@openai/codex-security 0.1.5 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +89 -8
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/.mcp.json +24 -1
- package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/preflight/capability-profiles.toml +0 -57
- package/_bundled_plugin/references/config-preflight.md +1 -1
- package/_bundled_plugin/references/final-report.md +15 -7
- package/_bundled_plugin/references/scan-artifacts.md +11 -9
- package/_bundled_plugin/references/scan-contract.md +3 -1
- package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +42 -0
- package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +100 -0
- package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +181 -0
- package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +166 -0
- package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +120 -0
- package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +83 -0
- package/_bundled_plugin/schemas/tools/review-items.schema.json +80 -0
- package/_bundled_plugin/schemas/tools/scan-draft.schema.json +572 -0
- package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +18 -0
- package/_bundled_plugin/scripts/deep_scan_config.py +11 -3
- package/_bundled_plugin/scripts/deep_scan_workbench.py +153 -133
- package/_bundled_plugin/scripts/finalize_scan_contract.py +21 -0
- package/_bundled_plugin/scripts/generate_in_scope_files.py +134 -0
- package/_bundled_plugin/scripts/workbench_cli.py +33 -1
- package/_bundled_plugin/scripts/workbench_db.py +127 -117
- package/_bundled_plugin/scripts/workbench_feedback.py +2 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +5 -49
- package/_bundled_plugin/scripts/workbench_progress.py +86 -3
- package/_bundled_plugin/scripts/workbench_remediation.py +19 -1
- package/_bundled_plugin/scripts/workbench_scan_history.py +7 -1
- package/_bundled_plugin/scripts/workbench_scan_start.py +11 -5
- package/_bundled_plugin/scripts/workbench_scan_usage.py +557 -0
- package/_bundled_plugin/scripts/workbench_schema.py +501 -0
- package/_bundled_plugin/scripts/workbench_validation.py +117 -13
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -4
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +34 -28
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +1 -1
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +11 -8
- package/_bundled_plugin/skills/security-scan/SKILL.md +16 -9
- package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +26 -14
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +1 -1
- package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
- package/_bundled_plugin/skills/validation/SKILL.md +5 -5
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +145 -227
- package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +53 -68
- package/dist/api.d.ts +33 -7
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +361 -48
- package/dist/api.js.map +1 -1
- package/dist/auth.js +1 -1
- package/dist/auth.js.map +1 -1
- package/dist/cli.d.ts +3 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +477 -40
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts +29 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +47 -2
- package/dist/config.js.map +1 -1
- package/dist/cost.d.ts +7 -0
- package/dist/cost.d.ts.map +1 -1
- package/dist/cost.js +349 -18
- package/dist/cost.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/multiscan.d.ts +1 -0
- package/dist/multiscan.d.ts.map +1 -1
- package/dist/multiscan.js +3 -0
- package/dist/multiscan.js.map +1 -1
- package/dist/runtime.d.ts +16 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +540 -25
- package/dist/runtime.js.map +1 -1
- package/dist/scan-activity.d.ts +13 -0
- package/dist/scan-activity.d.ts.map +1 -0
- package/dist/scan-activity.js +319 -0
- package/dist/scan-activity.js.map +1 -0
- package/dist/scan-dashboard.d.ts +47 -0
- package/dist/scan-dashboard.d.ts.map +1 -0
- package/dist/scan-dashboard.js +444 -0
- package/dist/scan-dashboard.js.map +1 -0
- package/dist/scan-history-renderer.d.ts.map +1 -1
- package/dist/scan-history-renderer.js +4 -1
- package/dist/scan-history-renderer.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/dist/worker-progress.d.ts +7 -0
- package/dist/worker-progress.d.ts.map +1 -1
- package/dist/worker-progress.js +68 -0
- package/dist/worker-progress.js.map +1 -1
- package/package.json +3 -3
|
@@ -41,7 +41,7 @@ Use the shared scan artifact path conventions in `../../references/scan-artifact
|
|
|
41
41
|
- the threat model is repository-scoped rather than being centered around any specific scan target
|
|
42
42
|
- it describes repository-wide primary product or runtime surfaces and trust boundaries before covering any narrower examples
|
|
43
43
|
- any vulnerability-class discussion is about repository-context classes, not findings about any current diff
|
|
44
|
-
7. Append the exact `Repository` and `Version` lines from `../../references/scan-artifacts.md
|
|
44
|
+
7. Append the exact `Repository` and `Version` lines from `../../references/scan-artifacts.md`. If the bound Deep discovery worker tool `record_codex_security_worker_threat_model` is available, persist the complete Markdown and unchanged footer only by calling `record_codex_security_worker_threat_model({ content })`; otherwise write the threat model to the repository-scoped path.
|
|
45
45
|
|
|
46
46
|
## Threat Model Generation Guidance
|
|
47
47
|
|
|
@@ -56,4 +56,4 @@ Generate and structure the threat model using `references/threat-model-guidance.
|
|
|
56
56
|
- In large monorepos, avoid centering `personal/`, `test/`, `tests/`, `docs/`, `examples/`, or one-off developer tooling unless repository evidence shows those are real deployed or privileged workflow surfaces.
|
|
57
57
|
- Call out trust boundaries and assumptions explicitly.
|
|
58
58
|
- Keep references to vulnerability types at the level of repository-context classes, rather than any diff findings.
|
|
59
|
-
-
|
|
59
|
+
- When `record_codex_security_worker_threat_model` is available in a bound Deep discovery worker, persist the complete threat model and footer only through that tool. Otherwise persist the threat model output to the repository-scoped threat model path from `../../references/scan-artifacts.md`.
|
|
@@ -18,9 +18,9 @@ Use the shared scan artifact path conventions in `../../references/scan-artifact
|
|
|
18
18
|
|
|
19
19
|
### Compact Standard-Scan Mode
|
|
20
20
|
|
|
21
|
-
When `$security-scan` explicitly invokes this skill in compact standard-scan mode,
|
|
21
|
+
When `$security-scan` or `$deep-security-scan` explicitly invokes this skill in compact standard-scan mode, read the full candidate set with `list_codex_security_candidates({ scanId, cursor?, limit? })`. Apply the validation method and evidence rules in this skill to every candidate in one invocation. Record exactly one nested validation per candidate with `record_codex_security_candidate_validations({ scanId, validations: [{ candidateId, validation }] })`, using the compact record shape in `../../references/scan-artifacts.md` and preserving every discovery field and candidate order.
|
|
22
22
|
|
|
23
|
-
In this mode, the
|
|
23
|
+
In this mode, the tool atomically records the nested validation in place of a per-finding validation report, receipt, or closure table. Submit all candidate validations together; submit `validations: []` when the candidate set is empty. Create `<discovery_dir>/validation_artifacts/<candidate_id>/` only when validation produces an actual PoC, crafted input, or log, and reference it from the nested record. All validation reasoning, instance-preservation, evidence, and confidence requirements still apply; only the artifact packaging changes.
|
|
24
24
|
|
|
25
25
|
## Workflow
|
|
26
26
|
|
|
@@ -41,7 +41,7 @@ In this mode, the nested record replaces the per-finding validation report, rece
|
|
|
41
41
|
6. Save any PoC files, inputs, or logs under the validation artifacts path for the active mode from `../../references/scan-artifacts.md`.
|
|
42
42
|
7. If validation is not feasible, document what was tried, what remains uncertain, and the exact proof gap.
|
|
43
43
|
8. Return a clear validation assessment per finding grounded in the evidence, proof gaps, and remaining uncertainty.
|
|
44
|
-
9. In compact standard-scan mode,
|
|
44
|
+
9. In compact standard-scan mode, call `record_codex_security_candidate_validations` once with the nested validation for every candidate; the tool atomically updates the stored candidates.
|
|
45
45
|
10. Outside compact standard-scan mode, save that finding's visible validation report and append one validation receipt per candidate id at the default paths from `../../references/scan-artifacts.md`. The receipt must record the validation method, evidence or exact proof gap, disposition, and validation artifact/report reference for that candidate finding.
|
|
46
46
|
|
|
47
47
|
## Usage Guidance
|
|
@@ -58,7 +58,7 @@ When validation falls back to static code understanding, or when static evidence
|
|
|
58
58
|
|
|
59
59
|
## Output Contract
|
|
60
60
|
|
|
61
|
-
In compact standard-scan mode,
|
|
61
|
+
In compact standard-scan mode, submit the nested record defined in `../../references/scan-artifacts.md` using `record_codex_security_candidate_validations`. Every input candidate must receive exactly one validation disposition. The recorded result is the phase closure; do not also create a narrative report or receipt.
|
|
62
62
|
|
|
63
63
|
Outside compact standard-scan mode, use the following report contract.
|
|
64
64
|
|
|
@@ -103,7 +103,7 @@ For repository-wide and scoped-path scans, also include a validation closure tab
|
|
|
103
103
|
- Keep validation artifacts and phase output in the paths for the active mode from `../../references/scan-artifacts.md` so the full scan bundle lives together. Compact standard scans do not create per-finding validation reports.
|
|
104
104
|
- Make a serious, bounded effort to get runtime validation working when it would materially change reportability, confidence, or severity. Consult repository guidance such as `AGENTS.md`, `README.md`, setup docs, test docs, build files, and package-manager metadata to identify the required dependencies, generated files, services, and setup steps.
|
|
105
105
|
- For scans that should not modify the target tree, use a disposable copy or generated-artifact directory under the validation artifacts path for the active mode for builds, generated clients, patched test harnesses, and PoC files. A no-edit target rule does not forbid output-only build copies when they are needed to validate the original code.
|
|
106
|
-
- For repository-wide and scoped-path scans outside compact standard-scan mode, update each affected finding's validation report and closure table as each reportable, suppressed, not_applicable, or deferred row is decided. In compact standard-scan mode,
|
|
106
|
+
- For repository-wide and scoped-path scans outside compact standard-scan mode, update each affected finding's validation report and closure table as each reportable, suppressed, not_applicable, or deferred row is decided. In compact standard-scan mode, call `record_codex_security_candidate_validations` once after deciding all candidates. Do not leave validated candidates only in transient notes, terminal logs, or validation artifacts; later phases must be able to reconstruct every disposition from the durable phase output.
|
|
107
107
|
- For large repository-wide scans, keep setup/build/debug effort proportionate to the candidate and the remaining high-impact coverage ledger. Do not spend the review budget trying to fully reproduce one internal service when static trace, existing tests, and deploy/config evidence are enough to validate or suppress the candidate.
|
|
108
108
|
- In repository-wide and scoped-path validation, once one candidate in a repeated high-impact pattern has a strong proof tuple, switch to sibling candidates from the coverage ledger and validate each by checking the same source, closest control, sink, and impact. Only continue deeper runtime work when it would materially change reportability, severity, or confidence.
|
|
109
109
|
- If a repository-wide shard has a promoted same-family finding plus unresolved seeded or root-control rows, close those sibling rows next as reportable, suppressed, or deferred before replacing the review with a more dramatic neighboring finding. Representative proof improves confidence, but it does not close sibling root controls without exact counterevidence.
|
|
@@ -1,263 +1,181 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: vulnerability-writeup
|
|
3
|
-
description:
|
|
3
|
+
description: Turn vulnerability notes, disclosure reports, PoCs, source code, or Codex Security findings into self-contained, sceptically validated, natural-sounding vulnerability reports. Use for one vulnerability or a disclosure campaign; a Codex Security scan is optional.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Vulnerability Writeup
|
|
7
7
|
|
|
8
|
-
##
|
|
9
|
-
|
|
10
|
-
Produce a distributable report set from rough vulnerability notes, PoCs, and source code. Treat this as a technical disclosure campaign: every distinct vulnerability gets its own directory, its own report, its own PoC artifacts,
|
|
11
|
-
and its own sub-agent draft. The desired output is not a cleaned-up note. It is a calm, expert narrative that proves the bug from source, explores how far the primitive can realistically be pushed, and ships with a PoC that another researcher can build and run.
|
|
12
|
-
|
|
13
|
-
Do not require a Codex Security scan, scan ID, manifest, findings JSON, coverage receipt, or seal. Ordinary disclosure documents and supplied vulnerability material are first-class inputs. When scan artifacts are present, use their validated fields as additional evidence; otherwise inventory the supplied documents directly and proceed with the same research and quality bar.
|
|
14
|
-
|
|
15
|
-
## Core Rules
|
|
16
|
-
|
|
17
|
-
- Use one sub-agent per vulnerability write-up. Do not assign multiple vulnerabilities to one worker.
|
|
18
|
-
- When this skill is used during Codex Security final reporting, the scan request is already authorization to launch the required one-finding write-up sub-agents. Do not ask for separate sub-agent authorization.
|
|
19
|
-
- The main agent owns inventory and deduplication. Workers receive only the single vulnerability they are writing.
|
|
20
|
-
- Review every sub-agent report yourself before accepting it.
|
|
21
|
-
- If a report falls short, run another sub-agent for that same vulnerability with the raw artifacts and a concise critique.
|
|
22
|
-
- Source access is mandatory for an excellent report. If the source tree or vulnerable revision is missing, stop and get it from the user unless the user explicitly accepts a lower-confidence report.
|
|
23
|
-
- Treat pre-captured source snippets as leads, not as the complete source of truth. Workers must inspect the target source tree or an exact revision snapshot before choosing final snippets.
|
|
24
|
-
- Never guess missing technical detail. Read source, inspect commits, run safe experiments, and clearly separate validated facts from hypotheses.
|
|
25
|
-
- Use lab or VM access only when it is explicitly authorized for this work.
|
|
26
|
-
Never test against public or live production instances unless the user has explicitly instructed you to do so for that target.
|
|
27
|
-
- Make reports self-contained and distributable. Do not mention Drive,
|
|
28
|
-
internal provenance, local absolute paths, or prior working folders.
|
|
29
|
-
- Write in the natural first-person voice of a professional vulnerability researcher. Use "we" throughout the technical walkthrough to guide the reader through source, state transitions, exploit ideas, and PoC behavior ("we first reach", "if we carry this value forward", "from here we control"). Include honest "I" statements for the work actually performed and its limits ("I reviewed revision", "I reproduced", "I could not run this without a VM"). Static review is work and may be stated as such. Never invent testing or personal observations. Do not sprinkle pronouns into otherwise impersonal prose merely to satisfy this rule; the report should feel genuinely narrated.
|
|
30
|
-
- Prefer readable, terminal-friendly line wrapping when it does not make the prose awkward. Do not let line length rules damage clarity, links, tables,
|
|
31
|
-
code references, or the natural rhythm of the report.
|
|
32
|
-
- Prefer source-backed narrative over labels. Each report should tell the full story: trigger, vulnerable path, bad state, impact, PoC, and fix.
|
|
33
|
-
- Vulnerabilities sometimes have several different options for exploitation.
|
|
34
|
-
Exploring and discussing alternative exploitation routes is often useful to include in a report even if it's not the best route or the one used for the PoC, so always include those discussions where they add interesting insights or explore ideas that otherwise wouldn't be covered. Where alternatives are covered, make the pros and cons clear, as one would expect in a technical discourse.
|
|
35
|
-
- Treat PoCs as first-class deliverables. The final report directory should contain clean PoC source, build/run instructions, representative output,
|
|
36
|
-
and any reliability, cleanup, or target-environment notes the reader needs.
|
|
37
|
-
If you feel it's not possible to develop a PoC, ask the user for guidance.
|
|
38
|
-
|
|
39
|
-
If the platform refuses to start more sub-agents, state that constraint to the user and queue the tasks. You should always delegate one report to one sub-agent. If a sub-agent starts but creates no files after one reasonable wait and one explicit finish instruction, close it and retry once with a tighter prompt for the same single vulnerability. If the retry also stalls,
|
|
40
|
-
mark the writeup phase blocked unless the user explicitly authorizes a main-agent fallback. Do not silently use a main-agent fallback for production scan completion.
|
|
41
|
-
|
|
42
|
-
## Inputs
|
|
43
|
-
|
|
44
|
-
Gather and preserve these inputs before drafting:
|
|
45
|
-
|
|
46
|
-
- raw vulnerability documents, exported text, or existing rough reports;
|
|
47
|
-
- supplied scanner findings or Codex Security finding bundles, when present;
|
|
48
|
-
- existing PoCs, scripts, crash logs, traces, and screenshots;
|
|
49
|
-
- the target source tree and exact vulnerable revision or release tag;
|
|
50
|
-
- a focused inventory of relevant source paths, functions, and revisions when available;
|
|
51
|
-
- fix commits, upstream diffs, or advisory text when available;
|
|
52
|
-
- lab access details such as SSH hosts, VMs, kernels, or test accounts;
|
|
53
|
-
- the user's authorization boundary for testing, especially whether any live target is in scope.
|
|
54
|
-
|
|
55
|
-
When the corpus comes from an external store (e.g. cloud storage or network paths), export the key text locally first. The final reports must not refer to external storage unless the user explicitly asks for provenance notes.
|
|
56
|
-
|
|
57
|
-
The produced write-ups must be distributable on their own and not assume access to other files or systems.
|
|
58
|
-
|
|
59
|
-
## Campaign Workflow
|
|
60
|
-
|
|
61
|
-
1. Create a destination directory, usually `reports` or the user-provided name. Use short, representative slug names.
|
|
62
|
-
2. Build an inventory of candidate documents and PoCs. Record title,
|
|
63
|
-
subsystem, primitive, affected paths, and likely duplicates.
|
|
64
|
-
3. Deduplicate by root cause and vulnerable code path, not by document title.
|
|
65
|
-
Merge notes and PoCs that describe the same bug.
|
|
66
|
-
4. Read `references/report-format.md` in full and use it as the report format.
|
|
67
|
-
Instruct every worker to do the same before drafting.
|
|
68
|
-
5. Confirm that each distinct vulnerability has enough source context to let a worker trace the bug from entry point to bad state. Inspect the finding's recorded locations, reopen the source around each relevant boundary, and give the worker the focused paths, functions, revision, and short source excerpts it needs. If source access is missing, collect the missing files,
|
|
69
|
-
revision, fix diff, or build instructions before drafting, or proceed at explicitly lower confidence when the user accepts that limitation.
|
|
70
|
-
6. If authorized lab access exists, record how to reach it and what safety limits apply. If it does not, instruct the worker to build or reason about PoCs locally and to state what could not be executed.
|
|
71
|
-
7. For each distinct vulnerability, create one directory containing an appropriately-named report file as markdown (e.g. `freebsd-shm-uaf.md`)
|
|
72
|
-
and a `poc/` directory when PoCs exist. Don't just use a nondescript file name like `report.md`.
|
|
73
|
-
8. Launch exactly one sub-agent for that vulnerability. Give it the raw notes, focused source paths and excerpts, target source tree, vulnerable revision, PoCs, output directory, format rules, lab details, and authorization boundary. Do not give it other vulnerabilities.
|
|
74
|
-
9. Review the worker output immediately. Check technical correctness,
|
|
75
|
-
completeness, line wrapping, self-contained wording, source snippets,
|
|
76
|
-
exploitability depth, PoC usability, and narrative voice. Reject a report that is written as an impersonal sequence of facts, reserves "we" for one token sentence, or never states in first person what was and was not validated.
|
|
77
|
-
10. Reject snippets that cut off before the vulnerable condition, missing guard, dangerous sink, relevant lifetime transition, or proposed fixed invariant. Inspect source directly before asking the worker to rewrite. If the story is thin, incomplete,
|
|
78
|
-
speculative, narratively compressed, impersonal, or missing a runnable PoC path, launch a new sub-agent for that same vulnerability with the raw inputs and the specific gaps to close.
|
|
79
|
-
11. Make only small main-agent edits after acceptance: heading fixes, line wrapping, command-path portability, and typo cleanup. Do not paper over a weak draft with surface edits.
|
|
80
|
-
12. Run final validation over the whole report set before returning.
|
|
81
|
-
|
|
82
|
-
## Sub-Agent Prompt
|
|
83
|
-
|
|
84
|
-
Use a prompt shaped like this for each vulnerability:
|
|
8
|
+
## Purpose
|
|
85
9
|
|
|
86
|
-
|
|
87
|
-
Write one high-quality vulnerability disclosure report for <slug>.
|
|
10
|
+
Produce a disclosure report that another security researcher can understand, check and, where safely possible, reproduce. Treat the original finding as a hypothesis, not a conclusion. Establish the assessed software version, attacker position, reachable entry point, expected security behaviour, actual failure and narrowest demonstrated impact before deciding how strongly the report can speak. Pin the exact underlying source privately so the report remains accurate without burdening the reader with unnecessary commit hashes.
|
|
88
11
|
|
|
89
|
-
|
|
90
|
-
summarize, compare, or polish any other finding. Quality drops when one
|
|
91
|
-
worker handles multiple bugs, so keep all attention on this single report.
|
|
12
|
+
The result is still a finished, distributable vulnerability report, not an interactive review. Bring the scepticism, evidence discipline and approachable researcher-to-researcher voice of a good conversational review into the report itself.
|
|
92
13
|
|
|
93
|
-
|
|
94
|
-
- Raw notes: <paths>
|
|
95
|
-
- Existing rough report, if any: <path>
|
|
96
|
-
- PoC artifacts: <paths>
|
|
97
|
-
- Focused source paths and excerpts: <paths and relevant functions>
|
|
98
|
-
- Target source tree: <path>
|
|
99
|
-
- Vulnerable revision/release: <revision>
|
|
100
|
-
- Fix commits/diffs, if any: <paths/revisions>
|
|
101
|
-
- Lab access: <ssh/vm details>
|
|
102
|
-
- Testing authorization boundary: <what is allowed and forbidden>
|
|
103
|
-
- Required format: `references/report-format.md`.
|
|
104
|
-
- Output directory: <reports-dir>/<slug>
|
|
105
|
-
|
|
106
|
-
Rules:
|
|
107
|
-
- Before drafting, open and read `references/report-format.md` in full. Its
|
|
108
|
-
headings are the beginning of the assignment, not a completeness checklist.
|
|
109
|
-
- Analyze source and fixes directly; never guess. Trace the bug from the
|
|
110
|
-
attacker-controlled entry point through the relevant state transitions to
|
|
111
|
-
the bad state.
|
|
112
|
-
- Treat supplied snippets as starting points. If a snippet ends before the
|
|
113
|
-
decisive branch, guard, sink, lifetime transition, or patch invariant,
|
|
114
|
-
reopen the source tree and quote a complete short snippet instead.
|
|
115
|
-
- Use the source tree throughout the report. Include short, relevant snippets
|
|
116
|
-
with file paths, functions, and enough surrounding explanation for a human
|
|
117
|
-
reader to follow the path without opening the repository.
|
|
118
|
-
- Treat the rough notes as leads, not gospel. Validate each claim against the
|
|
119
|
-
vulnerable source, the fix diff, or an experiment. Correct the notes when
|
|
120
|
-
the source proves them incomplete or slightly wrong.
|
|
121
|
-
- Explore exploitability, not just reachability. Discuss viable primitives,
|
|
122
|
-
constraints, allocator or protocol behavior, race windows, object lifetime,
|
|
123
|
-
attacker-controlled bytes, reliability, and useful dead ends. Build small
|
|
124
|
-
throwaway probes when they clarify an exploit path.
|
|
125
|
-
- Verify or improve the PoC when safe and authorized. Prefer disposable VMs
|
|
126
|
-
or local test targets for crashes, corruption, LPE, data loss, or denial of
|
|
127
|
-
service. Never run against public or live production instances unless the
|
|
128
|
-
authorization boundary explicitly allows that target.
|
|
129
|
-
- Ship a polished final PoC in `poc/`. Include source, build files, a README
|
|
130
|
-
when helpful, exact run commands using relative paths, required environment
|
|
131
|
-
details, expected output, and notes on reliability or cleanup.
|
|
132
|
-
- Produce a self-contained report markdown file with no provenance references
|
|
133
|
-
and no local absolute paths.
|
|
134
|
-
- Use a natural first-person researcher voice in the report itself. Guide the
|
|
135
|
-
reader with "we" across the substantive walkthrough: introduce why each
|
|
136
|
-
source excerpt matters, carry values and object state between functions,
|
|
137
|
-
reason through exploit options, and explain PoC behavior. Do not leave the
|
|
138
|
-
reader with a dense sequence of snippets and declarative conclusions.
|
|
139
|
-
- Include at least one truthful first-person-singular account of the validation
|
|
140
|
-
basis and limits. For example: "I reviewed the vulnerable revision and fix
|
|
141
|
-
directly, but I did not execute the panic trigger because no disposable VM
|
|
142
|
-
was available." Mention builds, experiments, failures, or observations only
|
|
143
|
-
when they actually happened.
|
|
144
|
-
- Give important transitions enough prose to teach why the evidence matters.
|
|
145
|
-
Explore promising exploitation routes, relevant alternatives, constraints,
|
|
146
|
-
and informative dead ends instead of collapsing exploitability into a verdict
|
|
147
|
-
paragraph. Add depth where the bug warrants it; do not pad the report.
|
|
148
|
-
- Prefer readable prose wrapping, but do not contort technical language,
|
|
149
|
-
links, tables, or code references to satisfy a fixed column width.
|
|
150
|
-
- Explain trigger, vulnerable path, bad state, impact, exploitability, PoC,
|
|
151
|
-
and fix as one coherent narrative. The reader should feel calmly guided
|
|
152
|
-
from background to source proof to practical demonstration.
|
|
153
|
-
- Use relative commands such as `cd poc` then `make`, not local absolute
|
|
154
|
-
paths.
|
|
155
|
-
```
|
|
14
|
+
Accept supplied notes, disclosure documents, existing reports, PoCs, source trees and scanner findings as first-class inputs. Do not require a scan ID, finding bundle, manifest, coverage receipt or other Codex Security scan artefact.
|
|
156
15
|
|
|
157
|
-
|
|
16
|
+
## Non-negotiable rules
|
|
158
17
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
18
|
+
- Give each distinct vulnerability its own report directory and exactly one drafting sub-agent. The main agent owns inventory, deduplication, source checks and final acceptance.
|
|
19
|
+
- During Codex Security final reporting, the scan request authorises those one-finding drafting sub-agents. Do not request separate delegation approval.
|
|
20
|
+
- When the exact vulnerable source revision is available, inspect it. Resolve the complete commit internally when possible and note dirty, shallow, missing, patched or mismatched source. For a reproduced vendor or distribution package, verify every reader-facing excerpt and line citation against that exact patched source; use upstream source separately for history unless it is also the code that ran. Follow relevant dependency code in causal order and identify its exact tested version. Use `git show REV:PATH` for a non-checked-out revision rather than treating the current worktree as that revision. In the report, identify the software by its verified public release whenever one exists.
|
|
21
|
+
- If the exact source or revision is unavailable, stop and request it. Produce a report-only assessment only when the user explicitly accepts that limitation, and make every source-dependent conclusion visibly conditional.
|
|
22
|
+
- When source and release history are available, trace the vulnerable code back to the change that introduced it and determine which released versions actually contain the vulnerable behaviour. Inspect the relevant tags, release branches, fixes and backports; never turn an unverified commit range into an affected-version claim.
|
|
23
|
+
- Never invent a source excerpt, line number, revision, affected version, first affected release, fixed release, advisory, CVE, CVSS vector, deployment prevalence, exploit route, execution result or observation.
|
|
24
|
+
- Distinguish source evidence, inspected-but-unexecuted PoCs, actual runtime observations, supplied report claims, inference and unknowns. Do not promote an inspected PoC into a reproduced vulnerability.
|
|
25
|
+
- Do not use "witness" as shorthand for supporting evidence. Name the actual source excerpt, test input, HTTP request and response, execution trace, proof-of-concept run, observed output or counterexample, and explain exactly what it demonstrates. Preserve an actual source identifier containing that word only when necessary, and immediately explain its concrete meaning.
|
|
26
|
+
- Test only within the user's explicit authorisation. Use disposable local targets for crashing, destructive or privilege-escalating PoCs. Never contact or test a public, external or production target without target-specific permission.
|
|
27
|
+
- Do not manufacture PoC commands, logs, screenshots or sample output. Include observed output only when it was actually produced or when a supplied, identifiable trace was inspected. Label a prediction as expected output and explain that it was not observed.
|
|
28
|
+
- Write in the language and locale the user requests; when they do not specify one, use their normal default. Be warm, direct and exact; guide substantive reasoning with a natural `we`, and use `I` only for work actually performed. Describe what the software should do, what it actually does and why that matters in plain language.
|
|
29
|
+
- Give people clear, conventional names when they help explain the finding: Alice is the legitimate account or resource owner, Bob is another legitimate user or intended recipient, Mallory is the active attacker, and Eve is a passive observer. Use matching example usernames such as `alice`, `bob`, `mallory` and `eve` consistently in prose, commands and PoCs.
|
|
30
|
+
- Make every delivered report and PoC portable and self-contained. Use repository-relative source paths, report-relative commands and verified software versions. Never include an author-machine-specific absolute path in report prose, excerpts, citations, links, PoC code, build files, command examples or captured output; retain a verified absolute target-system path when it is necessary to describe or reproduce the vulnerability.
|
|
31
|
+
|
|
32
|
+
## Actors, language and release references
|
|
33
|
+
|
|
34
|
+
Introduce only the people the particular finding needs and keep their roles consistent. For example: `Alice owns the document; Mallory signs in as mallory and retrieves it by changing the document ID.` Add Bob when the behaviour involves another legitimate user or intended recipient, and Eve only when passive interception is actually relevant. Preserve important real system roles, privileges and account types; do not pretend that a generic example user has permissions the actual product does not grant.
|
|
35
|
+
|
|
36
|
+
Explain the problem in terms of what should happen and what happens instead. Prefer `Only Alice should be able to read her document, but the download handler checks that Mallory is signed in without checking who owns the document` over abstract, theory-heavy security language. Define genuinely necessary technical terms once and use them only when they clarify the real mechanism.
|
|
166
37
|
|
|
167
|
-
|
|
38
|
+
Replace opaque evidence labels with the actual thing observed. For example, write `the request showing Mallory received Alice's document`, `the input that triggers the out-of-bounds read`, `the recorded order of the two requests`, `the failing regression test`, or `the source lines showing that the ownership check is missing`. Choose the phrase that matches the real evidence; do not substitute an equally vague generic label.
|
|
168
39
|
|
|
169
|
-
|
|
40
|
+
Use public release numbers as the primary reader-facing source references. Give the assessed release, the first verified affected release and the fixed release when established. Cite source using a repository-relative path and function; do not repeat a commit hash for every excerpt. Include a short commit reference only when the introducing change, fixing change, unversioned build or conflicting release history is itself important to the explanation.
|
|
170
41
|
|
|
171
|
-
|
|
172
|
-
- follow data, lifetime, locking, bounds, and state transitions;
|
|
173
|
-
- quote short source snippets only when they clarify the path;
|
|
174
|
-
- inspect vulnerable release code with commands like `git show <rev>:<file>`;
|
|
175
|
-
- compare fix commits when available to confirm the intended invariant;
|
|
176
|
-
- describe the resulting kernel or application state precisely;
|
|
177
|
-
- calibrate impact to the validated primitive;
|
|
178
|
-
- name assumptions and unverified exploitability limits.
|
|
42
|
+
## Trace affected release history
|
|
179
43
|
|
|
180
|
-
|
|
44
|
+
Before drafting, inspect the history of the actual vulnerable code rather than assuming the current version has always behaved this way.
|
|
181
45
|
|
|
182
|
-
|
|
46
|
+
1. Identify the exact lines, check, state change or permission decision that makes the reported attack possible.
|
|
47
|
+
2. Trace that behaviour through file history, renames and blame to identify the change that introduced it.
|
|
48
|
+
3. Inspect release tags and maintained branches to find the earliest released version that actually contains the vulnerable behaviour.
|
|
49
|
+
4. Inspect the fixing change and each relevant release branch to determine the first fixed version and any backported fixes.
|
|
50
|
+
5. Confirm representative affected and fixed release snapshots directly. A tag containing an introducing commit is not proof that the released code remained vulnerable after subsequent fixes or backports.
|
|
51
|
+
6. State separately what is confirmed, what is the earliest version inspected and what cannot be determined from the available history. If tags, older history or release mappings are missing, say so rather than claiming a definitive first affected version.
|
|
183
52
|
|
|
184
|
-
|
|
185
|
-
- use `git show <revision>:<path>` when the source tree is a Git checkout and the scanned revision is available;
|
|
186
|
-
- identify relevant compile-time options, configuration, permissions, and threat-model checks;
|
|
187
|
-
- search for sibling call sites and variants that help explain the invariant;
|
|
188
|
-
- include snippets from vulnerable code and, when useful, the fixing diff;
|
|
189
|
-
- keep snippets short and narrate the important lines before or after them.
|
|
53
|
+
Do not stop at a shallow checkout when complete history, release archives or authoritative mirrors can be obtained safely within scope. Use checksum manifests or equivalent publisher evidence to establish archive provenance where appropriate. Inspect enough actual release snapshots to support the stated family or branch coverage, then name the intermediate patch releases or current branch tips that were not individually checked.
|
|
190
54
|
|
|
191
|
-
|
|
55
|
+
Use Git history and full commit identities as research evidence, not as repeated report prose. When supported, explain the result as a release history: `The vulnerable ownership check was introduced in 2.3.0, is present in 2.3.0–2.5.1, and is corrected in 2.5.2.` Explain what the introducing change was trying to do and why the earlier release did not have the problem when that history clarifies the root cause. Do not present that example as a finding or reuse its version numbers without checking the real project.
|
|
192
56
|
|
|
193
|
-
|
|
194
|
-
Useful lines of inquiry include:
|
|
57
|
+
## Evidence-first intake
|
|
195
58
|
|
|
196
|
-
|
|
197
|
-
- how allocator, scheduler, parser, cache, sandbox, or protocol behavior affects reliability;
|
|
198
|
-
- how to groom state before the trigger and stabilize state afterward;
|
|
199
|
-
- what information leaks, write gadgets, confused-deputy paths, or privilege boundaries might combine with the primitive;
|
|
200
|
-
- what constraints make a stronger exploit unlikely.
|
|
59
|
+
Before drafting, inventory:
|
|
201
60
|
|
|
202
|
-
|
|
61
|
+
- the raw finding, report, disclosure notes and claimed trigger;
|
|
62
|
+
- the exact source root, assessed release and privately pinned commit or tag, or the source limitation the user explicitly accepted for a report-only assessment;
|
|
63
|
+
- the introducing change, earliest verified affected release, affected release branches, fixing change and verified fixed or backported releases;
|
|
64
|
+
- the affected paths, functions, configuration and build options;
|
|
65
|
+
- Alice, Bob, Mallory or Eve as appropriate, together with each person's actual account, required credentials, privileges and controlled input;
|
|
66
|
+
- the affected owner, intended recipient, security boundary and downstream consumer;
|
|
67
|
+
- the claimed impact and the narrower primitive actually supported;
|
|
68
|
+
- any PoC, logs, negative control, regression test and available fix;
|
|
69
|
+
- what was read, built, executed, observed, merely supplied or not available;
|
|
70
|
+
- the testing authorisation and any disposable test environment.
|
|
203
71
|
|
|
204
|
-
|
|
205
|
-
data-loss, or LPE cases, prefer disposable VMs and state the risk in the report. If a PoC cannot safely be run, at least verify that it builds or that its build recipe is coherent, and explain the missing execution condition.
|
|
72
|
+
Write down the minimal reported trigger as a hypothesis before tracing it. Keep the actual attacker-controlled input, intermediate state and claimed sink aligned throughout the investigation. Do not quietly replace the claimed exploit with an easier earlier event, another request, a different object, a patched revision or a test-fixture-only behaviour.
|
|
206
73
|
|
|
207
|
-
|
|
74
|
+
Before drafting, reduce the finding to one concrete attack sentence: who Mallory is, which legitimate credential or input she controls, what she does, which separate policy or owner should stop her and which real sink she reaches. State the important non-claims alongside it, such as `Mallory reuses her own session; she does not steal Alice's session or break TLS.` Record the complete tested topology and prerequisites near this sentence, separating defaults from operator configuration and leaving deployment prevalence unknown unless measured.
|
|
208
75
|
|
|
209
|
-
|
|
210
|
-
- include a `Makefile`, script, container recipe, or exact build command;
|
|
211
|
-
- include example commands from a clean checkout or unpacked report bundle;
|
|
212
|
-
- include representative output from a successful run;
|
|
213
|
-
- separate exploratory probes from the polished final PoC when both are kept;
|
|
214
|
-
- include cleanup or reset instructions when the PoC changes system state.
|
|
76
|
+
Challenge the claim before making it sound convincing:
|
|
215
77
|
|
|
216
|
-
|
|
78
|
+
- Is the required configuration default, optional, unusual or unknown? Documentation and shipped examples establish existence, not prevalence.
|
|
79
|
+
- Does the attacker already need the access or privilege that the report claims to obtain?
|
|
80
|
+
- Does the exact source preserve the reported object ownership, callback order, lock, lifetime, bounds, validation order and final sink?
|
|
81
|
+
- Can cancellation, generation checks, error handling, cleanup, permissions or another guard prevent the path?
|
|
82
|
+
- Does a controlled test change only timing or visibility, or can it create the outcome itself?
|
|
83
|
+
- What negative control or concrete observation would distinguish the claimed vulnerability from a benign explanation?
|
|
84
|
+
- Does the evidence establish reachability, a bad state, a real boundary crossing or only a stronger impact that remains possible?
|
|
85
|
+
|
|
86
|
+
If the source contradicts the finding, stop presenting it as a vulnerability. Explain the contradiction and the remaining evidence rather than generating a persuasive disclosure for a false positive.
|
|
87
|
+
|
|
88
|
+
## Campaign workflow
|
|
89
|
+
|
|
90
|
+
1. Create the user-requested report directory, or use `reports/`. Inventory and deduplicate findings by root cause and source path rather than title.
|
|
91
|
+
2. Read `references/report-format.md` completely. Require each drafting sub-agent to read it before writing.
|
|
92
|
+
3. When the vulnerable source is available, pin and inspect it. Independently check the decisive entry point, security check, state change, sink and available fix. Trace the introducing change and inspect affected and fixed release tags only when the relevant history is available; otherwise record that limitation without blocking a source-backed report. When the user explicitly accepted a report-only assessment, record the unavailable source and require every source-dependent conclusion to remain conditional.
|
|
93
|
+
4. Record the one-sentence attack and non-claims, available verified release history or explicit release-history limitations, named actors, complete tested topology, defaults versus configured prerequisites, meaningful positive and negative controls, exact validation basis and testing boundary before assigning the finding.
|
|
94
|
+
5. Create one descriptively named Markdown report per vulnerability and a sibling `poc/` directory only when real PoC artefacts exist or can safely be developed.
|
|
95
|
+
6. Launch exactly one sub-agent for each distinct vulnerability. Provide only that vulnerability's raw material, available pinned source or explicitly accepted report-only limitation, PoC artefacts, output directory, report-format reference and authorisation boundary.
|
|
96
|
+
7. Independently read the returned report against the raw artefacts and any available pinned source and release history. Check each important claim, excerpt, transition, affected-version statement, impact, fix and reported observation; keep source-dependent conclusions conditional when source inspection was unavailable and the user accepted a report-only assessment.
|
|
97
|
+
8. Reject a draft that smooths over missing evidence, invents a run, inflates impact, guesses affected versions, leaks an author-machine-specific absolute path, calls an unexplained piece of evidence a "witness", overloads the prose with hashes or jargon, mistakes configuration existence for prevalence, or uses named actors or first-person language as decoration.
|
|
98
|
+
9. If the draft needs substantive repair, launch a fresh sub-agent for that same finding with the original artefacts and specific review failures. Do not cover an evidentiary failure with cosmetic edits.
|
|
99
|
+
10. Make only small final corrections after acceptance, and validate the completed report and real PoC artefacts before delivery.
|
|
100
|
+
|
|
101
|
+
If delegation is unavailable, report that constraint instead of silently drafting a production-scan finding in the main agent. If a worker stalls, give one explicit finish instruction, retry once with a tighter single-finding assignment, and report the remaining blocker if the retry also fails.
|
|
102
|
+
|
|
103
|
+
## Single-finding drafting prompt
|
|
104
|
+
|
|
105
|
+
Use this shape and supply the actual evidence:
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
Write one self-contained vulnerability disclosure report for <slug>.
|
|
217
109
|
|
|
218
|
-
|
|
110
|
+
You own exactly one finding. Read references/report-format.md completely before drafting.
|
|
219
111
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
112
|
+
Inputs:
|
|
113
|
+
- Raw finding and rough report: <paths>
|
|
114
|
+
- Source root and privately pinned vulnerable revision: <path and revision; never put the author-machine path in the report; or unavailable, with the user's explicit acceptance of a report-only assessment>
|
|
115
|
+
- Assessed release and verified affected versions: <release, first affected version, branches and gaps>
|
|
116
|
+
- Introducing and fixing changes: <verified history, release tags and backports>
|
|
117
|
+
- Relevant source paths, functions and claimed trigger: <details>
|
|
118
|
+
- Existing PoC, logs and negative controls: <paths or none>
|
|
119
|
+
- Fix or advisory, if directly available: <revision and paths or unknown>
|
|
120
|
+
- Attacker prerequisites and configuration: <known facts and unknowns>
|
|
121
|
+
- Named actors and usernames: <Alice/alice, Bob/bob, Mallory/mallory or Eve/eve as appropriate>
|
|
122
|
+
- Testing authorisation and disposable lab: <boundary>
|
|
123
|
+
- Report and PoC output directory: <directory>
|
|
124
|
+
|
|
125
|
+
Treat the supplied finding as a hypothesis. Inspect the exact source revision yourself when available. If the user explicitly accepted a report-only assessment without source, identify that limitation, keep every source-dependent conclusion visibly conditional and never invent an excerpt or line citation. Otherwise, trace the actual attacker-controlled entry point, the reported state change, existing checks and the real sink. Reopen any source excerpt that ends before the decisive line. Do not substitute a different event, object, revision or test harness for the claimed trigger.
|
|
126
|
+
|
|
127
|
+
Open with the actual attack in ordinary language and say what it is not. Name Mallory's legitimate starting credential or input, the separate service, owner or policy she crosses, and the concrete protected sink she reaches. Put the complete tested prerequisites near the beginning and distinguish defaults from configured features without guessing prevalence.
|
|
128
|
+
|
|
129
|
+
When source and release history are available, trace when the vulnerable behaviour first appeared and inspect the relevant released versions, fixing change and backports. If the supplied checkout is shallow, obtain complete history or exact release archives when safely available rather than treating the gap as the answer. Write the report in terms of verified software versions; include a commit hash only when that specific change is important or a release number is unavailable. Clearly separate the earliest verified vulnerable version from an unproven first affected release, and identify unsampled patch releases or branch tips; state unavailable release evidence as a limitation in an explicitly accepted report-only assessment.
|
|
130
|
+
|
|
131
|
+
Before stating impact, challenge deployment assumptions, attacker privileges, cancellation, locks, cleanup, ordering, negative controls and alternative explanations. Say exactly which claims are established, which remain plausible and which the source contradicts. Correct the original notes when necessary. If the vulnerability does not hold, report the contradiction; do not manufacture a disclosure.
|
|
132
|
+
|
|
133
|
+
Use the user's requested language and locale, or their normal default when unstated, with a calm researcher-to-researcher voice. Use Alice for the legitimate owner, Bob for another legitimate user or intended recipient, Mallory for the active attacker and Eve for a passive observer, only when those roles fit. Carry the matching usernames through requests, shell commands, PoCs and output. Follow one cross-component causal story: first establish that the ordinary security policy is configured correctly, then show the shared state or failed check, the dependency behaviour it changes and the real protected sink. Explain what the software should do, what it actually does, why each important excerpt matters and what the evidence does not settle. Use "we" naturally to guide the walkthrough. Use "I" only to state the exact source review, builds, observations, experiments or limitations that actually occurred.
|
|
134
|
+
|
|
135
|
+
Never call evidence a "witness". Instead, tell the reader what it actually is and what it proves: the request returning Alice's data to Mallory, the input triggering the failure, the captured output showing the result, the test exposing the bug, or the source lines containing the missing check. If an essential real code identifier contains that word, preserve the exact identifier and immediately explain what it represents in plain English.
|
|
136
|
+
|
|
137
|
+
Follow the required report headings. Make the impact no broader than the demonstrated primitive. Discuss realistic stronger routes and useful dead ends only as clearly qualified analysis. Never guess affected versions, prevalence, CVSS, reliability, patch status or runtime results.
|
|
138
|
+
|
|
139
|
+
Include a real PoC only when available or safely and explicitly authorised. Separate exact source review, inspected PoC code, syntax or build checks, actual runs, preserved records, offline evidence verification, source-confirmed but unexecuted releases and expected-but-unobserved behaviour. A convenience reproducer assembled from a real fixture is not an executed exploit unless it was actually run. Include observed output only when observed; otherwise label the expected result and explain the missing execution condition. Use repository- or report-relative paths and commands. Never copy an author-machine-specific absolute path into the report, PoC, build recipe, screenshots, logs or output; preserve a verified absolute target-system path when it is necessary to explain or reproduce the vulnerability.
|
|
140
|
+
|
|
141
|
+
Before returning, reread the report against the PoC, fix and any available exact source and release history. When the user explicitly accepted a report-only assessment, verify that every unavailable source-dependent claim remains conditional. Remove generic filler, unsupported certainty, repeated commit hashes, jargon, inconsistent actor names, repetitive proof labels, token first-person phrases, author-machine-specific absolute paths and claims the artefacts cannot support.
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
For a rewrite, give the replacement worker the original evidence and precise failed checks, not merely the previous prose:
|
|
145
|
+
|
|
146
|
+
```text
|
|
147
|
+
The previous draft incorrectly or inadequately handled <specific source, trigger, impact, validation or voice failures>. Re-establish each disputed claim against the pinned revision and original artefacts. Rewrite the explanation rather than adding qualifiers or first-person phrases to an unsupported narrative.
|
|
148
|
+
```
|
|
223
149
|
|
|
224
|
-
|
|
150
|
+
## Source and exploitability standard
|
|
225
151
|
|
|
226
|
-
|
|
227
|
-
- Exploitability is treated as research. The report names attacker-controlled values, useful primitives, realistic routes, constraints, fallbacks,
|
|
228
|
-
reliability dependencies, and dead ends that teach something.
|
|
229
|
-
- The PoC section separates diagnostic probes from the strongest exploit or demonstration path, gives a safe-first run order, and includes representative output.
|
|
230
|
-
- Remediation explains the invariant to restore, then gives minimal fixes,
|
|
231
|
-
deeper structural hardening where useful, and regression tests that exercise the real vulnerable path.
|
|
232
|
-
- The language is precise, calm, and conversationally professional. It should not read like a terse scanner finding, a marketing advisory, or a pile of disconnected notes.
|
|
233
|
-
- The voice sounds like a researcher writing to peers. First-person plural carries the reader through the substantive source, exploitability, and PoC reasoning rather than appearing once as decoration. First-person singular gives an honest account of actual source review, validation work, failed attempts, and limits.
|
|
234
|
-
- The prose explains why each important transition matters. A complete set of headings, snippets, and conclusions is not enough when the connective reasoning remains implicit.
|
|
152
|
+
Prove the vulnerability in causal order. Establish the named actor and controlled input, show the real reachable entry point, explain what the software should prevent, carry the relevant value or object through each meaningful step, identify the check or behaviour that fails, and demonstrate the resulting effect at the real sink. In a cross-component finding, show the normal per-component protection first, then the shared key or state, the receiving library's decision and the downstream effect; explain why each excerpt changes the outcome. Quote only short, exact snippets that contain the decisive line. Cite the repository-relative path, function and verified release without repeatedly attaching commit hashes. Explain both what an excerpt proves and the material question it leaves open.
|
|
235
153
|
|
|
236
|
-
|
|
154
|
+
Compare a real fix only after verifying that it addresses the same vulnerable behaviour and actually prevents the reported attack. Distinguish a proposed defensive patch from an upstream fix. Establish introduction, affected-version boundaries, fixed releases and backports using inspected source history and released code; explicitly flag missing release history.
|
|
237
155
|
|
|
238
|
-
-
|
|
239
|
-
- Does the report prove the vulnerable path from source and cite the exact functions, files, and revisions that matter?
|
|
240
|
-
- Are code snippets chosen because they illuminate the story, not because the report needed decoration?
|
|
241
|
-
- Does every snippet include the decisive line or branch it is meant to prove,
|
|
242
|
-
rather than cutting off just before the vulnerability?
|
|
243
|
-
- Does the exploitability analysis explore multiple realistic paths,
|
|
244
|
-
including constraints and dead ends that sharpen the conclusion?
|
|
245
|
-
- Is there a high-quality final PoC with build/run commands and example output, or a clear reason why execution was not authorized or safe?
|
|
246
|
-
- Does the remediation explain the invariant that must be restored and show a plausible minimal patch or defensive pattern?
|
|
247
|
-
- Does the report use a natural "we" voice through the walkthrough and include a truthful "I" account of what the author validated or could not test?
|
|
248
|
-
- Does the prose patiently connect the evidence, or does it still read like a technically correct but lightweight scanner expansion?
|
|
156
|
+
Explore stronger exploitation as research, not advertising. Discuss allocator or protocol behaviour, attacker-controlled bytes, timing, identity, configuration, useful primitives and meaningful dead ends when relevant. Distinguish a possible interleaving from production reliability, a bad state from a usable exploit, and local control from a real privilege or tenant boundary crossing.
|
|
249
157
|
|
|
250
|
-
|
|
158
|
+
Use a diagram or state table only when it clarifies a genuinely difficult object lifetime, ownership boundary or event sequence. Do not add visual material, theory or variants to make a simple finding look more impressive.
|
|
251
159
|
|
|
252
|
-
|
|
253
|
-
Check every report against `references/report-format.md`, then run relevant project checks:
|
|
160
|
+
## Report acceptance
|
|
254
161
|
|
|
255
|
-
|
|
256
|
-
- `rg -n '\b(we|We|I|our|Our|us)\b' <report>` as a quick signal for missing researcher voice, followed by a manual read for natural usage;
|
|
257
|
-
- `make -n` in every `poc/` directory (may need to run on the appropriate target system; doesn't necessarily need to build on whichever system the report is being written on);
|
|
258
|
-
- source commands used in the reports, when feasible;
|
|
259
|
-
- a parity check against the original report directory when rewriting.
|
|
162
|
+
Read `references/report-format.md` and the finished report yourself. Accept it only when:
|
|
260
163
|
|
|
261
|
-
|
|
164
|
+
- a new reader can understand the component, the named actors and the relevant security boundary;
|
|
165
|
+
- the verified release, configuration, attacker prerequisites and affected-version history are accurately scoped;
|
|
166
|
+
- the source establishes the same trigger sequence and security failure described in the report, or the user explicitly accepted a report-only assessment and every unavailable source-dependent claim remains visibly conditional;
|
|
167
|
+
- every excerpt is exact, attributed to a repository-relative source path and verified software version, necessary and explained;
|
|
168
|
+
- source proof, inference, reported claims and runtime observation remain distinguishable;
|
|
169
|
+
- meaningful guards, negative controls and alternative explanations are addressed;
|
|
170
|
+
- impact, exploitation reliability, affected versions and deployment prevalence are no stronger than the evidence;
|
|
171
|
+
- the PoC, commands, output and cleanup instructions reflect real artefacts and actual validation;
|
|
172
|
+
- available positive and negative controls rule out the important benign explanations and isolate any tested interim mitigation; when no authorized runtime or verified trace is available, clearly identify those controls as unperformed;
|
|
173
|
+
- the proposed fix explains in plain English what the code must do differently and suggests relevant regression coverage;
|
|
174
|
+
- the narrative sounds like a thoughtful human researcher, not a scanner, marketing copy or a checklist;
|
|
175
|
+
- each supporting observation is identified in concrete language, without calling unexplained evidence a "witness";
|
|
176
|
+
- Alice, Bob, Mallory and Eve are used only in their appropriate roles, with consistent example usernames;
|
|
177
|
+
- release numbers carry the explanation, and commit hashes appear only when they add specific value;
|
|
178
|
+
- `we` genuinely carries the explanation and `I` accurately describes performed work and its limits;
|
|
179
|
+
- the report and every distributed PoC, script, build file and output contain no author-machine-specific absolute paths, internal provenance, placeholder text or fabricated detail; retain an absolute target-system path when it is necessary to describe or reproduce the verified vulnerability.
|
|
262
180
|
|
|
263
|
-
|
|
181
|
+
Validate the report's Markdown, required headings, and any front matter against `references/report-format.md`; run an actual report-specific validator only when the repository supplies one. Search every distributable report, PoC, build file, script and captured output for author-machine-specific macOS, Linux and Windows absolute paths, including local user-home, temporary, checkout and `file://` paths; remove those details without deleting absolute target-system paths that are essential to the verified behavior. Run relevant real PoC build or dry-run checks only when they exist, are safe and are supported by the target environment. When a disclosure package also contains an advisory, validate the technical report against the report-format reference without misclassifying the advisory or changing the final package layout. Re-run any supplied offline evidence verifier and ensure generated bytecode or local-path leakage does not enter the package. A word search can help identify accidental provenance or missing researcher voice, but neither a pronoun count nor required headings can establish factual accuracy.
|