Skip to main content
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.

Squiggly to merged PR in 4 clicks

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.

Multi-AI BYOA

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.

​
Prerequisites

  • VS Code 1.85+ (or a fork that ships the same extension API - see 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)

​
Install

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

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.
2

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:
code --install-extension breachlens-vscode-X.Y.Z.vsix
3

Reload the window

The extension activates on onStartupFinished. A fresh window load is enough - no settings to touch yet.

​
Sign in to BreachLens

1

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.
2

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.
3

Map workspace folders to BreachLens repos

Auto-detection reads git remote get-url origin for each workspace folder and matches against Repository.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.

​
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. 
{
  // 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.
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.

​
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

“BreachLens: not connected” 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 Node does not trust. For corporate CAs, set NODE_EXTRA_CA_CERTS in your VS Code environment.
“BreachLens: license required” toast. The server-side license check failed. Your BreachLens admin needs to set LICENSE_PUBLIC_KEY and LICENSE_KEY on the api and restart it. Verify with curl -sf -H "Authorization: Bearer <token>" https://<your-api>/api/system/license.
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 Finding.filePath in the drawer against your local layout.
“Open in BreachLens” 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 React UI origin and restart the api.
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.

​
Next steps

REST API

Drive BreachLens from CI pipelines and scripts. Token auth, three example calls.

Scan MCP servers

Find prompt-injection, tool-poisoning, and token-theft risk in your AI-agent attack surface.

Authentication

SSO, passkeys, multi-IdP per org. How operators sign in.

Need help?

Email hi@breachlens.app for setup help, signed .vsix re-issues, or a Slack onboarding channel.