> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breachlens.app/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code extension

> Surface BreachLens findings inline as you code, then go squiggly-to-merged-PR in four clicks.

The BreachLens VS Code extension is a thin client: no scanners run locally. It connects to your BreachLens API, paints findings as red squigglies on the exact lines that triggered them, and ties the lightbulb code action to the same auto-fix PR pipeline you use in the web UI.

<CardGroup cols={2}>
  <Card title="Squiggly to merged PR in 4 clicks" icon="wand-magic-sparkles">
    Lightbulb on a red squiggly → **Preview auto-fix** → review the side-by-side diff → **Apply fix → opens PR/MR**. The PR lands on GitHub or GitLab without leaving the editor.
  </Card>

  <Card title="Multi-AI BYOA" icon="sparkles">
    Patches are generated by your configured AI provider (Anthropic, OpenAI, Gemini, or Ollama). The extension never calls an AI directly - all generation runs server-side against the provider your org configured.
  </Card>
</CardGroup>

## Prerequisites

* **VS Code 1.85+** (or a fork that ships the same extension API - see [VS Code forks](#vs-code-forks))
* **Node 20+** on the host (the extension's `engines.node` floor)
* A running **BreachLens deployment** reachable from your workstation over HTTPS
* A **licensed** deployment - the extension calls `GET /api/system/license` on connect and refuses to surface findings if the deployment is unlicensed
* A **BreachLens API token** with the right scopes (see [Sign in](#sign-in-to-breachlens))

## Install

The extension ships as a signed `.vsix` today. A VS Code Marketplace listing is on the roadmap.

<Steps>
  <Step title="Get the VSIX">
    Download the signed `.vsix` from the link in your license email. Air-gapped deployments can ride the file through their normal data-diode pipeline - the signature lets your receiving security tooling verify publisher authenticity without internet access.
  </Step>

  <Step title="Install from VSIX">
    In VS Code, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **Extensions: Install from VSIX...**, then pick the downloaded file.

    Or from a terminal:

    ```bash theme={null}
    code --install-extension breachlens-vscode-X.Y.Z.vsix
    ```
  </Step>

  <Step title="Reload the window">
    The extension activates on `onStartupFinished`. A fresh window load is enough - no settings to touch yet.
  </Step>
</Steps>

## Sign in to BreachLens

<Steps>
  <Step title="Mint an API token in the web UI">
    In BreachLens, navigate to **Settings** → **API Tokens** → **Generate token**.

    For first-time pilots, mint a token with these four scopes:

    * `findings:read` - populate the tree view, squigglies, hover tooltips
    * `findings:write` - enable **Apply fix → opens PR/MR**
    * `scans:trigger` - enable **BreachLens: Scan current workspace now** and scan-on-save
    * `scans:read` - read scan status as it completes

    The plaintext `blt_…` token is shown once on creation. Copy it now; the UI stores only a SHA-256 hash.
  </Step>

  <Step title="Run BreachLens: Connect to BreachLens">
    In VS Code, Command Palette → **Connect to BreachLens**.

    Paste your BreachLens API base URL (for example `https://breachlens.acme.internal`), then the `blt_…` token. The token is stored in `vscode.SecretStorage` - never in `settings.json` - and the URL is stored as a machine-scoped setting so it never syncs through Settings Sync.

    VS Code reloads. The status bar shows `BreachLens` with a connection indicator and finding count.
  </Step>

  <Step title="Map workspace folders to BreachLens repos">
    Auto-detection reads `git remote get-url origin` for each workspace folder and matches against the repo's registered clone URL in BreachLens. Folders whose remote matches are auto-mapped.

    When auto-detection misses (forks, mirrors, monorepo subdirs, non-canonical clone URLs), Command Palette → **Select BreachLens repo for current workspace folder** and pick from the quickpick. The override is stored per-workspace.
  </Step>
</Steps>

## What you get

* **Red squigglies on findings.** By default every finding renders as an Error (red) regardless of severity - matching GitHub CodeQL's convention so visual weight drives triage. Switch to graded colours via `breachlens.squigglyMode`.
* **Hover tooltips** with title, severity, scanner, finding ID, CVE (when present), description, remediation, and a deep link to the BreachLens drawer for full context.
* **Lightbulb code actions** (`Ctrl+.` / `Cmd+.`) on every BreachLens diagnostic: **Preview auto-fix (side-by-side diff)** and **Apply auto-fix (opens PR/MR)**. The apply action is `isPreferred=true` so it floats to the top of the menu.
* **Side-by-side diff preview** with a three-button toolbar: **Apply fix → opens PR/MR**, **Discard fix preview**, **Regenerate fix**.
* **One-click "Generate fix now"** when no cached patch exists, and **Regenerate fix** when the cached patch has drifted out of sync with the source file. Both call the BreachLens API server-side; you stay in VS Code.
* **BreachLens activity-bar view** with a Findings tree for the connected workspace, plus inline actions to open the finding in your browser or trigger an auto-fix.
* **Problems panel integration.** Findings show up under the `BreachLens` source in `View → Problems` (`Ctrl+Shift+M`) alongside language-server diagnostics.
* **Status bar.** Connection state plus a per-workspace finding count. The bar tints yellow on HIGH and red on CRITICAL using VS Code's theme tokens, so it looks consistent across themes.

## Settings reference

All settings live under the `breachlens.*` namespace. Edit them in `settings.json` or via `File → Preferences → Settings`.

```jsonc settings.json theme={null}
{
  // Set via "Connect to BreachLens" - do not edit by hand unless the URL changed.
  // Machine-scoped: never synced through Settings Sync.
  "breachlens.apiUrl": "https://breachlens.acme.internal",

  // How often to poll for new findings. 0 disables auto-refresh
  // (manual only via the tree-view refresh button). Min 10. Default 60.
  "breachlens.refreshIntervalSeconds": 60,

  // How findings map to VS Code's severity ladder.
  //   "all-error" (default) - every finding renders red. Matches GitHub CodeQL.
  //   "severity"            - CRITICAL/HIGH=red, MEDIUM=yellow, LOW=blue, INFO=hint.
  "breachlens.squigglyMode": "all-error",

  // Fire a delta scan on every save in a mapped repo. Default false.
  // Requires an API token with the 'scans:trigger' scope.
  "breachlens.scanOnSave.enabled": false,

  // Wait this long after the last save before flushing the scan.
  // Higher = fewer scans during fast multi-file saves at the cost of
  // slower feedback. Min 0.5, max 30.
  "breachlens.scanOnSave.debounceSeconds": 2
}
```

The API token itself is never stored in `settings.json`. Run **BreachLens: Disconnect** to wipe it from SecretStorage.

## Scan-on-save (off by default)

`breachlens.scanOnSave.enabled` is `false` by default and stays that way for a reason: SAST + SCA + SECRET + IAC takes roughly 5-15s of scanner time per save. Running it on every keystroke-flush would compete with your local compile loop. This matches GitHub CodeQL's and Snyk's defaults - opt-in, not opt-out.

When you turn it on, the extension:

1. Buffers saves into a per-repo set
2. Resets a single shared debounce timer (default 2s) on every save
3. Flushes the bucket once the timer expires with no new saves
4. Skips repos with an inflight scan and re-queues the files for the next flush

So a burst of 30 saves from a formatter or find-and-replace coalesces into one scan with all 30 files in the `changedFiles` array. SCA always runs full because dependency graphs are not per-file.

Toggle it from the Command Palette via **Toggle scan-on-save**. The setting is written to Global scope so it follows you across workspaces.

<Warning>
  Scan-on-save needs a token with the `scans:trigger` scope. If your token lacks it, the extension toasts once per session and then drops silently - it will not spam you on every save.
</Warning>

## VS Code forks

The extension uses only the public VS Code extension API, so it sideloads cleanly into **Cursor**, **Windsurf**, **Antigravity**, and **Kiro**. Use the same `.vsix` and the same **Extensions: Install from VSIX...** command. Marketplace listings for each fork's market are roadmap.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;BreachLens: not connected&#x22; persists after Connect">
    Common causes: wrong API URL (typo, `http` vs `https`), token revoked or never created, network blocking the API host, or a self-signed TLS cert that VS Code does not trust. For corporate CAs, set `NODE_EXTRA_CA_CERTS` in your VS Code environment.
  </Accordion>

  <Accordion title="&#x22;BreachLens: license required&#x22; toast">
    The server-side license check failed. Your BreachLens admin needs to set `LICENSE_PUBLIC_KEY` and `LICENSE_KEY` in the deployment environment and restart. Verify with `curl -sf -H "Authorization: Bearer <token>" https://<your-api>/api/system/license`.
  </Accordion>

  <Accordion title="Tree view populated but no squigglies in the editor">
    The squigglies render only on files whose path matches what BreachLens scanned. If your local checkout has different relative paths (monorepo subdir mounted as workspace root, intermediate dirs missing), re-map the workspace folder via **Select BreachLens repo for current workspace folder**, or compare the file path shown in the finding drawer against your local layout.
  </Accordion>

  <Accordion title="&#x22;Open in BreachLens&#x22; lands on a 404">
    The server's `FRONTEND_URL` is misconfigured (pointing at the API URL, or a hostname that does not resolve). Your admin needs to set it to the web UI origin and restart the deployment.
  </Accordion>

  <Accordion title="Apply fix returns 403">
    Your API token is missing the `findings:write` scope. Mint a new token with the scope — the current UI requires revoke and remint rather than in-place scope edits.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="REST API" icon="code" href="/api">
    Drive BreachLens from CI pipelines and scripts. Token auth, three example calls.
  </Card>

  <Card title="Scan MCP servers" icon="plug" href="/mcp">
    Find prompt-injection, tool-poisoning, and token-theft risk in your AI-agent attack surface.
  </Card>

  <Card title="Authentication" icon="key" href="/auth">
    SSO, passkeys, multi-IdP per org. How operators sign in.
  </Card>

  <Card title="Need help?" icon="envelope" href="mailto:sales@breachlens.app">
    Email us for setup help, signed `.vsix` re-issues, or a Slack onboarding channel.
  </Card>
</CardGroup>