How to use Pepper

Day-to-day workflows: scans, projects, GitHub, and remediation.

Dashboard

Route /dashboard

Organization overview: finding counts by severity, recent projects, activity feed, and shortcuts to start a scan. Use New Scan from the sidebar or embedded dialog to queue work quickly.

New Security Scan

Route /scans/new

Steps

Choose or create a project (container for scans and build gates).
Select scan type: Full, SAST only, SCA only, or Secrets only.
Pick a source:
- Repository — GitHub/GitLab HTTPS clone URL and optional branch.
- Upload — .zip, .tar, .tar.gz, or .tgz archive.
Submit. The scan is created and enqueued; the worker picks it up when running.

Git clone without pasting a token

If GitHub is connected under Repositories, private GitHub URLs clone using your org OAuth token. The personal access token field is hidden on the new-scan form when OAuth is active.

SVN

SVN scans are created via the API with sourceType: SVN_CHECKOUT. The worker needs the svn binary installed. See README for examples.

Projects

Route /projects, /projects/[id]

Each project holds scans, optional repoUrl, default branch, and GitHub metadata when imported.
Project cards show security grade and open finding counts.
Project settings (/projects/[id]/settings) — edit name and description only.
Build gate summary appears on the project page when configured.

Repositories (GitHub)

Route /repositories

Connect GitHub

Click Connect GitHub (or use Settings → Integrations).
Authorize the OAuth app on GitHub (read:user and repo scopes).
Return to Pepper — status shows your GitHub username.

Import repositories

Picker — Select repos from your GitHub account; Pepper creates/links projects and queues an initial full scan.
Add repository by URL — Enter owner/repo or https://github.com/owner/repo for any repo your account can access (not only the picker list).

Configure OAuth in .env: GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, callback {NEXTAUTH_URL}/api/integrations/github/callback.

Scan detail

Route /scans/[scanId]

Live status while QUEUED, RUNNING, or PAUSED.
Pause / Resume / Stop / Cancel for active scans.
Rescan from the scans list to run again on the same project.
Findings grouped by scanner family (SAST, Secrets, SCA, IaC, Zero-Day).
Filter by severity and scanner type.
Export findings as CSV or HTML report.
Download artifacts (e.g. SBOM) when produced.

Working with findings

Click a row to expand the detail panel.

Suggest fix — LLM-generated summary, developer steps, optional unified diff (read-only guidance).
Open fix PR — Creates a GitHub branch, commits an LLM-rewritten file, opens a pull request (see below).
Status — Mark Open, Confirmed, False positive, Accepted risk, Fixed.
View on GitHub — Line link when the scan has a GitHub repo context.

Open fix PR

Automated remediation workflow tied to GitHub OAuth (no PAT required when connected).

Requirements

GitHub connected for your organization.
LLM API key configured (org Settings → LLM or LLM_API_KEY / OPENROUTER_API_KEY in env).
Finding must have a file path.
A GitHub repository linked to the project or scan, or you provide owner/repo when prompted.
Your GitHub user must have push (write) access to that repository.

Flow

Click Open fix PR on a finding.
Confirm the dialog (explains that Pepper fetches the file from GitHub and uses the LLM).
If GitHub is not connected, you are redirected to OAuth and returned to the scan with ?github=connected&openPr={findingId}.
If the scan has no GitHub repo, enter owner/repo or a GitHub URL when prompted.
Pepper creates branch pepper-security-…, commits the fix, opens a PR. A link opens in a new tab.

Common errors

Not Found — File path does not exist on GitHub at that branch, or wrong repo for an upload scan.
Cannot push — You can read a public repo but cannot create branches (use your fork or a repo you own).
Failed to create branch — No write access, org SAML SSO not authorized, or branch naming rules on the repo.

Compliance mapping

Route /scans/[scanId]/compliance

Maps findings to framework themes (e.g. OWASP, PCI). Refresh and export from the compliance page after the scan completes.

Notifications

Route /notifications (also via top bar)

In-app notifications for scan completion and gate failures. Email requires SMTP in environment and per-user preferences.

CI / API scanning

Trigger scans from CI using POST /api/scans with an API key. Copy the webhook URL and example from Settings → Integrations.