From 9232085f311df57a7f9d860a5beb167e830421db Mon Sep 17 00:00:00 2001 From: Michael D'Angelo Date: Mon, 3 Aug 2026 18:56:11 -0700 Subject: [PATCH 1/4] docs: improve vulnerability writeup quality --- .../skills/vulnerability-writeup/SKILL.md | 372 +++++++----------- .../references/report-format.md | 121 +++--- 2 files changed, 198 insertions(+), 295 deletions(-) diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md index 593a85ff..0bf43cc8 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md @@ -1,263 +1,181 @@ --- name: vulnerability-writeup -description: Write up vulnerabilities from disclosure documents, rough notes, supplied findings, PoCs, source code, or Codex Security scan output into polished, self-contained, source-backed reports. Use for one vulnerability or a disclosure campaign; a Codex Security scan is optional. +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. --- # Vulnerability Writeup -## Overview - -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, -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. - -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. - -## Core Rules - -- Use one sub-agent per vulnerability write-up. Do not assign multiple vulnerabilities to one worker. -- 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. -- The main agent owns inventory and deduplication. Workers receive only the single vulnerability they are writing. -- Review every sub-agent report yourself before accepting it. -- If a report falls short, run another sub-agent for that same vulnerability with the raw artifacts and a concise critique. -- 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. -- 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. -- Never guess missing technical detail. Read source, inspect commits, run safe experiments, and clearly separate validated facts from hypotheses. -- Use lab or VM access only when it is explicitly authorized for this work. - Never test against public or live production instances unless the user has explicitly instructed you to do so for that target. -- Make reports self-contained and distributable. Do not mention Drive, - internal provenance, local absolute paths, or prior working folders. -- 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. -- Prefer readable, terminal-friendly line wrapping when it does not make the prose awkward. Do not let line length rules damage clarity, links, tables, - code references, or the natural rhythm of the report. -- Prefer source-backed narrative over labels. Each report should tell the full story: trigger, vulnerable path, bad state, impact, PoC, and fix. -- Vulnerabilities sometimes have several different options for exploitation. - 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. -- Treat PoCs as first-class deliverables. The final report directory should contain clean PoC source, build/run instructions, representative output, - and any reliability, cleanup, or target-environment notes the reader needs. - If you feel it's not possible to develop a PoC, ask the user for guidance. - -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, -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. - -## Inputs - -Gather and preserve these inputs before drafting: - -- raw vulnerability documents, exported text, or existing rough reports; -- supplied scanner findings or Codex Security finding bundles, when present; -- existing PoCs, scripts, crash logs, traces, and screenshots; -- the target source tree and exact vulnerable revision or release tag; -- a focused inventory of relevant source paths, functions, and revisions when available; -- fix commits, upstream diffs, or advisory text when available; -- lab access details such as SSH hosts, VMs, kernels, or test accounts; -- the user's authorization boundary for testing, especially whether any live target is in scope. - -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. - -The produced write-ups must be distributable on their own and not assume access to other files or systems. - -## Campaign Workflow - -1. Create a destination directory, usually `reports` or the user-provided name. Use short, representative slug names. -2. Build an inventory of candidate documents and PoCs. Record title, - subsystem, primitive, affected paths, and likely duplicates. -3. Deduplicate by root cause and vulnerable code path, not by document title. - Merge notes and PoCs that describe the same bug. -4. Read `references/report-format.md` in full and use it as the report format. - Instruct every worker to do the same before drafting. -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, - revision, fix diff, or build instructions before drafting, or proceed at explicitly lower confidence when the user accepts that limitation. -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. -7. For each distinct vulnerability, create one directory containing an appropriately-named report file as markdown (e.g. `freebsd-shm-uaf.md`) - and a `poc/` directory when PoCs exist. Don't just use a nondescript file name like `report.md`. -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. -9. Review the worker output immediately. Check technical correctness, - completeness, line wrapping, self-contained wording, source snippets, - 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. -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, - 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. -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. -12. Run final validation over the whole report set before returning. - -## Sub-Agent Prompt - -Use a prompt shaped like this for each vulnerability: +## Purpose -```text -Write one high-quality vulnerability disclosure report for . +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. -You are responsible for exactly one vulnerability. Do not write about, -summarize, compare, or polish any other finding. Quality drops when one -worker handles multiple bugs, so keep all attention on this single report. +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. -Inputs: -- Raw notes: -- Existing rough report, if any: -- PoC artifacts: -- Focused source paths and excerpts: -- Target source tree: -- Vulnerable revision/release: -- Fix commits/diffs, if any: -- Lab access: -- Testing authorization boundary: -- Required format: `references/report-format.md`. -- Output directory: / - -Rules: -- Before drafting, open and read `references/report-format.md` in full. Its - headings are the beginning of the assignment, not a completeness checklist. -- Analyze source and fixes directly; never guess. Trace the bug from the - attacker-controlled entry point through the relevant state transitions to - the bad state. -- Treat supplied snippets as starting points. If a snippet ends before the - decisive branch, guard, sink, lifetime transition, or patch invariant, - reopen the source tree and quote a complete short snippet instead. -- Use the source tree throughout the report. Include short, relevant snippets - with file paths, functions, and enough surrounding explanation for a human - reader to follow the path without opening the repository. -- Treat the rough notes as leads, not gospel. Validate each claim against the - vulnerable source, the fix diff, or an experiment. Correct the notes when - the source proves them incomplete or slightly wrong. -- Explore exploitability, not just reachability. Discuss viable primitives, - constraints, allocator or protocol behavior, race windows, object lifetime, - attacker-controlled bytes, reliability, and useful dead ends. Build small - throwaway probes when they clarify an exploit path. -- Verify or improve the PoC when safe and authorized. Prefer disposable VMs - or local test targets for crashes, corruption, LPE, data loss, or denial of - service. Never run against public or live production instances unless the - authorization boundary explicitly allows that target. -- Ship a polished final PoC in `poc/`. Include source, build files, a README - when helpful, exact run commands using relative paths, required environment - details, expected output, and notes on reliability or cleanup. -- Produce a self-contained report markdown file with no provenance references - and no local absolute paths. -- Use a natural first-person researcher voice in the report itself. Guide the - reader with "we" across the substantive walkthrough: introduce why each - source excerpt matters, carry values and object state between functions, - reason through exploit options, and explain PoC behavior. Do not leave the - reader with a dense sequence of snippets and declarative conclusions. -- Include at least one truthful first-person-singular account of the validation - basis and limits. For example: "I reviewed the vulnerable revision and fix - directly, but I did not execute the panic trigger because no disposable VM - was available." Mention builds, experiments, failures, or observations only - when they actually happened. -- Give important transitions enough prose to teach why the evidence matters. - Explore promising exploitation routes, relevant alternatives, constraints, - and informative dead ends instead of collapsing exploitability into a verdict - paragraph. Add depth where the bug warrants it; do not pad the report. -- Prefer readable prose wrapping, but do not contort technical language, - links, tables, or code references to satisfy a fixed column width. -- Explain trigger, vulnerable path, bad state, impact, exploitability, PoC, - and fix as one coherent narrative. The reader should feel calmly guided - from background to source proof to practical demonstration. -- Use relative commands such as `cd poc` then `make`, not local absolute - paths. -``` +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. -When re-running a weak report, add only the review deltas: +## Non-negotiable rules -```text -The prior draft was too light on . Rewrite from the raw -artifacts and source so the report reads as a complete technical story. Use -"we" to guide the actual source and exploitation walkthrough, and state with -"I" what you personally validated and what you could not test. Do not merely -add first-person phrases to the existing prose. -``` +- 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. +- During Codex Security final reporting, the scan request authorises those one-finding drafting sub-agents. Do not request separate delegation approval. +- Inspect the exact vulnerable source revision. 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. +- 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. +- 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. +- 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. +- 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. +- 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. +- 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. +- 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. +- 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. +- 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. +- Make every delivered report and PoC portable and self-contained. Use repository-relative source paths, report-relative commands and verified software versions. Never include a local absolute path in report prose, excerpts, citations, links, PoC code, build files, command examples or captured output. + +## Actors, language and release references + +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. + +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. -## Technical Analysis Standard +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. -For each report, prove the vulnerability from the target source: +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. -- identify the exact entry point and attacker-controlled inputs; -- follow data, lifetime, locking, bounds, and state transitions; -- quote short source snippets only when they clarify the path; -- inspect vulnerable release code with commands like `git show :`; -- compare fix commits when available to confirm the intended invariant; -- describe the resulting kernel or application state precisely; -- calibrate impact to the validated primitive; -- name assumptions and unverified exploitability limits. +## Trace affected release history -### Source Work +Before drafting, inspect the history of the actual vulnerable code rather than assuming the current version has always behaved this way. -The worker should use the repository as a primary artifact: +1. Identify the exact lines, check, state change or permission decision that makes the reported attack possible. +2. Trace that behaviour through file history, renames and blame to identify the change that introduced it. +3. Inspect release tags and maintained branches to find the earliest released version that actually contains the vulnerable behaviour. +4. Inspect the fixing change and each relevant release branch to determine the first fixed version and any backported fixes. +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. +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. -- inspect the vulnerable revision, not just the current tree; -- use `git show :` when the source tree is a Git checkout and the scanned revision is available; -- identify relevant compile-time options, configuration, permissions, and threat-model checks; -- search for sibling call sites and variants that help explain the invariant; -- include snippets from vulnerable code and, when useful, the fixing diff; -- keep snippets short and narrate the important lines before or after them. +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. -### Exploitability Work +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. -The Exploitability Analysis section should be thoughtful and specific. It may include unsuccessful branches when they teach the reader something important. -Useful lines of inquiry include: +## Evidence-first intake -- how to maximize attacker control over corrupted data or control flow; -- how allocator, scheduler, parser, cache, sandbox, or protocol behavior affects reliability; -- how to groom state before the trigger and stabilize state afterward; -- what information leaks, write gadgets, confused-deputy paths, or privilege boundaries might combine with the primitive; -- what constraints make a stronger exploit unlikely. +Before drafting, inventory: -### PoC Work +- the raw finding, report, disclosure notes and claimed trigger; +- the exact source root, assessed release and privately pinned commit or tag; +- the introducing change, earliest verified affected release, affected release branches, fixing change and verified fixed or backported releases; +- the affected paths, functions, configuration and build options; +- Alice, Bob, Mallory or Eve as appropriate, together with each person's actual account, required credentials, privileges and controlled input; +- the affected owner, intended recipient, security boundary and downstream consumer; +- the claimed impact and the narrower primitive actually supported; +- any PoC, logs, negative control, regression test and available fix; +- what was read, built, executed, observed, merely supplied or not available; +- the testing authorisation and any disposable test environment. -Use the lab to build PoCs and run safe probes. For panic, wedge, corruption, -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. +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. -A strong final PoC should be easy for the reader to run: +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. -- place it under the report directory's `poc/` folder; -- include a `Makefile`, script, container recipe, or exact build command; -- include example commands from a clean checkout or unpacked report bundle; -- include representative output from a successful run; -- separate exploratory probes from the polished final PoC when both are kept; -- include cleanup or reset instructions when the PoC changes system state. +Challenge the claim before making it sound convincing: -## Report Quality Bar +- Is the required configuration default, optional, unusual or unknown? Documentation and shipped examples establish existence, not prevalence. +- Does the attacker already need the access or privilege that the report claims to obtain? +- Does the exact source preserve the reported object ownership, callback order, lock, lifetime, bounds, validation order and final sink? +- Can cancellation, generation checks, error handling, cleanup, permissions or another guard prevent the path? +- Does a controlled test change only timing or visibility, or can it create the outcome itself? +- What negative control or concrete observation would distinguish the claimed vulnerability from a benign explanation? +- Does the evidence establish reachability, a bad state, a real boundary crossing or only a stronger impact that remains possible? + +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. + +## Campaign workflow + +1. Create the user-requested report directory, or use `reports/`. Inventory and deduplicate findings by root cause and source path rather than title. +2. Read `references/report-format.md` completely. Require each drafting sub-agent to read it before writing. +3. Pin and inspect each finding's vulnerable source. Independently check the decisive entry point, security check, state change, sink and available fix. Trace the introducing change and inspect the affected and fixed release tags before assigning the finding. +4. Record the one-sentence attack and non-claims, verified release history, named actors, complete tested topology, defaults versus configured prerequisites, meaningful positive and negative controls, exact validation basis and testing boundary before assigning the finding. +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. +6. Launch exactly one sub-agent for each distinct vulnerability. Provide only that vulnerability's raw material, pinned source, PoC artefacts, output directory, report-format reference and authorisation boundary. +7. Independently read the returned report against the pinned source, release history and raw artefacts. Check each important claim, excerpt, transition, affected-version statement, impact, fix and reported observation. +8. Reject a draft that smooths over missing evidence, invents a run, inflates impact, guesses affected versions, leaks a local 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. +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. +10. Make only small final corrections after acceptance, and validate the completed report and real PoC artefacts before delivery. + +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. + +## Single-finding drafting prompt + +Use this shape and supply the actual evidence: + +```text +Write one self-contained vulnerability disclosure report for . -Every accepted report must follow the guidance in `references/report-format.md`. +You own exactly one finding. Read references/report-format.md completely before drafting. -The report should read like a complete story for a security engineer who has not seen the original notes. It should patiently walk the reader from the entry point to the vulnerable transition, the bad state, exploitation routes, -PoC behavior, and the fix. Avoid filler, generic variant-analysis endings, -and claims unsupported by source or experiment, but include thoughtful discussion and maintain a warm, professional attitude: the voice of one security researcher carefully explaining the work to another. +Inputs: +- Raw finding and rough report: +- Source root and privately pinned vulnerable revision: +- Assessed release and verified affected versions: +- Introducing and fixing changes: +- Relevant source paths, functions and claimed trigger:
+- Existing PoC, logs and negative controls: +- Fix or advisory, if directly available: +- Attacker prerequisites and configuration: +- Named actors and usernames: +- Testing authorisation and disposable lab: +- Report and PoC output directory: + +Treat the supplied finding as a hypothesis. Inspect the exact source revision yourself. 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. + +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. + +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. + +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. + +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. + +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. + +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. + +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 a local absolute path into the report, PoC, build recipe, screenshots, logs or output. + +Before returning, reread the report against the exact source, release history, PoC and fix. Remove generic filler, unsupported certainty, repeated commit hashes, jargon, inconsistent actor names, repetitive proof labels, token first-person phrases, local absolute paths and claims the artefacts cannot support. +``` + +For a rewrite, give the replacement worker the original evidence and precise failed checks, not merely the previous prose: + +```text +The previous draft incorrectly or inadequately handled . 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. +``` -An excellent report usually has a few recognizable traits: +## Source and exploitability standard -- The proof is layered. It establishes the actor, entry point, vulnerable check, bad transformation or state transition, sink, and fixed source shape in an order that feels easy to follow. -- Exploitability is treated as research. The report names attacker-controlled values, useful primitives, realistic routes, constraints, fallbacks, - reliability dependencies, and dead ends that teach something. -- The PoC section separates diagnostic probes from the strongest exploit or demonstration path, gives a safe-first run order, and includes representative output. -- Remediation explains the invariant to restore, then gives minimal fixes, - deeper structural hardening where useful, and regression tests that exercise the real vulnerable path. -- 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. -- 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. -- 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. +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. -Before accepting a report, ask whether it reaches the excellent bar: +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. -- Can a reader understand the affected component and threat model without the original notes? -- Does the report prove the vulnerable path from source and cite the exact functions, files, and revisions that matter? -- Are code snippets chosen because they illuminate the story, not because the report needed decoration? -- Does every snippet include the decisive line or branch it is meant to prove, - rather than cutting off just before the vulnerability? -- Does the exploitability analysis explore multiple realistic paths, - including constraints and dead ends that sharpen the conclusion? -- 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? -- Does the remediation explain the invariant that must be restored and show a plausible minimal patch or defensive pattern? -- 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? -- Does the prose patiently connect the evidence, or does it still read like a technically correct but lightweight scanner expansion? +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. -## Validation +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. -Review the completed report set directly after drafting and after any rewrite. -Check every report against `references/report-format.md`, then run relevant project checks: +## Report acceptance -- `rg` for forbidden provenance terms and TODO markers; -- `rg -n '\b(we|We|I|our|Our|us)\b' ` as a quick signal for missing researcher voice, followed by a manual read for natural usage; -- `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); -- source commands used in the reports, when feasible; -- a parity check against the original report directory when rewriting. +Read `references/report-format.md` and the finished report yourself. Accept it only when: -Do not hand off until validation passes or the remaining failures are explicitly explained to the user. +- a new reader can understand the component, the named actors and the relevant security boundary; +- the verified release, configuration, attacker prerequisites and affected-version history are accurately scoped; +- the source establishes the same trigger sequence and security failure described in the report; +- every excerpt is exact, attributed to a repository-relative source path and verified software version, necessary and explained; +- source proof, inference, reported claims and runtime observation remain distinguishable; +- meaningful guards, negative controls and alternative explanations are addressed; +- impact, exploitation reliability, affected versions and deployment prevalence are no stronger than the evidence; +- the PoC, commands, output and cleanup instructions reflect real artefacts and actual validation; +- positive and negative controls rule out the important benign explanations and isolate any tested interim mitigation; +- the proposed fix explains in plain English what the code must do differently and suggests relevant regression coverage; +- the narrative sounds like a thoughtful human researcher, not a scanner, marketing copy or a checklist; +- each supporting observation is identified in concrete language, without calling unexplained evidence a "witness"; +- Alice, Bob, Mallory and Eve are used only in their appropriate roles, with consistent example usernames; +- release numbers carry the explanation, and commit hashes appear only when they add specific value; +- `we` genuinely carries the explanation and `I` accurately describes performed work and its limits; +- the report and every distributed PoC, script, build file and output contain no local absolute paths, internal provenance, placeholder text or fabricated detail. -A report with no natural first-person walkthrough, or no truthful singular account of the validation basis and limits, fails validation and must be rewritten. A mechanical pronoun match does not make an impersonal report pass. +Validate front matter and Markdown formatting with the repository's plugin authoring validator. Search every distributable report, PoC, build file, script and captured output for local macOS, Linux and Windows absolute paths, including user-home, temporary, checkout and `file://` paths; remove every match before delivery. 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 one direct technical report through an isolated temporary validation directory or link rather than 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. diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md index abf613a8..caffd3f0 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md @@ -1,104 +1,89 @@ # Vulnerability Report Format -Use this guide to write a comprehensive vulnerability report that covers the details of a vulnerability, considers options for exploitation and walks the reader through the most effective steps to trigger the bug. +Write one self-contained Markdown report for a technically experienced security engineer who has not seen the original finding. The report should read like one careful researcher guiding another from the affected component and attacker prerequisites through the exact vulnerable source, demonstrated impact and appropriate fix. -The report should be written in markdown. Use language hints in code snippets to indicate programming language -- e.g. use ```c rather than just ```. Choose an appropriate file name for the report that makes it clear what the vulnerability is at a glance. For example, `freebsd-shm-ftruncate-uaf-lpe.md`. -Don't just choose the name `report.md` or anything nondescript like that. +Use the language and locale requested by the user, or their normal default when unstated, with a warm professional voice and direct technical language. Let `we` guide real reasoning: carry the same input, object or state between relevant excerpts and explain why each step matters. Use `I` only for what the author actually reviewed, built, ran, observed or could not test. Explain the expected behaviour and the actual failure in plain language. -Audience: other vulnerability researchers and security engineers with a deep knowledge of software exploitation and software development. The report must be written in clear English and use precise language. Be warm and somewhat friendly in the manner of your writing, but not overly familiar: as you'd expect a technical write-up to read from one expert to another. Don't sound robotic. +Use a specific report filename, such as `freebsd-shm-ftruncate-uaf.md`. Cite repository-relative paths, functions and verified release versions. Give fenced source excerpts the correct language. Use one natural source line per instruction paragraph or list item; do not hard-wrap Markdown prose in the middle of a sentence. -Use a natural first-person researcher voice. The report should regularly guide the reader with language such as "we first reach this branch", "if we carry this value into the next call", "from here we control the length field", or -"we can now compare this with the fixed path". Use that voice in the real source, exploitability, and PoC walkthrough—not only in an introduction or summary. +## Evidence and voice -Use first-person singular for actual work the report author performed and for its limits, such as "I reviewed the vulnerable revision and the fixing diff", -"I reproduced this on", "I did not get a stable shell", or "I could not exercise this path without a kernel fault-injection hook". Every report must include a truthful singular account of its validation basis. Static source review counts; do not imply that code was built or executed when it was not. -Never invent personal observations. +Start with evidence, not confidence. Before calling a finding exploitable, establish the assessed software version, configuration, attacker capability, reachable path, the security behaviour that should have held and the narrowest demonstrated boundary crossing. Open with the actual attack in ordinary language: name Mallory's legitimate starting credential or input, the separate owner or policy she crosses and the real sink she reaches. Immediately state important non-claims, such as that she reused her own session rather than stealing someone else's or breaking a protocol. Treat supplied notes, unexecuted PoCs and reported traces as claims until the underlying source or runtime artefact is actually inspected. -First person is a narrative tool, not a quota. Do not retrofit an impersonal draft by scattering "we can see" through it. The reader should feel accompanied through the reasoning: why a snippet matters, what state we carry forward, why one exploitation route looks promising, and what an experiment did or did not establish. +Introduce classic named actors when they clarify the story: Alice is the legitimate owner, Bob is another legitimate user or intended recipient, Mallory is the active attacker, and Eve is a passive eavesdropper. Carry `alice`, `bob`, `mallory` and `eve` into example account names, requests, commands and PoC output. Introduce only the actors the actual vulnerability needs and preserve the product's real account roles and permissions. -Talk through the details that matter and don't gloss over things or skip them when they add value. +Keep the differences between exact source, inspected PoC code, observed execution, supplied reports, inference and unknowns clear in natural prose. Do not mechanically prefix every sentence with an evidence label or add a generic confidence disclaimer to every section. -The quality target is the "excellent" style of report: a source-backed story that patiently proves the vulnerable path, explores exploitation like a researcher actually working the bug, and leaves the reader with artifacts they can build and run. Do not settle for a short triage note with section headings. +Do not describe supporting material as a "witness". Name the specific thing the reader can inspect: a source excerpt showing the missing check, Mallory's request for Alice's document, the server response disclosing that document, a failing test, an input that triggers memory corruption, a captured execution trace, or an observed PoC result. Explain what that particular example establishes. If a genuine source symbol or required field is literally named `witness`, quote it accurately and immediately explain its actual purpose. -Excellent reports usually do these things: +Trace the vulnerable behaviour back to its introducing change, inspect release tags and maintained branches, and verify fixed releases or backports. Do not let a shallow checkout end the investigation when complete history or exact release archives can be obtained safely. Tell that history primarily through public version numbers, and explain what the introducing change was meant to fix when that explains the root cause. Give the first affected and first fixed release only when confirmed against actual release snapshots. When older tags, history or branch coverage are unavailable, say `the earliest version I could verify` rather than inventing a definitive affected range; name unsampled patch releases or branch tips instead of implying they were checked. -- establish the actor, reachable entry point, affected component, and exact source/revision basis early; -- walk the reader through the relevant call chain or state machine before naming the bug; -- use short source snippets with file paths and function names, then explain the important lines in prose; -- show the bad state with concrete values, type conversions, lifetime edges, - bounds, lock transitions, parser states, or protocol fields; -- compare the fixed source shape when a fix exists, and explain the invariant the fix restores; -- treat exploitability as research, not a verdict. Discuss promising paths, - constraints, architecture or configuration dependencies, and dead ends that clarify the primitive; -- include small probes or exploratory PoCs when they helped refine the final exploit story; -- ship a clean final PoC with build/run commands and representative output. +Do not invent an affected-version range, introduction date, fixed release, deployment prevalence, default configuration, reliable race, root shell, tenant crossing, CVE, CVSS score, log or expected result. A documented configuration establishes that the configuration exists; it does not establish that most deployments enable it. A timing-controlled test establishes a controlled ordering; it does not establish production reliability. -Use readable prose wrapping. Terminal-friendly line lengths are welcome when they fit naturally, but do not damage clarity, links, tables, code references, or the rhythm of the explanation to satisfy a fixed column width. +Avoid abstract security jargon, grand claims, dramatic severity language, marketing phrasing, repetitive signposting, empty praise, token `we can see` sentences and conclusions disconnected from the evidence. Describe what should have happened, what happens instead and why it affects Alice or benefits Mallory. Prefer the exact small fact that the source proves. -The report must be written using the high-level structure that follows. Use the headings as there are listed here for each section and include sub-sections (and even sub-sub sections if really necessary) judiciously to cleanly and logically organise the content. +Do not fill the report with Git hashes. Pin the exact source privately, cite the public software version and relevant repository-relative path in the report, and mention a short commit reference only when a specific introducing or fixing change genuinely matters or when no released version exists. -## Quality Bar +Never include a local absolute filesystem path anywhere in the distributable report or PoC. This applies to prose, source citations, links, shell commands, build files, comments, screenshots and captured terminal output. Use repository-relative or report-relative paths and remove local user-home, temporary, checkout and `file://` paths from included material. -The report should feel like a warm, professional technical walk-through from one security researcher to another. It should not read like a scanner result, -a terse triage note, or a stitched-together collection of bullets. The reader should be guided through the component, the reachable entry point, the vulnerable transition, the bad state, exploitation options, PoC behavior, and the fix in a coherent order. +The final report must contain the following seven headings, in this order. -Strong write-ups generally have these qualities: +## Executive Summary -- The proof is layered: actor, entry point, relevant state, vulnerable check, - bad transformation or lifetime edge, sink, and fixed source shape. -- Source snippets are short and purposeful. Each snippet should be introduced or explained so the important lines are obvious without opening the repository. -- Exploitability is explored like research. Discuss attacker-controlled values, useful primitives, realistic routes, constraints, fallbacks, - reliability dependencies, and dead ends that clarify the primitive. -- PoC material is first-class. Separate diagnostic probes from the strongest final demonstration when both are included, give a safe-first run order, - and include representative output. -- Remediation explains the invariant to restore before showing code. It should also name regression tests that exercise the real vulnerable path and nearby variants. -- The tone is calm, precise, and conversationally professional: confident enough to be useful, careful enough not to overclaim. The voice should feel like a researcher writing to peers, with natural "we" walkthrough language and honest "I" statements for experiments actually performed. -- The prose contains the connective reasoning between source excerpts and conclusions. A report that has all required headings but reduces the bug to a sequence of snippets, terse facts, and verdicts is still incomplete. -- The validation basis is personal and precise: what I inspected, built, ran, - observed, or could not test. The rest of the technical story uses "we" to make difficult control flow and exploitation reasoning comfortable to follow. +Name the component, assessed software version, required attacker position, essential configuration, vulnerable operation and narrowest demonstrated impact. State the verified first affected release, affected release range and fixed release when established by source history and inspected release snapshots. Distinguish the earliest release inspected from an unproven first affected version, and separate a plausible stronger effect from a demonstrated one. -The structure must contain the following headings: +Use the first paragraph to tell the concrete attack and its limits, not to announce a generic vulnerability class. Say who Mallory is, what legitimate access she starts with, which separate boundary should stop her, what happens instead and whether this is distinct from session theft, a protocol flaw or another tempting but unsupported explanation. -1. **Executive Summary**: Summarise what the vulnerability is, which versions of the software are affected, what the impact is and what it allows an attacker to do. Include the validation basis: source revision, fixed revision if known, lab target, and what was or was not executed. State this basis in a truthful first-person-singular sentence (for example, "I reviewed revision X directly, but I did not execute the trigger"). If exact advisory names, CVEs, or patch-level claims are uncertain, say that rather than overstating them. As well as the affected versions, it's often interesting to note how long ago the vulnerability was introduced to give the reader a sense of how ubiquitous it is. +Include a truthful first-person statement of the validation basis. For example: `I reviewed the affected release, its earlier release history and the fix directly; I did not execute the trigger because no disposable test machine was available.` Do not imply that source review reproduced an exploit. -2. **Background**: Provide a technical background to set the scene. Describe, - briefly, the relevant part of the software functionality. Assume the audience is technically strong, but not necessarily intimately familiar with the relevant part of the attack surface or threat model (including actors). This section should introduce the objects, callbacks, permission model, configuration, and normal invariants needed to understand the bug. - Use source snippets here when they establish the reachable surface or the security boundary. +## Background -3. **Vulnerability Details**: Continue naturally on from the Background section, but now work towards a full-detail walk-through of how the vulnerable code is reached and what the issue is. Tie this in with the mise-en-scène established so far so that the story of who can reach the code, by what means, and how the relevant input carries through is clear to the reader. Prove the bug from source: entry point, attacker-controlled fields, checks that should have protected the path, the exact missed invariant, and the resulting bad state. Concrete arithmetic, type truncation, lifetime diagrams, state tables, or before/after values are often more persuasive than broad claims. +Introduce only the component behaviour, named actors, controlled values, ownership, privilege boundary and expected security behaviour needed to understand this finding. Put the complete tested topology and prerequisites near the beginning. Separate default behaviour from opt-in configuration and deployment assumptions without guessing prevalence. -4. **Exploitability Analysis**: By this point, the reader understands the full threat model context of the vulnerability and the story of how the bad state can be reached. This section should now focus on how it's possible to maximally capitalise on the vulnerability: for example, if relevant, how does the underlying heap allocator work and be groomed to arrange data in a favourable manner, or what kind of control do we have over any objects/data we can corrupt, etc. This is an excellent opportunity for both drawing on prior art and also being creative in how unique aspects of the vulnerability can be tackled. Including diagrams and small, self-contained PoCs to trigger these aspects is especially useful. An excellent PoC demonstrates leveraging the vulnerability to the maximum within reason. - E.g. dropping to a stable interactive root shell, or confidently leaking a pointer to something useful, or achieving reliable command injection, etc. - (this will vary according to what the vulnerability is). Include multiple realistic exploitation routes when they exist. It is useful to preserve failed or partial branches when they teach an important constraint, such as allocator behavior, address-space layout, sandbox permissions, protocol sequencing, or object lifetime. +If the attack involves similar objects or values, name them concretely and preserve that distinction throughout the report. For example, distinguish `alice`'s document from Mallory's authenticated `mallory` session. Include a short source excerpt only when it establishes the real entry point, security boundary or normal behaviour. - Write this as an investigation rather than a severity verdict. Walk through the strongest route with "we", then discuss meaningful alternatives, - reliability constraints, and dead ends when they sharpen the conclusion. - Spend prose on the hard or surprising parts; do not pad simple mechanics. +## Vulnerability Details -5. **Proof of Concept**: This should tie together all of the exploration and creative process performed in the Exploitability Analysis section into a maximally-effective and stable proof-of-concept that can be used with minimal configuration against the target. Don't just mention that a PoC is included: describe the approach it takes, any notes about reliability, and provide sample output from building and running it. Include exact relative commands from the report directory, expected output on vulnerable and fixed targets when possible, target requirements, cleanup instructions, and a clear warning when the PoC can crash, corrupt, delete data, or escalate on the test machine. Keep exploratory probes separate from the polished final PoC when both are included. +Follow the reported trigger in causal order. Begin with Mallory's actual controlled input, inspect each material check or state change and show the precise line where the code fails to enforce the expected behaviour. First establish that each ordinary policy or ownership check is configured correctly, then show the shared state, receiving component or dependency decision and real downstream operation that bypasses it. Carry the same request, object, field or state through that whole path. When a named attacker does not fit the actual mechanism, describe the real actor without forcing the example. -6. **Remediation**: Explain the most effective way to patch the vulnerability. - Include a minimal code snippet on a proposed patch that would fix it. Also make suggestions about how the surrounding structure or other parts of the project could be improved or hardened to prevent the vulnerability. Explain the invariant in plain technical terms before showing the patch, and point to regression tests that would catch the original failure and nearby variants. This is a good location to include diagrams or flow charts, for instance. +Identify the repository-relative source path, function and assessed software version for each excerpt. For a runtime-tested vendor or distribution package, verify excerpts and line numbers against that exact patched source; do not quote a nearby upstream tag as if it ran. Cite relevant dependency code in causal order and explain concrete log or trace fields in plain English. Quote only the lines necessary to establish the decisive behaviour, then explain what they prove and what remains unverified. Refer to each demonstration by what it actually is, such as `Mallory's request`, `the returned document`, `the failing test` or `the execution trace`, rather than using an unexplained evidence label. Address relevant validation, locking, cancellation, cleanup, permissions, timing and alternative explanations rather than assuming they cannot prevent the path. -7. **Summary**: Summarise what the impact of the vulnerability is, why the vulnerability is present and what we demonstrated through the story told in this report. Suggest areas of future research, such as where variant analysis may be effective or whether some part of the codebase "feels" - complex or underprotected. +Explain how the vulnerable behaviour entered the project and which released versions contain it. Use a commit reference only where the introduction or fix is materially relevant to that explanation. -The report must also be distributed with proof-of-concept artifacts. These should reside in a directory alongside the report and include the fully-functional, clean, high-quality proof-of-concept code plus any build files needed (e.g. a Makefile). +If the exact source contradicts the claimed sequence, explicitly say so. Do not silently replace the finding with a nearby weaker bug or a more convenient test event. -The PoC directory should be usable from an unpacked report bundle. Prefer relative commands such as: +## Exploitability Analysis + +Start with the narrow primitive the evidence actually establishes. Explain which account, privilege, tenant, process, memory object or availability boundary it can cross under the verified prerequisites. + +Discuss stronger exploitation routes only where the underlying source or authorised experiments support their premises. Explain meaningful constraints such as allocator behaviour, controllable bytes, protocol ordering, configuration, scheduling and cleanup. Label a possible chain or timing window as conditional when it has not been demonstrated. + +Include positive and negative controls that rule out the strongest alternative explanations: show normal allowed access, fresh rejection at the crossed boundary, same-domain success where relevant, the real sink reached only by the attack and any one-setting mitigation that was actually tested. Explain what each control rules out. Do not turn ordinary reachability into remote code execution, an artificial interleaving into production reliability or a different identity into privilege escalation. + +## Proof of Concept + +Identify the real PoC artefacts, target requirements, build steps, execution safety and expected state. Use consistent example account names such as `alice` and `mallory`. Separate exact source review, preserved run records, offline evidence verification, PoC code that was inspected, a syntax or build check that succeeded, a convenience reproducer that was assembled but not run, source-confirmed releases and a run that was actually observed. + +Use relative commands from the distributable report directory, for example: ```sh cd poc make -./exploit_or_probe +./poc ``` -The report should include representative output, for example: +Include command output only when generated by the author or directly verified in a supplied trace. Explain what each request, response, test run or output line actually shows instead of referring to it as a "witness". Remove local absolute paths from genuine captured output without inventing results; visibly mark a necessary omission if it matters. If execution was unavailable or unsafe, say why; describe the unobserved result explicitly as expected behaviour, not a successful run. Never fabricate a crash, shell, leaked value, log or fixed-target result. -```text -[+] primitive reached -[+] target state validated -[+] current process is uid=0 euid=0 -``` +Explain any cleanup and warn clearly when a PoC could corrupt data, exhaust resources, crash a machine or change privileges. If no real PoC can safely be developed, explain the limitation instead of inventing an artefact. + +## Remediation + +Explain in plain English what the fixed code must do: for example, check that the requested document belongs to Alice before returning it to the signed-in user, or accept a resumed session only when the current effective authentication policy also accepts the identity recorded in it. Name every policy input that must remain distinct, preserve that distinction through serialisation or restoration and include it in shared lookup keys where relevant. Provide a small, source-compatible proposed fix when the surrounding source supports it, or cite and explain an inspected upstream fix. Clearly distinguish proposed remediation from a fix that has actually shipped and identify the verified fixed release when known. + +Recommend regression tests covering the real entry point, the failing state transition, a meaningful negative control and nearby variants where justified. Suggest broader hardening only when it addresses the demonstrated mechanism. + +## Summary + +Restate the verified prerequisites, actual security failure, affected versions and demonstrated impact without upgrading any earlier conditional claim. Briefly identify the most useful remaining validation, exploitation question or related source path only when grounded in the evidence. -Do not include local absolute paths, internal note provenance, or references to the drafting process in the final report. +The report and every file in any sibling `poc/` directory must remain understandable outside the author's environment. Check all Markdown, source, scripts, build recipes and included output for personal-machine and other local absolute paths. Do not include internal storage locations, scanner implementation detail, drafting workflow or placeholders. If the final disclosure package also includes a separate advisory, keep its format separate and validate the technical report through an isolated temporary directory or link so the advisory is not mistaken for a second technical report. From 4281cd36923c1a547a7b168a2548df34ae76daa4 Mon Sep 17 00:00:00 2001 From: Michael D'Angelo Date: Mon, 3 Aug 2026 23:32:45 -0700 Subject: [PATCH 2/4] fix: clarify evidence-aware vulnerability report acceptance --- .../_bundled_plugin/skills/vulnerability-writeup/SKILL.md | 8 ++++---- .../vulnerability-writeup/references/report-format.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md index 0bf43cc8..276a018d 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md @@ -163,19 +163,19 @@ Read `references/report-format.md` and the finished report yourself. Accept it o - a new reader can understand the component, the named actors and the relevant security boundary; - the verified release, configuration, attacker prerequisites and affected-version history are accurately scoped; -- the source establishes the same trigger sequence and security failure described in the report; +- 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; - every excerpt is exact, attributed to a repository-relative source path and verified software version, necessary and explained; - source proof, inference, reported claims and runtime observation remain distinguishable; - meaningful guards, negative controls and alternative explanations are addressed; - impact, exploitation reliability, affected versions and deployment prevalence are no stronger than the evidence; - the PoC, commands, output and cleanup instructions reflect real artefacts and actual validation; -- positive and negative controls rule out the important benign explanations and isolate any tested interim mitigation; +- 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; - the proposed fix explains in plain English what the code must do differently and suggests relevant regression coverage; - the narrative sounds like a thoughtful human researcher, not a scanner, marketing copy or a checklist; - each supporting observation is identified in concrete language, without calling unexplained evidence a "witness"; - Alice, Bob, Mallory and Eve are used only in their appropriate roles, with consistent example usernames; - release numbers carry the explanation, and commit hashes appear only when they add specific value; - `we` genuinely carries the explanation and `I` accurately describes performed work and its limits; -- the report and every distributed PoC, script, build file and output contain no local absolute paths, internal provenance, placeholder text or fabricated detail. +- 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. -Validate front matter and Markdown formatting with the repository's plugin authoring validator. Search every distributable report, PoC, build file, script and captured output for local macOS, Linux and Windows absolute paths, including user-home, temporary, checkout and `file://` paths; remove every match before delivery. 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 one direct technical report through an isolated temporary validation directory or link rather than 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. +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. diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md index caffd3f0..773850d8 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md @@ -24,7 +24,7 @@ Avoid abstract security jargon, grand claims, dramatic severity language, market Do not fill the report with Git hashes. Pin the exact source privately, cite the public software version and relevant repository-relative path in the report, and mention a short commit reference only when a specific introducing or fixing change genuinely matters or when no released version exists. -Never include a local absolute filesystem path anywhere in the distributable report or PoC. This applies to prose, source citations, links, shell commands, build files, comments, screenshots and captured terminal output. Use repository-relative or report-relative paths and remove local user-home, temporary, checkout and `file://` paths from included material. +Never include an author-machine-specific absolute filesystem path anywhere in the distributable report or PoC. This applies to prose, source citations, links, shell commands, build files, comments, screenshots and captured terminal output. Use repository-relative or report-relative paths and remove local user-home, temporary, checkout and `file://` paths from included material. Preserve an absolute target-system path such as `/etc/passwd`, `/proc`, `/dev`, or a Unix-domain socket when that path is necessary to describe or reproduce the verified vulnerability. The final report must contain the following seven headings, in this order. @@ -58,7 +58,7 @@ Start with the narrow primitive the evidence actually establishes. Explain which Discuss stronger exploitation routes only where the underlying source or authorised experiments support their premises. Explain meaningful constraints such as allocator behaviour, controllable bytes, protocol ordering, configuration, scheduling and cleanup. Label a possible chain or timing window as conditional when it has not been demonstrated. -Include positive and negative controls that rule out the strongest alternative explanations: show normal allowed access, fresh rejection at the crossed boundary, same-domain success where relevant, the real sink reached only by the attack and any one-setting mitigation that was actually tested. Explain what each control rules out. Do not turn ordinary reachability into remote code execution, an artificial interleaving into production reliability or a different identity into privilege escalation. +When an authorized disposable target or a verified execution trace is available, include positive and negative controls that rule out the strongest alternative explanations: show normal allowed access, fresh rejection at the crossed boundary, same-domain success where relevant, the real sink reached only by the attack and any one-setting mitigation that was actually tested. Explain what each observed control rules out. When execution or a verified trace is unavailable, describe relevant controls as unperformed validation work rather than implying runtime observations. Do not turn ordinary reachability into remote code execution, an artificial interleaving into production reliability or a different identity into privilege escalation. ## Proof of Concept From e7e1aeeaf4bad6976993be4e668a153eece0872d Mon Sep 17 00:00:00 2001 From: Michael D'Angelo Date: Mon, 3 Aug 2026 23:42:42 -0700 Subject: [PATCH 3/4] docs: clarify report-only source and target path handling --- .../skills/vulnerability-writeup/SKILL.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md index 276a018d..deb7881b 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md @@ -17,9 +17,9 @@ Accept supplied notes, disclosure documents, existing reports, PoCs, source tree - 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. - During Codex Security final reporting, the scan request authorises those one-finding drafting sub-agents. Do not request separate delegation approval. -- Inspect the exact vulnerable source revision. 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. +- 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. - 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. -- 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. +- 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. - 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. - 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. - 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. @@ -27,7 +27,7 @@ Accept supplied notes, disclosure documents, existing reports, PoCs, source tree - 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. - 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. - 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. -- Make every delivered report and PoC portable and self-contained. Use repository-relative source paths, report-relative commands and verified software versions. Never include a local absolute path in report prose, excerpts, citations, links, PoC code, build files, command examples or captured output. +- 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. ## Actors, language and release references @@ -59,7 +59,7 @@ Use Git history and full commit identities as research evidence, not as repeated Before drafting, inventory: - the raw finding, report, disclosure notes and claimed trigger; -- the exact source root, assessed release and privately pinned commit or tag; +- 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; - the introducing change, earliest verified affected release, affected release branches, fixing change and verified fixed or backported releases; - the affected paths, functions, configuration and build options; - Alice, Bob, Mallory or Eve as appropriate, together with each person's actual account, required credentials, privileges and controlled input; @@ -89,12 +89,12 @@ If the source contradicts the finding, stop presenting it as a vulnerability. Ex 1. Create the user-requested report directory, or use `reports/`. Inventory and deduplicate findings by root cause and source path rather than title. 2. Read `references/report-format.md` completely. Require each drafting sub-agent to read it before writing. -3. Pin and inspect each finding's vulnerable source. Independently check the decisive entry point, security check, state change, sink and available fix. Trace the introducing change and inspect the affected and fixed release tags before assigning the finding. +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 the affected and fixed release tags before assigning the finding. When the user explicitly accepted a report-only assessment, record the unavailable source and require every source-dependent conclusion to remain conditional. 4. Record the one-sentence attack and non-claims, verified release history, named actors, complete tested topology, defaults versus configured prerequisites, meaningful positive and negative controls, exact validation basis and testing boundary before assigning the finding. 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. -6. Launch exactly one sub-agent for each distinct vulnerability. Provide only that vulnerability's raw material, pinned source, PoC artefacts, output directory, report-format reference and authorisation boundary. -7. Independently read the returned report against the pinned source, release history and raw artefacts. Check each important claim, excerpt, transition, affected-version statement, impact, fix and reported observation. -8. Reject a draft that smooths over missing evidence, invents a run, inflates impact, guesses affected versions, leaks a local 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. +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. +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. +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. 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. 10. Make only small final corrections after acceptance, and validate the completed report and real PoC artefacts before delivery. @@ -111,7 +111,7 @@ You own exactly one finding. Read references/report-format.md completely before Inputs: - Raw finding and rough report: -- Source root and privately pinned vulnerable revision: +- Source root and privately pinned vulnerable revision: - Assessed release and verified affected versions: - Introducing and fixing changes: - Relevant source paths, functions and claimed trigger:
@@ -122,11 +122,11 @@ Inputs: - Testing authorisation and disposable lab: - Report and PoC output directory: -Treat the supplied finding as a hypothesis. Inspect the exact source revision yourself. 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. +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. 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. -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. +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. 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. @@ -136,9 +136,9 @@ Never call evidence a "witness". Instead, tell the reader what it actually is an 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. -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 a local absolute path into the report, PoC, build recipe, screenshots, logs or output. +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. -Before returning, reread the report against the exact source, release history, PoC and fix. Remove generic filler, unsupported certainty, repeated commit hashes, jargon, inconsistent actor names, repetitive proof labels, token first-person phrases, local absolute paths and claims the artefacts cannot support. +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. ``` For a rewrite, give the replacement worker the original evidence and precise failed checks, not merely the previous prose: From e21a36dd05e40c55e9ed60c8b4756f7248165347 Mon Sep 17 00:00:00 2001 From: Michael D'Angelo Date: Tue, 4 Aug 2026 00:07:54 -0700 Subject: [PATCH 4/4] docs: handle missing source and release history consistently --- .../_bundled_plugin/skills/vulnerability-writeup/SKILL.md | 4 ++-- .../vulnerability-writeup/references/report-format.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md index deb7881b..aaa809a7 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/SKILL.md @@ -89,8 +89,8 @@ If the source contradicts the finding, stop presenting it as a vulnerability. Ex 1. Create the user-requested report directory, or use `reports/`. Inventory and deduplicate findings by root cause and source path rather than title. 2. Read `references/report-format.md` completely. Require each drafting sub-agent to read it before writing. -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 the affected and fixed release tags before assigning the finding. When the user explicitly accepted a report-only assessment, record the unavailable source and require every source-dependent conclusion to remain conditional. -4. Record the one-sentence attack and non-claims, verified release history, named actors, complete tested topology, defaults versus configured prerequisites, meaningful positive and negative controls, exact validation basis and testing boundary before assigning the finding. +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. +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. 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. 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. 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. diff --git a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md index 773850d8..be0c0ef1 100644 --- a/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +++ b/sdk/typescript/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md @@ -44,11 +44,11 @@ If the attack involves similar objects or values, name them concretely and prese ## Vulnerability Details -Follow the reported trigger in causal order. Begin with Mallory's actual controlled input, inspect each material check or state change and show the precise line where the code fails to enforce the expected behaviour. First establish that each ordinary policy or ownership check is configured correctly, then show the shared state, receiving component or dependency decision and real downstream operation that bypasses it. Carry the same request, object, field or state through that whole path. When a named attacker does not fit the actual mechanism, describe the real actor without forcing the example. +Follow the reported trigger in causal order. Begin with Mallory's actual controlled input. When source is available, inspect each material check or state change and show the precise line where the code fails to enforce the expected behaviour. When the user explicitly accepted a report-only assessment without source, describe the supplied trigger sequence as conditional, identify its actual evidence and unavailable checks, and never invent a source excerpt, line or observed state. First establish any verified ordinary policy or ownership check, then describe the evidenced shared state, receiving component or dependency decision and downstream operation without upgrading an unverified claim. Carry the same request, object, field or state through that whole path. When a named attacker does not fit the actual mechanism, describe the real actor without forcing the example. -Identify the repository-relative source path, function and assessed software version for each excerpt. For a runtime-tested vendor or distribution package, verify excerpts and line numbers against that exact patched source; do not quote a nearby upstream tag as if it ran. Cite relevant dependency code in causal order and explain concrete log or trace fields in plain English. Quote only the lines necessary to establish the decisive behaviour, then explain what they prove and what remains unverified. Refer to each demonstration by what it actually is, such as `Mallory's request`, `the returned document`, `the failing test` or `the execution trace`, rather than using an unexplained evidence label. Address relevant validation, locking, cancellation, cleanup, permissions, timing and alternative explanations rather than assuming they cannot prevent the path. +For each available, verified source excerpt, identify its repository-relative source path, function and assessed software version. For a runtime-tested vendor or distribution package, verify excerpts and line numbers against that exact patched source; do not quote a nearby upstream tag as if it ran. Cite available dependency code in causal order and explain concrete log or trace fields in plain English. Quote only the lines necessary to establish the decisive behaviour, then explain what they prove and what remains unverified; omit source excerpts entirely when an explicitly accepted report-only assessment has no source. Refer to each demonstration by what it actually is, such as `Mallory's request`, `the returned document`, `the failing test` or `the execution trace`, rather than using an unexplained evidence label. Address relevant validation, locking, cancellation, cleanup, permissions, timing and alternative explanations rather than assuming they cannot prevent the path. -Explain how the vulnerable behaviour entered the project and which released versions contain it. Use a commit reference only where the introduction or fix is materially relevant to that explanation. +When release history is available, explain how the vulnerable behaviour entered the project and which released versions contain it; otherwise identify the unavailable history and do not guess affected releases. Use a commit reference only where the introduction or fix is materially relevant to that explanation. If the exact source contradicts the claimed sequence, explicitly say so. Do not silently replace the finding with a nearby weaker bug or a more convenient test event.