Scan and finding lifecycle
Provide one canonical state map from repository connection through environment, scan, review, defend, PR, and archive.
Outcome
You can place any repository, scan, or finding on the one canonical map: connect repository → prepare environment (Harness build) → scan → review (acknowledge / reject) → Defend patch → PR request / approve → archive — and you know who acts at each step and what state signals it is done.
Who can do it
This page is a reference — reading it requires nothing. Each stage in the map names the capability that gates acting on it; the roles that hold each capability are defined in Roles and permissions.
Before you begin
None. If you are working through the flow for the first time, start at Connect your first repository and use this page as the map you return to.
The lifecycle
- Connect a repository → it appears on your Attack Surface
- Prepare the environment (Harness build) →
ready - Run a scan → findings recorded
- Review findings → acknowledge true positives / reject false positives
- Defend patch generation →
defendedwith an evaluated patch - Pull request → request, then approve & open on GitHub → merged
- Archive → completed work hidden from the default view, reversibly
Stage-by-stage state map
| Stage | Action (exact UI label) | Capability | States you will see | Stage is done when |
|---|---|---|---|---|
| Connect repository | Scan a repository on /byos
(repository + pinned revision) |
repo.connect |
repository listed on your Attack Surface | the repository page opens with its Findings / Environments & hunts / Build jobs tabs |
| Prepare environment (Harness build) | launch a build; approve its plan via Review & approve plan when the build pauses for you | scan.synth |
queued → building →
action required (plan approval) → ready;
failures show failed |
the environment shows ready |
| Scan (hunt) | Scan this repository → Launch hunt | scan.hunt |
queued → running → confirmed
/ needs review / no findings;
failures show failed or stopped |
the run completes and its findings appear on the Findings tab |
| Review findings | Acknowledge true positive & generate patch (fans approval across the group's pending occurrences and immediately launches Defend), or — on the finding's run page — Acknowledge true positive, Acknowledge true positive (hold patch), or Reject as false positive | finding.review; the combined
acknowledge-and-patch button also needs patch.generate |
finding group: candidate → needs review →
defend ready / confirmed on acknowledge,
or false positive on reject |
no rows remain in needs review |
| Defend patch | automatic after the combined acknowledge button; or Defend / Launch defend for selected / Defend all ready (N) | patch.generate |
defend ready → defend running →
defended, with a patch evaluation of
pass / partial / fail |
the defend result shows an evaluated patch
(source.diff) |
| Pull request | two separately permissioned steps:
1 · Request PR (records intent, no push), then
2 · Approve & open PR (pushes
prpl/defend/… and opens the PR) |
step 1: patch.generate · step 2:
patch.pr.approve |
requested → open → merged /
closed (state pill on the finding row and defend
result) |
the PR is merged in your GitHub review process |
| Archive | archive / unarchive on findings, scan runs, and environments; Include archived (N) reveals hidden rows | archive |
rows dimmed with an archived chip; fully
reversible |
the default view shows only work that still needs attention |
Finding statuses at a glance
| Status badge | Meaning | Next action |
|---|---|---|
candidate | surfaced, not validated | none yet |
needs review | validated evidence awaiting your decision | acknowledge or reject |
defend ready | acknowledged / confirmed, eligible for a patch | Defend |
defend running | patch generation in flight | wait / monitor |
defended | patch generated and evaluated | request + approve the PR |
confirmed | true positive; patch held or handled elsewhere | optional Defend |
false positive | rejected by a reviewer | archive if desired |
env change | the scan asked for an environment adjustment | review the environment change request |
The loop closes with recurring scans: each scheduled scan re-enters the map at the scan stage, and repository knowledge carries your decisions forward so later scans start smarter.
Verify
- Given any status badge on the Findings tab, you can find its row in the table above and name the action that moves it forward.
- You can explain why opening a pull request takes two clicks by two capabilities, while acknowledging a finding takes one.
Troubleshooting
- A stage will not start — check the capability column; the control is hidden or refused when you do not hold the capability for that repository. See Roles and permissions.
- A run seems stuck — use Monitor environments and scan jobs to inspect its live state and logs.
- Stage-specific failures — each linked guide has its own troubleshooting section; for cross-cutting issues see Troubleshooting.
Next steps
Walk the map for real, starting at Connect your first repository — or jump to the stage you are on.
Last verified against commit c0bf54d on 2026-07-10 · capture scenario: scan-lifecycle