Skip to main content
This walks you through getting BreachLens running on your own machine, connecting your first GitHub repository, and seeing scan findings show up in the dashboard.
Want to see it in action before installing? Ask us for a demo — we’ll walk you through a real scan: findings, attack paths, and a proof-of-exploit replay. The docs also ship an interactive API playground you can point at your own deployment once you’re running.

​
Prerequisites

Before you begin, you must have:
  • Docker 24.0+ and Docker Compose v2
  • 8 GB RAM minimum (16 GB recommended for the pentest scanner tier)
  • 30 GB free disk space
  • Ports 5173 (web) and 3000 (api) free on your host
  • A license JWT from sales@breachlens.app (free for 30-day trial)

​
Install

1

Get your license

Email sales@breachlens.app with your company name and intended deployment. You’ll receive a license JWT and the signed EULA within one business day.
2

Pull the install bundle

BreachLens ships as a single tarball with docker-compose.yml + scanner images. Download from the link in your license email.
3

Set your license

Paste the license JWT into .env:
The license is verified at api startup — locally, with no phone-home. Without a valid license the platform still boots and core scanning stays available; the premium features are disabled (they return HTTP 402) until you apply one. See Licensing for the details.
4

Bring up the stack

First boot takes ~3 minutes (image pulls + database migrations + scanner warm-up). Watch the logs until the api healthcheck flips to healthy:
5

Create your owner account

On first boot — when no account exists yet — the api prints a one-time setup token to its logs. Grab it:
You’ll see a banner like:
Open https://localhost:5173/setup, paste the token, and fill in your name, work email, a strong password, your organization name, and your primary email domain (e.g. acme.com). Submitting creates the first owner account — a break-glass admin on a fresh team workspace.
Accept the certificate on both ports. With the default self-signed cert, your browser has to trust both https://localhost:5173 (web) and https://localhost:3000/health (api) — the setup form posts to the api on port 3000, and an untrusted cert there makes the submit fail silently. Open each URL once, accept the warning, then return to /setup.
The setup token works once and expires after 24 hours. To print a fresh one, restart the api: docker compose restart api. Once the first account exists, /setup closes permanently — there’s no second break-glass admin by design.
6

Enroll multi-factor authentication

Immediately after setup, BreachLens requires the owner to enroll MFA — an authenticator app (TOTP) or a passkey. Complete the prompt and you’ll land on the dashboard.From here on you sign in with the email + password you just set (plus MFA). You can add SSO and invite teammates later from Settings → Authentication.

​
Run your first scan

1

Install the BreachLens GitHub App

From the dashboard, open Repositories → Add repository and choose From GitHub. You’ll be prompted to install the BreachLens GitHub App on the org or account that owns the repos you want to scan. It requests read-only access to repository contents and metadata, plus write access to checks and pull requests (for PR gating and auto-fix PRs).When GitHub asks which repositories to grant, you choose the scope:

All repositories

Simplest. New repos appear in BreachLens automatically — connect once, never return to GitHub. Recommended for demos and most teams.

Only select repositories

Least privilege. You hand-pick which repos the App can see. To scan a new one later, add it to the installation on GitHub first — one click from the Manage on GitHub link in the Add-repository modal.
Granting access is not the same as scanning. The scope you choose only controls which repos appear in the picker — nothing is scanned until you add a repo in BreachLens and run a scan. “All repositories” is read-only and safe; scanning stays opt-in, one repo at a time.
2

Trigger a scan

Back in the BreachLens dashboard, navigate to Repositories, pick a connected repo, and click Run scan in the top-right.The default scan tier runs SAST + SCA + Secrets + IaC in parallel. For a typical small-to-medium repo, findings land in under a minute — roughly 15–45 seconds in our testing. Large monorepos take proportionally longer.
For the full walkthrough — every way to add a repo, the complete GitHub App permission matrix, PR gating, and how to also audit your account’s GitHub posture — see Scan a repository.
3

Triage findings

Navigate to Findings. Filter by Severity: Critical, High and Has attack path: yes to see what actually matters.Click any finding row to open the detail drawer — you’ll see the AI-suggested fix, reachability tier, attack-path context, and a one-click Generate auto-fix PR button.

​
Next steps

Add a domain target

Run DAST + autonomous pentest against a live web app. Capture proof-of-exploit videos.

Configure SSO

Wire Microsoft Entra ID, Okta, Auth0, Google Workspace, or Keycloak. Multi-IdP per org supported.

Bring your own AI

Plug Anthropic, OpenAI, Gemini, or Ollama for auto-fix and finding summarization.

Air-gap installation

Deploy in a disconnected network. Your code, findings, and AI inference stay in your network; provision offline mirrors for the scanner rules and vulnerability data.
Stuck? Reach out at sales@breachlens.app — every license customer gets a dedicated Slack channel during onboarding.