feat(osv): grade dependency reachability and promote reachable CVEs (main)

docs/dependency-cves.md

@@ -47,7 +47,8 @@ The step calls external binaries and degrades cleanly when they are absent (it l
 
 - `data/<id>/setup/osv-findings.json` records the vulnerable packages and their advisory IDs. This file and the resolver's evidence files live under the gitignored `setup/` directory.
 - The threat model (`INFO.md`) gains a **Known-vulnerable dependencies** section. Rows resolved from a version range are labeled as such, since that version may not be the one installed.
-- Matcher generation receives the threat model, so an advisory whose vulnerable call is reachable in the code gets a matcher and becomes a scan candidate. The investigation phase then judges reachability and writes the finding.
+- That section requires a **Dependency reachability** verdict with one graded line per dependency (`HIGH`/`MEDIUM`/`LOW`, the vulnerable call site as `file:line` or "not called", and the consequence if reached). Fixing this structure keeps a reachable advisory from being summarized away as prose, so the same dependency is graded the same way across runs.
+- Matcher generation receives the threat model, so an advisory graded reachable gets a matcher aimed at its call site and becomes a scan candidate. The investigation phase then confirms reachability and writes the finding.
 
 ## Security notes
 

packages/deepsec/src/__tests__/osv-enrich.test.ts

@@ -233,6 +233,21 @@ describe("buildContext resolved-version labeling", () => {
     expect(ctx).not.toMatch(/`log4j-core@2\.14\.1` \(resolved/);
   });
 
+  it("emits the required graded reachability block naming every dependency", () => {
+    const ctx = buildContext([
+      { name: "starlette", version: "0.46.0", vulns: [{ id: "X" }], resolved: true },
+      { name: "anyio", version: "3.6.2", vulns: [{ id: "Y" }], resolved: true },
+      { name: "idna", version: "2.8.0", vulns: [{ id: "Z" }], resolved: true },
+    ]);
+    // the structured directive is present and demands a per-dep graded verdict
+    expect(ctx).toContain("### Dependency reachability (required)");
+    expect(ctx).toMatch(/HIGH\|MEDIUM\|LOW/);
+    // every dependency is named in the directive so none can be silently dropped
+    expect(ctx).toContain("`starlette`");
+    expect(ctx).toContain("`anyio`");
+    expect(ctx).toContain("`idna`");
+  });
+
   it("flags a package as resolved via resolvedPaths", () => {
     const raw = JSON.stringify({
       results: [

packages/deepsec/src/setup/osv-enrich.ts

@@ -442,11 +442,27 @@ export function buildContext(hits: OsvPackageHit[]): string {
     const vulnLines = h.vulns.map((v) => `  - ${v.id}${v.summary ? `: ${v.summary}` : ""}`);
     return [`- \`${h.name}@${h.version}\`${marker}`, ...vulnLines].join("\n");
   });
+  // Every dependency below must appear in the required verdict block, so the
+  // review always produces a graded, line-anchored reachability judgment per
+  // dependency. Leaving this to free prose is what makes a reachable advisory
+  // (e.g. an unbounded form parse) silently vanish on a noisier run: one run
+  // writes "HIGH reachability, routing.py:443 → multipart DoS" and the finding
+  // lands; another writes "starlette is a heavily-used dependency" and it is
+  // dropped. Pinning the structure removes that variance from the promote step.
+  const names = hits.map((h) => `\`${h.name}\``).join(", ");
   return [
     OSV_CONTEXT_HEADING,
     "",
-    'These dependencies have published advisories (id followed by what the advisory is about). Rows marked "resolved range version" come from resolving a version range and may not be the installed version — treat them as applicable-if-resolved, not confirmed-present. In the Threat model and Project-specific patterns to flag sections, note where this codebase actually imports or calls each one, so the review can judge whether the advisory is reachable here rather than merely present.',
+    'These dependencies have published advisories (id followed by what the advisory is about). Rows marked "resolved range version" come from resolving a version range and may not be the installed version — treat them as applicable-if-resolved, not confirmed-present.',
     "",
     ...blocks,
+    "",
+    "### Dependency reachability (required)",
+    "",
+    `In the Threat model section, emit a \`Dependency reachability\` subsection with exactly one line for EVERY dependency above (${names}) — do not omit any, do not merge them into prose. Use this fixed format per line:`,
+    "",
+    '`- <name>@<version> — <HIGH|MEDIUM|LOW> reachability — <file:line of the vulnerable call site, or "not imported/called by this codebase"> — <the advisory consequence if reached>`',
+    "",
+    "Grade reachability by whether this codebase actually reaches the vulnerable code path: HIGH when it imports and calls the affected API on an attacker-reachable path (name the `file:line`), LOW when the package is only transitive or the affected API is never called here. A dependency graded HIGH with a reachable call site is a finding to promote (steer a matcher at that `file:line`), not merely context; LOW ones stay recorded here. Keep this verdict for every dependency even across refreshes.",
   ].join("\n");
 }

packages/processor/src/prompt/core.ts

@@ -69,6 +69,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (\`file:line\`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (\`file:line\`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/01-empty-project.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/02-nextjs-tsx-batch.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/03-django-py-batch.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/04-polyglot-python-batch-filters-other-techs.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/05-polyglot-typescript-batch-filters-other-techs.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/06-polyglot-mixed-batch.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/07-overflow-fallback.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/08-with-info-and-append.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth:

prompt-samples/09-laravel-php-batch.md

@@ -71,6 +71,14 @@ Before classifying an issue, check for mitigations:
 
 If fully mitigated, do NOT flag it. Report only genuine, exploitable vulnerabilities.
 
+## Known-vulnerable dependencies
+
+When project context (INFO.md) includes a **Dependency reachability** section, treat its graded verdicts as promotion guidance for dependency-advisory candidates:
+
+- **HIGH reachability** with a named call site (`file:line`): the vulnerable dependency code is reached from this codebase. Promote it to a finding at that site — do NOT dismiss it as "just a library default" or "the application's responsibility." The advisory's own severity carries into the finding. A HIGH verdict means reachability is already established upstream; your job is to confirm the call site and write it up, not to re-litigate whether a reachable advisory is worth reporting.
+- **MEDIUM reachability**: judge it on its merits like any other candidate.
+- **LOW reachability**: the affected API is not called, or the package is only transitive. Keep it as context; do NOT raise a standalone finding on the basis of a LOW grade. The one exception: if you find a concrete reachable call site (`file:line`) that the grading missed, treat it as reachable and promote — a LOW grade is a starting assumption, not a reason to ignore evidence.
+
 ## Auth Bypass Patterns to Look For
 
 Beyond missing auth, look for **subtle bypasses** in code that appears to have auth: