Merge pull request #2224 from s-ff/webui

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"]
+}