← Files Codex SecurityARCHIVED FILE

references/scan-artifacts.md

11.4 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

# Scan Artifact Paths

Use these shared path conventions for Codex Security scan workflows unless the user explicitly provides different input or output paths.

Follow `artifact-storage.md` for storage selection, file authoring and shared threat-model cache rules.

## Base Paths

- `plugin_dir=<codex-security plugin root>`
- `target_id=<stable scan target identity from references/scan-contract.md>`
- `scan_id=<scanId returned by the MCP scan context, or CODEX_SECURITY_SCAN_ID when provided>`
- `scan_dir=<scanDir returned by the MCP scan context>`; when `CODEX_SECURITY_SCAN_DIR` is provided, use that existing SDK-owned directory. Never derive a scan directory from a repository name, revision, timestamp or temporary-directory formula.
- For a standalone phase, use the `directory` returned by `save_codex_security_artifact` for the selected `targetPath` and `storage`, as described in `artifact-storage.md`.
- `target_paths_file=<CODEX_SECURITY_TARGET_PATHS_FILE>` for SDK scoped-path scans; reference it as `"$CODEX_SECURITY_TARGET_PATHS_FILE"` in POSIX shells or `"$env:CODEX_SECURITY_TARGET_PATHS_FILE"` in PowerShell. This read-only scope file lives outside the scan directory. Pass it unchanged as `--scopes-file` to the SDK's primary inventory command and to `bind-repo-scopes` before finalization. For `make-hosted-repo-scope-input`, review the inventory at the path it reports. Use the supplied scan-directory recovery command only if a later shell cannot read that file. Do not print, evaluate, modify, or treat the scope file as shell syntax.
- `artifacts_dir=<scan_dir>/artifacts`
- `context_dir=<artifacts_dir>/01_context`
- `discovery_dir=<artifacts_dir>/02_discovery`
- `coverage_dir=<artifacts_dir>/03_coverage`
- `reconciliation_dir=<artifacts_dir>/04_reconciliation`
- `findings_dir=<artifacts_dir>/05_findings`

Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in POSIX shells or `& "$env:PYTHON"` in PowerShell), otherwise use `python` on Windows and `python3` on Unix-like hosts.

## Threat Model (Phase 1) Paths

- Resolved SECURITY.md guidance: `<context_dir>/security_guidance.md`
- Repository-scoped threat model: use the shared cache policy in `artifact-storage.md`.
- Canonical per-scan model: `scan.threatModel` in `<scan_dir>/scan-manifest.json`, retained in semantic checkpoints as soon as architecture mapping produces it.
- Human-readable per-scan model: `<scan_dir>/threatmodel.md`, generated by the host from the canonical model. Later phases use the retained canonical content or this projection. Historical scans may retain `<context_dir>/threat_model.md`; read it only when the canonical model is absent, without renaming or rewriting the historical file. For sealed scans, the historical document must be a recorded artifact with a matching digest.

## Finding Discovery (Phase 2) Paths

### Compact Deep And Workbench-Backed Diff Discovery

Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Workbench-backed diff scans use the compact artifacts described below.

Deep Scan runs Standard audits. Each worker saves findings and pending review work with `complete: false`, then submits its final result through `record_codex_security_scan_draft`. Worker checkpoints survive retries, cancellation and failure.

After each batch the host compares the repairs described in the reports. It checks disputed pairs that share an assigned repair, or cite overlapping code when a repair could not be assigned. It merges such a pair only when one narrow edit covers both reports in full and each supplies supporting code. A finding with an additional faulty operation or insufficient evidence stays separate. Each original finding and its citations stay in the saved union. The host records comparison failures and keeps unresolved reports. It writes the parent’s unsealed `scan-manifest.json` and `findings.json` with the accepted results and their review state. If the deadline arrives before a worker finishes, the parent retains the reason and any saved findings or pending review. See `scan-contract.md` for field definitions.

- A workbench-backed diff scan records all candidates once with `record_codex_security_discovery_candidates({ scanId, candidates })` and reads the canonical candidates with `list_codex_security_candidates({ scanId, cursor?, limit? })`.
  - The writer validates candidates against assigned source paths, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values.
  - After normalization, compact validation adds exactly one `validation` object to every row with `disposition` (`reportable`, `suppressed`, `not_applicable`, or `deferred`), `method`, `confidence` (`high`, `medium`, or `low`), `confidence_rationale`, concise `rubric` and `evidence`, `counterevidence_or_proof_gap`, `remaining_uncertainty`, and optional `artifact_paths`. Add `source`, `control`, `sink`, or `preconditions` only when they clarify or differ from the discovery fields.
  - Compact attack-path analysis adds exactly one `attack_path` object to each validation row marked `reportable` or `deferred`, with `decision` (`reportable`, `ignore`, or `deferred`), `dataflow`, `reachability`, `counterevidence`, `impact` and `likelihood` (`high`, `medium`, `low`, `ignore`, or `unknown`), `severity` (`critical`, `high`, `medium`, `low`, `ignore`, or `unknown`), `severity_rationale`, `change_conditions`, and `proof_gap` when deferred. A `reportable` decision requires severity `critical`, `high`, `medium`, or `low`; `ignore` requires severity `ignore`; `deferred` uses a provisional reportable severity or `unknown`.
  - Record all validations through `record_codex_security_candidate_validations` and all eligible attack-path decisions through `record_candidate_attack_paths`. The tools atomically preserve all discovery fields and candidate order.
