Merge pull request #2312 from s-ff/edit-explorer-landing-page

Edit explorer landing page
mandiant · Aug 23, 2024 · a5c14c3 · a5c14c3
2 parents 6c883f3 + 88a632c
commit a5c14c3
Show file tree

Hide file tree

Showing 9 changed files with 114 additions and 105 deletions.
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ capa detects capabilities in executable files.
 You run it against a PE, ELF, .NET module, shellcode file, or a sandbox report and it tells you what it thinks the program can do.
 For example, it might suggest that the file is a backdoor, is capable of installing services, or relies on HTTP to communicate.
 
-To interactively inspect capa results in your browser use the [capa web explorer](https://mandiant.github.io/capa/explorer/).
+To interactively inspect capa results in your browser use the [capa explorer web](https://mandiant.github.io/capa/explorer/).
 
 If you want to inspect or write capa rules, head on over to the [capa-rules repository](https://github.com/mandiant/capa-rules). Otherwise, keep reading.
 
@@ -89,12 +89,12 @@ Download stable releases of the standalone capa binaries [here](https://github.c
 
 To use capa as a library or integrate with another tool, see [doc/installation.md](https://github.com/mandiant/capa/blob/master/doc/installation.md) for further setup instructions.
 
-# web explorer
-The [capa web explorer](https://mandiant.github.io/capa/explorer/) enables you to interactively explore capa results in your web browser. Besides the online version you can download a standalone HTML file for local offline usage.
+# capa explorer web
+The [capa explorer web](https://mandiant.github.io/capa/explorer/) enables you to interactively explore capa results in your web browser. Besides the online version you can download a standalone HTML file for local offline usage.
 
-![capa web explorer screenshot](https://github.com/mandiant/capa/blob/master/doc/img/capa_web_explorer.png)
+![capa explorer web screenshot](https://github.com/mandiant/capa/blob/master/doc/img/capa_web_explorer.png)
 
-More details on the web UI is available in the [capa web explorer README](https://github.com/mandiant/capa/blob/master/web/explorer/README.md).
+More details on the web UI is available in the [capa explorer web README](https://github.com/mandiant/capa/blob/master/web/explorer/README.md).
 
 # example
 

diff --git a/web/explorer/DEVELOPMENT.md b/web/explorer/DEVELOPMENT.md
@@ -1,6 +1,6 @@
-# Development Guide for Capa Explorer Web
+# Development Guide for capa explorer web
 
-This guide will help you set up the Capa Explorer Web project for local development.
+This guide will help you set up the capa explorer web project for local development.
 
 ## Prerequisites
 
@@ -31,7 +31,7 @@ Before you begin, ensure you have the following installed:
     npm run dev
     ```
 
-    This will start the Vite development server. The application should now be running at `http://localhost:<port>`
+    This will start the Vite development server. The application should now be running at `http://localhost:<port>`.
 
 ## Project Structure
 
@@ -80,7 +80,7 @@ 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.
+This will generate an offline HTML bundle file in the `capa-explorer-web/` directory.
 
 ## Testing
 
@@ -98,12 +98,13 @@ We use ESLint for linting and Prettier for code formatting. Run the linter with:
 
 ```
 npm run lint
+npm run format:check
 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.
+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
 

diff --git a/web/explorer/README.md b/web/explorer/README.md
@@ -1,6 +1,6 @@
-# Capa Explorer Web
+# 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.
+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
 
@@ -11,31 +11,34 @@ Capa Explorer Web is a browser-based user interface for exploring program capabi
 
 ## 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.
+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/explorer) or running it locally by downloading the offline release from the top right-hand corner and opening it in your web browser.
 
-2. **Import capa Results**:
+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).
+      - You can generate the analysis document by running `capa.exe -j results.json sample.exe_`
     - Or, paste a URL to a capa JSON file and click the arrow button to load it.
+        - Like for the other import mechanisms, loading of both plain (`.json`) and GZIP compressed JSON (`.json.gz`) files is supported).
     - Alternatively, use the "Preview Static" or "Preview Dynamic" for sample data.
 
-3. **Explore the Results**:
+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.
+        - "Show distinct library rule matches" to include or exclude library rules.
+        - "Show columns filters" to show per-column search filters.
 
-4. **Interact with the Data**:
-    - Expand/collapse nodes in the table to see more details.
+4. **Interact with the results**:
+    - Expand/collapse nodes in the table to see more details by clicking rows or clicking arrow icons.
     - 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.
+    - Right click on rule names (and `match` nodes) 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.
+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).
+For developers interested in building or contributing to capa explorer web, please refer to our [Development Guide](DEVELOPMENT.md).
diff --git a/web/explorer/index.html b/web/explorer/index.html
@@ -4,7 +4,7 @@
         <meta charset="UTF-8" />
         <link rel="icon" href="/favicon.ico" />
         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>Capa Explorer</title>
+        <title>capa explorer web</title>
         <script defer src="https://cloud.umami.is/script.js" data-website-id="0bb8ff9e-fbcc-4ee2-9f9f-b337a2e8cc7f"></script>
     </head>
     <body>

diff --git a/web/explorer/src/components/DescriptionPanel.vue b/web/explorer/src/components/DescriptionPanel.vue
@@ -1,16 +1,46 @@
 <template>
-    <div class="flex flex-column align-items-center">
+    <div class="flex flex-column align-items-center mb-6">
         <div class="text-center">
             <h1>
                 <img src="@/assets/images/logo-full.png" alt="Capa: identify program capabilities" />
-                <h6 class="font-medium" style="color: rgb(176, 26, 26)">capa: identify program capabilities</h6>
+                <h3 class="font-medium" style="color: rgb(176, 26, 26)">capa: identify program capabilities</h3>
             </h1>
         </div>
         <div>
-            <p class="text-xl max-w-75rem" style="max-width: 75ch">
-                Capa-WebUI is a web-based tool for exploring the capabilities identified in a program. It can be used to
-                search and display the rule matches in different viewing modes.
+            <p class="text-xl p-3 max-w-75rem" style="max-width: 75ch">
+                capa explorer web is a web-based tool for exploring the capabilities identified in a program. It can be
+                used to search and display the rule matches in different viewing modes.
+            </p>
+        </div>
+        <div class="bg-blue-50 border-round p-3 pb-4 text-center max-w-75rem mt-4">
+            <p class="text-700 text-sm m-0">New to capa? Follow these quick steps to get started:</p>
+            <p class="text-700 text-sm mb-3"></p>
+            <ol class="text-left text-sm pl-4 mb-3">
+                <li class="mb-2">Install capa: <code>pip install flare-capa</code></li>
+                <li class="mb-2">Generate JSON output: <code>capa -j /path/to/file > result.json</code></li>
+                <li>Upload the JSON file here to explore the results</li>
+            </ol>
+            <p class="text-700 text-sm m-0">
+                For more detailed information, explore the
+                <a
+                    href="https://github.com/mandiant/capa"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    class="text-blue-600 hover:text-blue-800 transition-colors duration-200"
+                >
+                    capa GitHub repository</a
+                >.
             </p>
         </div>
     </div>
 </template>
+
+<style scoped>
+/* highlight inline code */
+code {
+    background-color: #e2e8f0;
+    padding: 2px 4px;
+    border-radius: 4px;
+    font-family: monospace;
+}
+</style>
diff --git a/web/explorer/src/components/MetadataPanel.vue b/web/explorer/src/components/MetadataPanel.vue
@@ -28,14 +28,14 @@
                 <span class="ml-2 mr-2 text-white-alpha-30"> • </span>
                 <span>{{ data.meta.analysis.arch === "i386" ? "i386" : data.meta.analysis.arch.toUpperCase() }}</span>
             </div>
-            <!-- Flavor • Extractor • CAPA Version • Timestamp -->
+            <!-- Flavor • Extractor • capa Version • Timestamp -->
             <div class="flex-wrap align-items-center text-sm m-0 line-height-3 text-white">
                 <span class="capitalize">
                     {{ flavor }} analysis with {{ data.meta.analysis.extractor.split(/(Feature)?Extractor/)[0] }}</span
                 >
                 <!--- Extractor (e.g., CapeExtractor -> Cape, GhidraFeatureExtractor -> Ghidra, ... etc) -->
                 <span class="mx-2 text-white-alpha-30"> • </span>
-                <span>CAPA v{{ data.meta.version }}</span>
+                <span>capa v{{ data.meta.version }}</span>
                 <span class="mx-2 text-white-alpha-30"> • </span>
                 <span>{{ new Date(data.meta.timestamp).toLocaleString() }}</span>
             </div>

diff --git a/web/explorer/src/components/NavBar.vue b/web/explorer/src/components/NavBar.vue
@@ -17,10 +17,10 @@ const isBundle = import.meta.env.MODE === "bundle";
                 <a
                     v-if="!isBundle"
                     v-ripple
-                    v-tooltip.bottom="'Download capa Explorer Web for offline usage'"
-                    href="./capa-explorer-web.zip"
+                    v-tooltip.bottom="'Download capa explorer web for offline usage'"
+                    href="capa-explorer-web.zip"
                     download="capa-explorer-web.zip"
-                    aria-label="Download capa Explorer Web release"
+                    aria-label="Download capa explorer web release"
                 >
                     <i class="pi pi-download text-xl"></i>
                 </a>

diff --git a/web/explorer/src/components/UploadOptions.vue b/web/explorer/src/components/UploadOptions.vue
@@ -1,70 +1,58 @@
 <template>
-    <Card>
-        <template #content>
-            <div class="flex flex-wrap align-items-center justify-content-center gap-3">
-                <div class="flex-grow-1 flex align-items-center justify-content-center">
-                    <FileUpload
-                        mode="basic"
-                        name="model[]"
-                        accept=".json,.gz"
-                        :max-file-size="10000000"
-                        :auto="true"
-                        :custom-upload="true"
-                        choose-label="Upload from local"
-                        @uploader="$emit('load-from-local', $event)"
-                    />
-                </div>
+    <div class="flex flex-wrap align-items-center justify-content-center gap-3 mb-6">
+        <div class="flex-grow-1 flex align-items-center justify-content-center">
+            <FileUpload
+                mode="basic"
+                name="model[]"
+                accept=".json,.gz"
+                :max-file-size="10000000"
+                :auto="true"
+                :custom-upload="true"
+                choose-label="Upload from local"
+                @uploader="$emit('load-from-local', $event)"
+            />
+        </div>
 
-                <Divider layout="vertical" class="hidden-mobile">
-                    <b>OR</b>
-                </Divider>
-                <Divider layout="horizontal" class="visible-mobile" align="center">
-                    <b>OR</b>
-                </Divider>
-
-                <div class="flex-grow-1 flex align-items-center justify-content-center gap-2">
-                    <FloatLabel>
-                        <InputText id="url" type="text" v-model="loadURL" />
-                        <label for="url">Load from URL</label>
-                    </FloatLabel>
-                    <Button icon="pi pi-arrow-right" @click="$emit('load-from-url', loadURL)" :disabled="!loadURL" />
-                </div>
-                <template v-if="!isBundle">
-                    <Divider layout="vertical" class="hidden-mobile">
-                        <b>OR</b>
-                    </Divider>
-                    <Divider layout="horizontal" class="visible-mobile" align="center">
-                        <b>OR</b>
-                    </Divider>
+        <div class="hidden-mobile">
+            <b>OR</b>
+        </div>
+        <Divider layout="horizontal" class="visible-mobile" align="center">
+            <b>OR</b>
+        </Divider>
+        <div class="flex-grow-1 flex align-items-center justify-content-center gap-2">
+            <FloatLabel>
+                <InputText id="url" type="text" v-model="loadURL" />
+                <label for="url">Load from URL</label>
+            </FloatLabel>
+            <Button icon="pi pi-arrow-right" @click="$emit('load-from-url', loadURL)" :disabled="!loadURL" />
+        </div>
+        <template v-if="!isBundle">
+            <div class="hidden-mobile">
+                <b>OR</b>
+            </div>
+            <Divider layout="horizontal" class="visible-mobile" align="center">
+                <b>OR</b>
+            </Divider>
+            <div class="flex-grow-1 flex align-items-center justify-content-center">
+                <Button label="Preview Static" @click="router.push({ path: '/', query: { rdoc: staticURL } })" />
+            </div>
 
-                    <div class="flex-grow-1 flex align-items-center justify-content-center">
-                        <Button
-                            label="Preview Static"
-                            @click="router.push({ path: '/', query: { rdoc: staticURL } })"
-                        />
-                    </div>
+            <div class="hidden-mobile">
+                <b>OR</b>
+            </div>
+            <Divider layout="horizontal" class="visible-mobile" align="center">
+                <b>OR</b>
+            </Divider>
 
-                    <Divider layout="vertical" class="hidden-mobile">
-                        <b>OR</b>
-                    </Divider>
-                    <Divider layout="horizontal" class="visible-mobile" align="center">
-                        <b>OR</b>
-                    </Divider>
-                    <div class="flex-grow-1 flex align-items-center justify-content-center">
-                        <Button
-                            label="Preview Dynamic"
-                            @click="router.push({ path: '/', query: { rdoc: dynamicURL } })"
-                        />
-                    </div>
-                </template>
+            <div class="flex-grow-1 flex align-items-center justify-content-center">
+                <Button label="Preview Dynamic" @click="router.push({ path: '/', query: { rdoc: dynamicURL } })" />
             </div>
         </template>
-    </Card>
+    </div>
 </template>
 
 <script setup>
 import { ref } from "vue";
-import Card from "primevue/card";
 import FileUpload from "primevue/fileupload";
 import Divider from "primevue/divider";
 import FloatLabel from "primevue/floatlabel";

diff --git a/web/explorer/src/main.js b/web/explorer/src/main.js
@@ -30,26 +30,13 @@ import { definePreset } from "@primevue/themes";
 
 const Noir = definePreset(Aura, {
     semantic: {
-        primary: {
-            50: "{zinc.50}",
-            100: "{zinc.100}",
-            200: "{zinc.200}",
-            300: "{zinc.300}",
-            400: "{zinc.400}",
-            500: "{zinc.500}",
-            600: "{zinc.600}",
-            700: "{zinc.700}",
-            800: "{zinc.800}",
-            900: "{zinc.900}",
-            950: "{zinc.950}"
-        },
         colorScheme: {
             light: {
                 primary: {
                     color: "{slate.800}",
                     inverseColor: "#ffffff",
-                    hoverColor: "{zinc.900}",
-                    activeColor: "{zinc.800}"
+                    hoverColor: "{sky.800}",
+                    activeColor: "{sky.800}"
                 }
             }
         }