Concepts

This page explains the vocabulary SecretsBuster uses across the dashboard, the API, and the GitHub Action. Read this first if a term elsewhere in the docs is unclear.

Target

A target is a single URL you want SecretsBuster to scan, e.g. https://app.example.com/login. Adding a target (via the dashboard, the API, or the GitHub Action) doesn't scan it by itself — it registers the URL so you can scan it now or on a schedule. Each scan of a target produces a new report.

A target keeps track of its most recent scan result and scan date, so you can see at a glance whether it's SAFE, LEAKY, ERROR, or has never been scanned.

Domain

Targets are automatically grouped into domains based on their registrable domain name (e.g. both https://app.example.com and https://www.example.com fall under the example.com domain; a target whose host is a bare IP address is grouped under that IP). You don't create domains directly — adding a target to a new domain creates it automatically. Domains give you a way to browse targets by the site they belong to instead of one long flat list.

Scan and Report

A scan is the process of crawling a target URL and the resources it loads — JavaScript files, network requests, and other public resources — looking for leaked secrets. SecretsBuster uses a real browser to load the page and execute its JavaScript, so it sees the same requests and scripts an attacker's browser would.

Every scan produces a report. A report moves through the following states as it's processed:

State	Meaning
QUEUED	The scan request was accepted and is waiting to be processed.
CRAWLING	The target and its resources are actively being crawled.
CRAWLED	Crawling finished. The report now has a scan result and findings, if any.
ERROR	Something prevented the scan from completing (see below).

Scanning is asynchronous: creating a report returns immediately with the report in QUEUED state, and you check back later (by polling in the API, refreshing the dashboard, or via the GitHub Action, which polls for you) once it reaches CRAWLED or ERROR. A scan typically takes between 10 and 30 seconds, depending on load and how many resources the target loads.

Scan Result

Once a report finishes, it's assigned one of three scan results:

• SAFE — no secrets were found in the target or any of its associated resources.
• LEAKY — at least one secret was found. The report's findings list which document(s) leaked what.
• ERROR — the target couldn't be scanned (e.g. it was unreachable, or an internal error occurred). An error scan result is distinct from a document-level error: if one associated resource fails to load but the target URL itself is scanned successfully, the report can still be SAFE or LEAKY.

Secrets and Leaks

When a report is LEAKY, its findings are organized by the document (URL) they were found in. For each leaky document, SecretsBuster lists every detected secret: its type (e.g. "AWS Access Key", "Stripe API Key"), its value, and how many times it occurred in that document. A single document can leak more than one secret, and the same secret can appear more than once.

See Understanding Scan Results for how to read validation and confidence information attached to each finding.

Validation

For secret types SecretsBuster has a validator for, each detected secret is automatically tested against its provider's real API right after the scan completes. This tells you whether the credential is still active, rather than leaving that question for you to check by hand. See Live Validation for the possible outcomes.

Confidence Score

Every detected secret also gets a true positive confidence score, estimating how likely it is to be a real credential rather than a placeholder, example, or test value pulled from documentation. This is what keeps <YOUR_API_KEY_HERE> from cluttering your findings the same way a real key would. See Confidence Scoring for details.

Duplicates

If the exact same secret value is found across more than one report, SecretsBuster flags it as a duplicate and links the other reports where it appeared. A credential that's hard-coded and shows up consistently across scans is a different — usually higher-priority — problem than one that appeared once.

Review and Triage

A LEAKY or ERROR report can be reviewed: you leave a comment and, for leaky reports, assign a triage category — TRUE_POSITIVE, FALSE_POSITIVE, or DUPLICATE — to record what you decided about it. Reviewing sets a review date and category so your team has a record of what's been triaged and what's still open. A review can be reopened later if needed. Reports that are still pending scan (QUEUED or CRAWLING) can't be reviewed yet.

Scan Policy

By default, a target is only scanned when you explicitly trigger a scan (from the dashboard, the API, or the GitHub Action). You can optionally set a scan policy per target to have it scanned automatically:

• Periodic — scan the target on a DAILY, WEEKLY, or MONTHLY cadence.
• When new detections are added — rescan the target whenever SecretsBuster's detection engine is updated with new secret types, so previously-scanned targets get checked against the latest detectors.

Every automatic scan counts against your API key's quota just like a manual one.

API Key and Usage Plan

An API key is what authenticates your requests to the SecretsBuster API (and is what the dashboard uses on your behalf when you trigger scans from it). Each API key is tied to a usage plan, which defines how many scans (POST /reports calls) you can make per period — typically monthly. Only creating a report consumes quota; reading reports, checking your account, or reviewing findings does not.

An API key has a status:

Status	Meaning
TRIAL	Currently within a free trial period.
TRIAL_ENDED	The trial period ended without converting to a paid subscription.
ACTIVE	A paid subscription in good standing.
DISABLED	The key can't be used to create new scans.

An account can hold multiple API keys (e.g. one per subscription or per team). The dashboard lets you pick which key is used when you trigger scans from it.

Account

Your account is identified by your email address and is where all your domains, targets, reports, and API keys live — regardless of which of your API keys created them. SecretsBuster uses passwordless authentication for the dashboard: you request a sign-in link by email rather than setting a password.