initial release of Capa Explorer Web

.github/workflows/deploy-webui.yml

@@ -0,0 +1,66 @@
+name: deploy Capa Explorer Web to Github Pages
+
+on:
+ # Runs on pushes targeting the webui branch
+ push:
+ branches: [ master ]
+ paths:
+ - 'web/explorer/**'
+
+ # Allows to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+ group: 'pages'
+ cancel-in-progress: true
+
+jobs:
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ submodules: 'recursive'
+ fetch-depth: 1
+ show-progress: true
+ - name: Set up Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: 'npm'
+ cache-dependency-path: './web/explorer/package-lock.json'
+ - name: Install dependencies
+ run: npm ci
+ working-directory: ./web/explorer
+ - name: Lint
+ run: npm run lint
+ working-directory: ./web/explorer
+ - name: Format
+ run: npm run format:check
+ working-directory: ./web/explorer
+ - name: Run unit tests
+ run: npm run test
+ working-directory: ./web/explorer
+ - name: Build
+ run: npm run build
+ working-directory: ./web/explorer
+ - name: Setup Pages
+ uses: actions/configure-pages@v4
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: './web/explorer/dist'
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4

.github/workflows/web-tests.yml

@@ -0,0 +1,42 @@
+name: Capa Explorer Web tests 
+
+on:
+ pull_request:
+ branches: [ master ]
+ paths:
+ - 'web/explorer/**'
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ with:
+ submodules: 'recursive'
+ fetch-depth: 1
+ show-progress: true
+
+ - name: Set up Node
+ uses: actions/setup-node@v3
+ with:
+ node-version: 20
+ cache: 'npm'
+ cache-dependency-path: './web/explorer/package-lock.json'
+
+ - name: Install dependencies
+ run: npm ci
+ working-directory: ./web/explorer
+
+ - name: Lint
+ run: npm run lint
+ working-directory: ./web/explorer
+
+ - name: Format
+ run: npm run format:check
+ working-directory: ./web/explorer
+
+ - name: Run unit tests
+ run: npm run test
+ working-directory: ./web/explorer

CHANGELOG.md

@@ -3,8 +3,11 @@
 ## master (unreleased)
 
 ### New Features
+
+- webui: explore capa analysis results in a web-based UI online and offline #2224 @s-ff
 - support analyzing DRAKVUF traces #2143 @yelhamer
 
+
 ### Breaking Changes
 
 ### New Rules (2)

web/explorer/.eslintrc.cjs

@@ -0,0 +1,13 @@
+/* eslint-env node */
+require("@rushstack/eslint-patch/modern-module-resolution");
+
+module.exports = {
+ root: true,
+ extends: ["plugin:vue/vue3-essential", "eslint:recommended", "@vue/eslint-config-prettier/skip-formatting"],
+ parserOptions: {
+ ecmaVersion: "latest"
+ },
+ rules: {
+ "vue/multi-word-component-names": "off"
+ }
+};

web/explorer/.gitignore

@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Dependencies, build results, and other generated files
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.vscode
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# TypeScript incremental build info
+*.tsbuildinfo

web/explorer/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+ "$schema": "https://json.schemastore.org/prettierrc",
+ "semi": true,
+ "tabWidth": 4,
+ "singleQuote": false,
+ "printWidth": 120,
+ "trailingComma": "none"
+}

web/explorer/DEVELOPMENT.md

