Run a security scan

Outcome

You will have launched a security scan — prpl calls each scan run a hunt — against a ready repository environment, watched it move through its stages, and recognized its completion state.

Who can do it

• Customer accounts can launch hunts on environments built from their own repositories.
• Organization members need the repository granted to them and a capability that includes launching scans (scan.hunt) — via the org-wide seat grants or the Repo owner role on that repository. The Findings reviewer role alone cannot launch hunts. See Roles and permissions.
• Waitlist accounts cannot launch hunts.
• Site admins can launch hunts anywhere.

Before you begin

• An environment for the repository shows the ready badge on the repository's Environments & hunts tab.
• Hunts incur cost — each launch runs one or more agent sessions against the environment.
• Decide whether to focus the hunt. Recon-derived attack classes fan a broad launch out into one hunt per class; a single CWE focus keeps it to one hunt.

Steps

There are three ways to trigger a hunt. Pick one:

Option A — automatically after the build

1. When starting the environment build, expand Scope and scan settings and tick Hunt after build.

2. As soon as the harness is ready, prpl launches hunts automatically — one per recon-discovered attack class. The build's Result page lists this fleet under Attack phase.

Option B — from the repository page

1. Open Attack surface, select the repository, and open the Environments & hunts tab.

2. On a row with the ready badge, choose an agent profile and pcap on or pcap off (network capture), then click Launch hunt.

3. You are redirected to the hunt's run page under /jobs/…. If the launch fanned out across several attack classes, the page you land on is the first of them; the rest appear on the Jobs page.

Option C — from a finished build's Result page

1. On the build pipeline page, the Result step shows Harness ready. If recon found no dominant weakness class you can pick or type a CWE to focus the hunt, or leave it blank to hunt broad.
2. Click Launch hunt.

What happens during the hunt

A hunt moves through three stages, shown as pills on the run page and the Jobs list: phase 1 · discovery (hypothesis generation), phase 2 · validate (each candidate is exercised against the running environment), and phase 3 · impact (severity and evidence enrichment). Only findings that validate against the live environment are reported as confirmed.

Verify

• While running, the run page shows the amber banner “run in progress — live feed below polls every 1.5s” and the live strip updates phase, duration, tokens, and findings.
• On completion the run's status pill settles on a terminal state: confirmed (validated findings), needs review (findings awaiting your decision), no_findings, or a failure state.
• The repository's Findings tab shows the resulting deduped finding groups, and the hunt appears under its environment on the Environments & hunts tab with its finding and confirmed counts.

Troubleshooting

The environment shows “Not ready to hunt”

The harness is not built (or the build is paused awaiting plan approval), so there is no runnable target. Finish the build first — see Prepare a repository environment.

“you do not have scan access to this repository”

Your account does not hold the scan capability for this repository. Organization members need the owner to grant the repository and a scan-capable role or seat grant — see Assign repository access and roles.

The hunt has been “running” for a long time

Long hunts are normal for large surfaces — check the run page's live feed: as long as new events and phase changes keep arriving, the hunt is progressing. If the live feed shows no new events for a long period and the status never settles, the run may have lost its runner; launch a fresh hunt from the environment row and report the stuck run if it recurs (Troubleshooting).

The hunt ended “failed”, “runner_fail”, or “incomplete”

The run hit an infrastructure or agent error before finishing. Open the run page to read the error context, then relaunch the hunt. Repeated failures on the same environment usually indicate a broken harness — rebuild the environment at the same ref and try again.

The hunt completed with no findings

That is a valid outcome, not an error. To probe deeper, start a new scan with a Known vulnerability description or Scope notes to focus the agents, or launch a hunt focused on a specific CWE from the build Result page.

Next steps

Read the results: Understand findings, then decide on each one in Acknowledge true positives or reject false positives. To watch runs across all repositories, see Monitor environments and scan jobs.