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 running first without installing? The live demo at aurora.breachlens.dev has DVWA and WebGoat pre-connected. Sign in with GitHub and explore.

​
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 hi@breachlens.app (free for 30-day trial)

​
Install

1

Get your license

Email hi@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.
tar xzf breachlens-2026.06.tar.gz
cd breachlens
3

Set your license

Paste the license JWT into .env:
cp .env.example .env
echo "LICENSE_JWT=eyJhbGciOiJSUzI1NiIs..." >> .env
The license is verified at api startup. Tampering with it (or running without one) prevents the api from booting. See License enforcement for the runtime check.
4

Bring up the stack

docker compose up -d
First boot takes ~3 minutes (image pulls + Prisma migrate + scanner warm-up). Watch the logs until the api healthcheck flips to healthy:
docker compose logs -f api
5

Open the web UI

Visit https://localhost:5173. You’ll see the first-login wizard. Accept the self-signed cert warning — BreachLens uses an internal CA in dev mode.Sign in with GitHub, then accept the auto-created PERSONAL organization.

​
Run your first scan

1

Install the BreachLens GitHub App

From the onboarding wizard, click Connect GitHub. You’ll be redirected to install the BreachLens GitHub App on your org or personal account.Pick the repos you want to scan. The minimum scopes are read-only on contents and metadata.
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. Expect findings within 30–90 seconds for a typical repo.
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

Run BreachLens fully offline. Sync vulnerability databases via signed tarballs over the egress verification pack.
Stuck? Reach out at hi@breachlens.app — every license customer gets a dedicated Slack channel during onboarding.