How to run campaign workflows

Use full campaigns to establish broad coverage, incremental campaigns to review changed paths, and retest campaigns to verify one remediated finding.

Establish a baseline with a full campaign

1. Confirm the project has a methodology version and at least one enabled model.
2. Check out the target branch and commit locally.
3. Run:

thespider-agent run

Without --campaign, the agent creates or reuses a full campaign from local Git metadata, drains claimable slices for its configured models, and submits results.

4. Open the project dashboard.
5. Confirm no slices remain pending or running.
6. Triage findings before treating the campaign as a release baseline.

The first campaign has no comparison. A later campaign compares with its explicit baseline_campaign_id when one is set; otherwise the risk dashboard compares with the preceding campaign by identifier.

Run an incremental audit

Incremental campaigns require a base commit and a non-empty changed-path list because the server does not have the source tree.

POST /v1/projects/{projectId}/campaigns
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "type": "incremental",
  "git": {
    "branch": "feature/tenant-settings",
    "commit": "HEAD_COMMIT",
    "remote_url": "git@example.com:team/repo.git",
    "dirty": false
  },
  "base_commit": "BASE_COMMIT",
  "changed_paths": [
    "src/http/settings.ts",
    "src/db/tenant.ts"
  ]
}

The server matches changed paths against pass scopes. Dependency manifests, lockfiles, container files, environment files, and selected framework configuration files trigger every pass because they can change assumptions globally.

Run an existing incremental campaign from the checkout that matches its target commit:

thespider-agent run --campaign CAMPAIGN_ID

On a managed runner host, thespider-agent daemon discovers claimable campaigns, fetches the target commit into a managed checkout, and runs them.

Interpret campaign comparison

The selected campaign is the current side. Its baseline is the explicit baseline campaign when present, otherwise the previous campaign.

• New means the finding has a current sighting and no baseline sighting.
• Resolved means the finding has a baseline sighting and no current sighting.
• Carried forward means an open finding has sightings in both campaigns.

Comparison uses project-level finding identity, fingerprint aliases, and sightings. A wording change that deduplicates to the same keeper is carried forward rather than counted as new.

The campaign page also shows findings new relative to its baseline. The project dashboard supplies the new, resolved, and carried-forward counts.

Retest a remediation

1. Open the finding in the web application.
2. Change its status to the mode-appropriate fixed state and record one or more fix commits.
3. Select Create retest campaign.
4. Open the linked campaign.
5. Run the campaign from a checkout at the recorded fix commit:

thespider-agent run --campaign CAMPAIGN_ID

The server limits the campaign to the finding's bucket and passes whose scopes match its files. When every retest slice finishes:

• An exact or deduplicated reappearance changes the finding to still_vulnerable and records a regressed fix verification.
• A covered run with no reappearance keeps or changes the finding to fixed and records a confirmed verification.
• An uncovered scope produces no conclusion.

Open the finding again to review fix and verification history.

Choose a cadence

• Run a full campaign after material methodology changes and on a scheduled release or monthly boundary.
• Run incremental campaigns for pull requests or branch updates.
• Retest each remediated severe finding before release.
• Keep one stable, completed campaign as the comparison baseline while a release train is active.
• Do not compare incomplete campaigns as if absence proved resolution; pending slices make the gate status pending.

Use the API reference for request fields and the concepts glossary for identity and lease terminology.