BugHunter VS Code Extension (Full Version 2.0)

BugHunter is the VS Code integration for running BugHunter security analysis directly from the development environment.

This document covers setup, usage, feature behavior, and troubleshooting.

1. Scope and Version

• Product area: VS Code extension integration for BugHunter.
• Intended version scope: full version (2.0) usage model.
• Core outcome: run analysis from VS Code, review findings, open report PDFs, and manage repeated runs.

2. Prerequisites

Before using the extension, ensure all of the following are available:

1. VS Code 1.107.0 or newer.
2. A BugHunter account.
3. A valid BugHunter API key.
4. Internet access to BugHunter backend services.
5. A folder-based VS Code workspace (at least one workspace folder).

3. Installation

1. Install BugHunter from your private marketplace feed or from a .vsix package.
2. If using .vsix: open Command Palette and run Extensions: Install from VSIX....
3. Reload VS Code after installation.
4. Open the BugHunter icon in the Activity Bar.

Figure 1. VS Code window showing the BugHunter icon in the Activity Bar and the “Project Analysis” sidebar open.

4. Generate and Store API Key

Generate key in dashboard

1. Go to https://app.bughunter.live and sign in.
2. Open API Keys in the dashboard.
3. Create a key and copy it immediately.
4. Store it securely. Full key display is one-time.

Figure 2. Bug Hunter Dashboard API Key generation interface.

Set key in VS Code

1. In BugHunter sidebar, click Set key, or run BugHunter: Set API Key.
2. Paste the key in the secure prompt.
3. If valid, the Key pill changes to OK.

Key validation behavior:

• Key must start with bh_.
• Key must include at least 4 underscore-separated segments.
• Invalid format is rejected with an error.

Figure 3. Sidebar API Status section before and after setting a key, showing Key: Missing turning into Key: OK..

5. Quick Start (First Analysis)

1. Open a workspace folder you want to scan.
2. Open BugHunter sidebar.
3. Confirm the Key pill is OK.
4. In Project, choose the target folder.
5. Wait for usage to load. If your plan allows analysis, Analyze Full Project becomes enabled.
6. Click Analyze Full Project.
7. Track status changes in the Status section.
8. When status is Completed and Open PDF is enabled, click it to open report.
9. Click findings to inspect details and open exact code locations.

6. Sidebar UI Reference

6.1 API Status Section

• Set key button: opens secure API key input flow.
• Endpoint pill:
  • OK: API base URL is resolved.
  • Missing: endpoint unavailable.
• Key pill:
  • OK: stored key exists.
  • Missing: no key in SecretStorage.

6.2 Project Section

• Project dropdown lists current workspace folders.
• Each option shows FolderName - FullPath.
• If no workspace folders are open, dropdown is disabled and shows No workspace folders.

6.3 Recent Runs Section

• Refresh button reloads run history.
• Run dropdown entries use: ProjectName - Status - LocalTimestamp.
• Selecting an entry loads its current job/report status.

6.4 Status Section

• Status pill shows current pipeline state.
• Job shows submission/job identifier.
• Status message line explains current phase or error detail.

6.5 Action Buttons Section

• Analyze Full Project: starts full analysis for selected project.
• Open PDF: opens report PDF in browser when available.
• Cancel: visible only during a short cancel window after queueing.
• Clear: resets sidebar state to idle and removes displayed findings/diagnostics.

6.6 Findings Section

• Shows findings list after report retrieval.
• Each finding includes severity pill, title, and location (file:line or Summary finding).
• Clicking a finding opens a details panel.

6.7 Help Section

• Docs: opens documentation site.
• Contact support: opens BugHunter support page.

Figure 4. Sidebar where each area is numbered: API Status, Project, Recent Runs, Status, Action Buttons, Findings, Help.

7. System Status Labels and What They Mean

Canonical system statuses:

Status label	Meaning	User action
Queued	Job accepted and waiting for review or execution.	Optional: cancel if available.
In Review	Analysis is actively being processed.	Wait for completion.
Completed	Run finished and report/findings are available.	Review findings and open PDF.
Failed	Run or retrieval failed.	Check message, troubleshoot, retry.
Cancelled	Job cancellation succeeded or backend reported cancelled.	Start a new run if needed.

Local extension progress notes (non-canonical system states):