@@ -0,0 +1,123 @@
+# Development Guide for Capa Explorer Web
+
+This guide will help you set up the Capa Explorer Web project for local development.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- Node.js (v20.x or later recommended)
+- npm (v10.x or later)
+- Git
+
+## Setting Up the Development Environment
+
+1. Clone the repository:
+
+ ```
+ git clone https://github.com/mandiat/capa.git
+ cd capa/web/explorer
+ ```
+
+2. Install dependencies:
+
+ ```
+ npm install
+ ```
+
+3. Start the development server:
+
+ ```
+ npm run dev
+ ```
+
+ This will start the Vite development server. The application should now be running at `http://localhost:<port>`
+
+## Project Structure
+
+```
+web/exporer/
+├── src/
+│ ├── assets/
+│ ├── components/
+│ ├── composables/
+│ ├── router/
+│ ├── utils/
+│ ├── views/
+│ ├── App.vue
+│ └── main.js
+├── public/
+├── tests/
+├── index.html
+├── package.json
+├── vite.config.js
+├── DEVELOPMENT.md
+└── README.md
+```
+
+- `src/`: Contains the source code of the application
+- `src/components/`: Reusable Vue components
+- `src/composables/`: Vue composition functions
+- `src/router/`: Vue Router configuration
+- `src/utils/`: Utility functions
+- `src/views/`: Top-level views/pages
+- `src/tests/`: Test files
+- `public/`: Static assets that will be served as-is
+
+## Building for Production
+
+To build the application for production:
+
+```
+npm run build
+```
+
+This will generate production-ready files in the `dist/` directory.
+
+Or, you can build a standalone bundle application that can be used offline:
+
+```
+npm run build:bundle
+```
+
+This will generate an offline HTML bundle file in the `dist/` directory.
+
+## Testing
+
+Run the test suite with:
+
+```
+npm run test
+```
+
+We use Vitest as our testing framework. Please ensure all tests pass before submitting a pull request.
+
+## Linting and Formatting
+
+We use ESLint for linting and Prettier for code formatting. Run the linter with:
+
+```
+npm run lint
+npm run format
+```
+
+## Working with PrimeVue Components
+
+Capa Explorer Web uses the PrimeVue UI component library. When adding new features or modifying existing ones, refer to the [PrimeVue documentation](https://primevue.org/vite) for available components and their usage.
+
+## Best Practices
+
+1. Follow the [Vue.js Style Guide](https://vuejs.org/style-guide/) for consistent code style.
+2. Document new functions, components, and complex logic.
+3. Write tests for new features and bug fixes.
+4. Keep components small and focused on a single responsibility.
+5. Use composables for reusable logic across components.
+
+## Additional Resources
+
+- [Vue.js Documentation](https://vuejs.org/guide/introduction.html)
+- [Vite Documentation](https://vitejs.dev/guide/)
+- [Vitest Documentation](https://vitest.dev/guide/)
+- [PrimeVue Documentation](https://www.primevue.org/)
+
+If you encounter any issues or have questions about the development process, please open an issue on the GitHub repository.

web/explorer/README.md

@@ -0,0 +1,41 @@
+# Capa Explorer Web
+
+Capa Explorer Web is a browser-based user interface for exploring program capabilities identified by capa. It provides an intuitive and interactive way to analyze and visualize the results of capa analysis.
+
+## Features
+
+- **Import capa Results**: Easily upload or import capa JSON result files.
+- **Interactive Tree View**: Explore and filter rule matches in a hierarchical structure.
+- **Function Capabilities**: Group and filter capabilities by function for static analysis.
+- **Process Capabilities**: Group capabilities by process for dynamic analysis.
+
+## Getting Started
+
+1. **Access the Application**: Open Capa Explorer Web in your web browser.
+ You can start using Capa Explorer Web by accessing [https://mandiant.github.io/capa](https://mandiant.github.io/capa/) or running it locally by dowloading the offline release in the [releases](https://github.com/mandiant/capa/releases) section and loading it in your browser.
+
+2. **Import capa Results**:
+
+ - Click on "Upload from local" to select a capa analysis document file from your computer (with a version higher than 7.0.0).
+ - Or, paste a URL to a capa JSON file and click the arrow button to load it.
+ - Alternatively, use the "Preview Static" or "Preview Dynamic" for sample data.
+
+3. **Explore the Results**:
+
+ - Use the tree view to navigate through the identified capabilities.
+ - Toggle between different views using the checkboxes in the settings panel:
+ - "Show capabilities by function/process" for grouped analysis.
+ - "Show library rule matches" to include or exclude library rules.
+
+4. **Interact with the Data**:
+ - Expand/collapse nodes in the table to see more details.
+ - Use the search and filter options to find specific features, functions or capabilities (rules).
+ - Right click on rule names to view their source code or additional information.
+
+## Feedback and Contributions
+
+We welcome your feedback and contributions to improve the web-based Capa Explorer. Please report any issues or suggest enhancements through the `capa` GitHub repository.
+
+---
+
+For developers interested in building or contributing to Capa Explorer WebUI, please refer to our [Development Guide](DEVELOPMENT.md).

web/explorer/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" href="/public/favicon.ico" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Capa Explorer</title>
+ </head>
+ <body>
+ <div id="app"></div>
+ <script type="module" src="/src/main.js"></script>
+ </body>
+</html>

web/explorer/jsconfig.json

@@ -0,0 +1,8 @@
+{
+ "compilerOptions": {
+ "paths": {
+ "@/*": ["./src/*"]
+ }
+ },
+ "exclude": ["node_modules", "dist"]
+}