Campaigns
A campaign is one audit of a branch and commit, pinned to one profile (Security or Bugs) and one methodology version.
| Type | When | What it covers |
|---|---|---|
full | First scan, or a periodic re-baseline | Every bucket × pass × enabled model |
incremental | A PR or branch | Passes whose scope hits changed_paths, plus a few high-risk files that always fan out |
retest | Checking that a fix landed | One finding's bucket and the passes that match its files |
Full scan from the agent
thespider-agent run
No --campaign means: look at local git, create or reuse a full campaign, drain claimable slices. Add --once --max-slices 1 for a bounded first run.
Open the project dashboard and wait until nothing is pending or running before you treat it as a baseline.
Incremental (a PR)
The server has no source tree, so someone has to tell it which paths changed. The GitHub webhook does that once TheSpider enables the integration. An API caller can do it directly:
POST /v1/projects/{id}/campaigns
{ profile, type: "incremental", git:{branch,commit,remote_url,dirty},
base_commit, changed_paths: ["src/http/settings.ts"] }
The regular thespider-agent run command only creates full campaigns. To run an incremental that already exists:
thespider-agent run --campaign CAMPAIGN_ID
A one-line change to .env, a lockfile, a Dockerfile, or similar can expand to every pass, because those files change assumptions globally. If no pass matches, the campaign has zero work and the gate can return pass. Check your pass scopes if that surprises you.
On a runner host, thespider-agent daemon picks up claimable campaigns and checks out the right commit for you.
Retest a fix
- Open the finding, mark it fixed, record the fix commit.
- Click Create retest campaign.
- Run it from a checkout at that commit:
thespider-agent run --campaign <retest-campaign-id>
Do not add a contradictory --profile. The campaign already pins one.
When every covered slice finishes:
- The same (or de-duplicated) finding again →
still_vulnerable. - Nothing comes back →
fixed. - A slice that never ran → no conclusion.
A commit mismatch returns 409 unless an API caller sets override: true. The web action uses the recorded fix commit.
To have the agent pick a finding, write the fix, and drive the retest, see Refine.
What "new" means
Findings are project-wide, not per campaign. If a finding was already triaged on main, the same issue on a PR is the same finding, not a new one.
A later campaign can name an explicit baseline. Otherwise the dashboard compares with the previous campaign. New / resolved / carried forward come from sightings, not from who first filed the row. An unfinished campaign is not proof that something is gone.
Suggested rhythm: campaign cadence.