• During packaging, upload, and report retrieval, the extension can temporarily show local progress labels/messages.
• Active processing may appear as Running in the extension UI while the canonical system state is In Review.
• Treat these as client-side progress steps, not backend lifecycle states.

8. Buttons and Controls Reference

Control	Location	Enabled/Visible when	What it does
Set key	API Status	Always visible	Opens secure prompt to save API key.
Analyze Full Project	Actions	API key exists + usage allows analysis + project selected	Starts full scan pipeline.
Open PDF	Actions	A report PDF URL is available	Opens report PDF in browser.
Cancel	Actions	Visible only before cancel deadline (~10s after queue)	Sends cancel request for current job.
Clear	Actions	Always visible	Resets sidebar to Idle, clears findings and diagnostics.
Refresh	Recent Runs	Always visible	Reloads recent runs from backend.
Project dropdown	Project	Enabled if workspace has folders	Selects folder to analyze.
Run dropdown	Recent Runs	Always visible	Loads a previous run by submission ID (if selected).
Docs	Help	Always visible	Opens docs site.
Contact support	Help	Always visible	Opens support page.
Open location	Finding details panel	Enabled for file-based findings (not summary-only)	Opens source file at finding line in editor.

9. Findings and Severity Meaning

Severity rendering in UI:

• High / Critical: red pill.
• Medium: yellow pill.
• Low / Info: green pill.

Finding behavior:

1. Click finding in sidebar to open a dedicated details panel.
2. In details panel, click Open location to jump to the file and line.
3. Summary-only findings (__summary__) show context but cannot open a file location.

If a completed run has zero findings, sidebar shows:

• Congratulations! No vulnerabilities found.

Figure 5. Left side BugHunter findings list with multiple severities, right side finding details panel.

10. Command Palette and Context Menu Commands

Available commands:

• BugHunter: Analyze Full Project
• BugHunter: Set API Key
• BugHunter: Clear API Key
• BugHunter: Refresh Usage
• BugHunter: Open Billing
• BugHunter: Open Docs
• BugHunter: Contact Support
• BugHunter: Analyze This Folder (Explorer folder context menu)

11. Troubleshooting

API / Auth

Symptom	Likely cause	Resolution
Key pill stays Missing	Key not set or was cleared	Run BugHunter: Set API Key and store valid key.
Error: key format invalid	Input is not a valid BugHunter key format	Use a key starting with bh_ and generated from dashboard.
401 or 403 responses	Revoked or expired key	Create a new key, set it again.

Project / Workspace

Symptom	Likely cause	Resolution
Analyze button disabled	Missing key, no selected project, or usage blocks analysis	Confirm key, select project, check plan usage.
Open a project folder first error	No workspace folder is open	Open folder/workspace, then retry.
Selected project error	Folder was removed from workspace	Re-select a valid workspace folder in Project dropdown.

Run Lifecycle

Symptom	Likely cause	Resolution
Cancel not available	Cancel window expired	Start a new run and cancel quickly if needed.
Failed after completion attempt	Report fetch failed or backend error	Use Refresh in runs; retry analysis if needed.
Status stuck on old run	Different run selected	Use Recent Runs dropdown to load desired run.

Size / Packaging

Symptom	Likely cause	Resolution
Archive too large error	Zipped project exceeds 150 MB client limit	Remove large generated files/folders and retry.
Important file missing in scan	File excluded by packaging rules	Check excluded directories and workspace layout.

Excluded from zip by default:

• .git, node_modules, .vscode, artifacts, cache, out, dist, build, coverage
• *.log files

Usage / Billing

Symptom	Likely cause	Resolution
Status Blocked	Quota, concurrency, or inactive plan	Open billing from prompt/command and resolve plan state.
Analyze unavailable despite key	Usage precheck failed	Refresh usage and retry when usage endpoint is reachable.

12. Security and Data Handling

• API keys are stored in VS Code SecretStorage (not plaintext settings).
• Production extension mode uses authenticated HTTPS requests (https://api.bughunter.live).
• Local temporary zip is deleted after upload attempt.
• File-based findings can be mapped to VS Code diagnostics via internal command flow.

13. Help and Support

• Screenshots and visual walkthroughs are published in the website docs.
• Documentation: https://docs.bughunter.live/
• Dashboard: https://app.bughunter.live
• Support: https://app.bughunter.live/dashboard/contact

License

This extension is proprietary software. Refer to LICENSE.txt included with the extension package.