- Optional compact validation evidence: `<discovery_dir>/validation_artifacts/<candidate_id>/`
  - Create this directory only for actual PoCs, crafted inputs, or logs and reference those paths from the row's `validation` object. Do not create placeholder per-candidate directories or narrative reports.

The worklist, per-finding receipt, and phase-report paths below apply only to standalone or legacy Diff workflows. Compact Workbench Diff scans use one shared `<discovery_dir>/candidate_ledger.jsonl`, written by `record_codex_security_discovery_candidates` and updated by the bound batch tools `record_codex_security_candidate_validations` and `record_candidate_attack_paths`; they do not create per-finding ledgers, reports, or receipts. Standard and Deep scans assemble validated findings directly without persisted source inventories or candidate ledgers.

### Diff Discovery And Coverage

- Advisory seed research: `<context_dir>/seed_research.md`
- Changed source input: `<discovery_dir>/rank_input.jsonl`
- Scoped deep-review input: `<discovery_dir>/deep_review_input.jsonl` if applicable
- Finding discovery report: `<discovery_dir>/finding_discovery_report.md`

### Deep Review

- Scoped work ledger: `<discovery_dir>/work_ledger.jsonl` if applicable
- Scoped raw candidates: `<discovery_dir>/raw_candidates.jsonl` if applicable

### Candidate Reconciliation

- Compact Diff candidate ledger: `<discovery_dir>/candidate_ledger.jsonl`
- Standalone or legacy Diff candidate findings directory: `<findings_dir>/`
- Standalone or legacy Diff per-finding directory: `<findings_dir>/<candidate_id>/`
- Standalone or legacy Diff per-finding candidate ledger: `<findings_dir>/<candidate_id>/candidate_ledger.jsonl`
- Scoped dedupe report: `<reconciliation_dir>/dedupe_report.md` if applicable
- Scoped deduped candidates: `<reconciliation_dir>/deduped_candidates.jsonl` if applicable

### Coverage

- Repository-wide coverage ledger: `<coverage_dir>/repository_coverage_ledger.md`
  - This is a coverage artifact, not a findings list: it should include checked surfaces with not_applicable, suppressed, deferred, or reportable dispositions.

## Validation (Phase 3) Paths

Standard scans and Deep Standard scan workers include validation directly in their final finding semantics. Compact workbench-backed diff scans record validation through their bound batch tool and may use the optional compact evidence path above. Standalone or legacy diff workflows may use these paths:

- Scan-level validation summary: `<findings_dir>/validation_summary.md` if applicable
- Per-finding validation report: `<findings_dir>/<candidate_id>/validation_report.md`
- Per-finding validation artifacts: `<findings_dir>/<candidate_id>/validation_artifacts/`

## Attack-Path Analysis (Phase 4) Paths

Standard scans and Deep Standard scan workers include attack-path analysis directly in their final finding semantics. Compact workbench-backed diff scans record attack-path decisions in each candidate's nested `attack_path` record through their bound batch tool. Standalone or legacy diff workflows may use these paths:

- Scan-level attack-path analysis report: `<findings_dir>/attack_path_analysis_report.md` if applicable
- Per-finding attack-path analysis report: `<findings_dir>/<candidate_id>/attack_path_analysis_report.md`

## Final Report Paths

All paths below are relative to the scan directory.

| Output | Path |
| --- | --- |
| Canonical scan receipt and findings | `scan-manifest.json` and `findings.json` |
| Readable report | `report.md` |
| Threat model, when recorded | `threatmodel.md` |
| Optional detailed finding write-up and supporting files | `findings/<slug>/<slug>.md` and `findings/<slug>/poc/` |
| Optional structural hardening portfolio | `hardening/hardening.md` and supporting files under `hardening/` |
| Report validation notes when validation fails | `report_validation.md` |
| Legacy coverage document | `coverage.json` only when referenced by the manifest's `scan.coverageRef` |

The current manifest stores additional excluded paths in `scan.review.excludedPaths`. See the [sealed scan contract](scan-contract.md#canonical-documents) for examples.

### Draft submission and retrieval

Workbench-owned Standard scans and workbench-backed diff scans submit drafts through `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, reviewState })`. Bound Deep workers submit their findings and review state through the same tool. The Deep coordinator writes the aggregated parent draft. SDK-owned Standard scans write unsealed manifest and findings files in the SDK-provided scan directory.

For Deep, workbench-backed diff, or explicitly requested Standard completed results, call `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`.

## Fix Finding Paths

- Fix report, when using an existing scan artifact directory: `<artifacts_dir>/fix_report.md`

## Placement Rules

- Put scan phase outputs and supporting evidence under the numbered artifact subdirectories above.
- Keep fix-finding outputs outside the numbered scan phases because fix-finding can run standalone or against an existing scan.
- Do not author the final `report.md` directly. Put complete scan-level report semantics in the canonical JSON files. Detailed per-finding prose in `findings/<slug>/<slug>.md` and derived design guidance under `hardening/` are optional for every scan mode. Finalization deterministically writes the unsealed `report.md` projection and links any recorded write-ups and hardening portfolio. Do not add these derived documents to the sealed artifact list.
- Keep the full scan bundle together under `scan_dir`.

SHA-256: 30a83f78ed066b1b4cfec3486b9f87952fb3c188fe16d16f654e025c6d3737e6