# Campaign scope and done criteria

Reference for a campaign's two versioned JSON documents, every scope filter and exclusion, dimensions recorded but not yet evaluated, and every done criterion.

A campaign carries two JSON documents, both at `"version": 1`. Unknown fields are kept as you sent them, so a dimension a newer Resolve Platform writes survives a round trip through an older server. A document that does not parse is `400 invalid scope document` or `400 invalid done document`. An empty scope is valid and means the whole organisation.

## Scope

```json
{
  "version": 1,
  "repos": ["acme/payments", "acme/ledger"],
  "category": "sca",
  "filters": { },
  "exclusions": { }
}
```

| Key | Meaning |
|---|---|
| `repos` | Repository full names. For a repositories campaign they are the target; otherwise they narrow it. Each must resolve to a real repository. |
| `category` | `sca`, `sast`, `secrets`, `iac` or `license`. Empty means every category. |

### Filters

All set filters must hold. Lists match any of their values.

| Filter | Keys |
|---|---|
| `identity` | `findingId`, `repoName`, `branchName`, `commitSha`, `source`, `category`, `packageName`, `packageVersion`, `packageEcosystem`, `purl`, `cpe`, `vendor`, `product` (all lists) |
| `weakness` | `cwes`, `aliases`, `ruleKeys`, `cleanCodeCategories` (lists) |
| `impact` | `minCvss`, `minCwss`, `minEpss`, `minEpssPercentile`, `minCess` (numbers) |
| `exploitAsserted` | `kev`, `vulncheckKev`, `msrcExploited`, `ransomware` (booleans) |
| `exploitObserved` | `any` (boolean), `sources` (list) |
| `reachability` | `verdicts` (list of reachability verdicts; `UNREACHABLE` is a valid choice), `assessedOnly` (boolean) |
| `exposure` | `internetExposed` (boolean), `audiences` (list). See [Internet exposure](/vulnerability-management/prioritisation/internet-exposure.md). |
| `supplyChain` | `malicious`, `squatted`, `abandoned`, `badActor` (booleans), `scorecardBelow` (number) |
| `attackChain` | `attackPathIds`, `techniques`, `tactics` (lists) |
| `lifecycle` | `eol`, `unmaintained` (booleans) |
| `licence` | `expressions` (list), `violatesPolicy` (boolean) |

### Exclusions

| Key | Excludes |
|---|---|
| `testCode` | Findings in test code |
| `devDeps` | Development dependencies |
| `transitiveDeps` | Transitive dependencies |
| `suppressed` | Findings covered by an active [suppression](/vulnerability-management/findings/suppressions.md) |
| `minConfidence` | Findings below this confidence (number) |

### Recorded but not evaluated yet

These dimensions are stored but not yet turned into a query. `POST /v1/campaigns/preview` lists any you used, so the Resolve Platform can say the count ignores them:

`attackChain` (any key), `licence.violatesPolicy`, `supplyChain.scorecardBelow`, `exploitObserved.sources`, `weakness.cleanCodeCategories`, `weakness.ruleKeys`.

## Done criteria

```json
{
  "version": 1,
  "join": "ALL",
  "criteria": [
    { "type": "gone-from-scans", "repos": ["acme/payments"], "category": "sca" },
    { "type": "safe-version" }
  ]
}
```

`join` is `ALL` (default: every criterion must hold) or `ANY` (one is enough). At least one criterion is required.

| `type` | Target kinds | Done when |
|---|---|---|
| `gone-from-scans` | vulnerabilities, repositories | The newest scan of the item's repository no longer reports it. The scan must be newer than the item's admission. May name its own `repos` and `category`, so "gone from the SCA scans of these two repositories" is a different claim from "gone everywhere". |
| `safe-version` | vulnerabilities, repositories | Gone from the latest scan **and** the package is at or above the fix version recorded at admission. A version that does not parse never satisfies it. |
| `eol-supported` | vulnerabilities, repositories | The installed version is on a supported cycle (`mode: "supported"`) or is the latest upstream release (`mode: "latest"`). Any other mode is 400. |
| `package-removed` | dependencies, repositories | The dependency is not in the newest scan of its repository, which must be newer than admission |
| `latest-version` | dependencies, repositories | The dependency is at the newest version the EOL catalogue knows. A package with no EOL record stays open. |
| `safe-version-used` | dependencies, repositories | The installed version has no open vulnerability that has a fix available |

A criterion not valid for the target kind is `400 criterion X is not valid for a <kind> campaign`.

`fix-verified` is not selectable. It is recorded when the scanner itself marked a finding fixed and named the run, and it always closes the item.

> [!WHY] Why an unscanned repository closes nothing
> `gone-from-scans` and `package-removed` require a scan newer than the item's admission. Without that, a campaign scoped to a repository nobody has rescanned would mark its whole cohort done on the first pass, reading "no evidence" as "finished".

## Item identity

The cohort remembers what a finding is, not the finding row: rows are re-minted on every scan and purged by retention. A finding item's key is `f|<repo>|<category>|<package>|<findingId>`; a dependency's is `d|<repo>|<dependencyKey>`.
