Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

docs(imports): distinguish Snyk evidence changes from finding edits (#2081)

Michael D'Angelo6114d53d232d
diff --git a/docs/scanner-imports/snyk.md b/docs/scanner-imports/snyk.md
index eb33024bd..3c05f9151 100644
--- a/docs/scanner-imports/snyk.md
+++ b/docs/scanner-imports/snyk.md
@@ -61,10 +61,27 @@ alternate dependency paths. The plugin cannot recover data its MCP server did
not return. See the [official SCA mapper](https://github.com/snyk/studio-mcp/blob/main/internal/oss/map.go).
The bundle's composite occurrence identity includes package version and dependency
path. Keep the same source key for each repository, branch and scan target across
-exports; a changed occurrence has a new ID. Plugin v1 paths are relative to the
-scan target and do not carry its Git-root offset. They remain in original evidence
+exports. A change to the composite identity produces a new source ID; changing
+only the evidence preserves that ID. Plugin v1 paths are relative to the scan
+target and do not carry its Git-root offset. They remain in original evidence
without being projected as repository locations or package manifest paths.
+### How to read import counts
+
+For the same repository and source key, `created` means a new source identity.
+For an existing identity, `updated` means the whole evidence snapshot changed;
+`unchanged` means it did not. These counts describe imported Snyk evidence, not
+new vulnerabilities, fixes, or Codex assessments.
+
+Each plugin finding retains its collection context. If a scan's `issueCount`
+falls from three to two, both remaining findings can get a new version even if
+neither occurrence changed. Their source IDs stay the same, and omitting the
+third finding does not close it. Native CLI JSON likewise retains the project's
+[`uniqueCount`](https://github.com/snyk/cli/blob/8b2d0a695c6b1b31f681e32039db958fba6f0c2f/src/lib/snyk-test/run-test.ts#L555)
+when supplied. It counts distinct vulnerabilities, not dependency-path
+occurrences: two paths to the same advisory contribute one to the count.
+Keep the original evidence; do not edit or strip scan metadata to suppress updates.
+
### Native CLI JSON
For automation, use the [Snyk CLI](https://docs.snyk.io/developer-tools/snyk-cli/commands/test)
diff --git a/sdk/typescript/tests-ts/snyk-collection-evidence.test.ts b/sdk/typescript/tests-ts/snyk-collection-evidence.test.ts
new file mode 100644
index 000000000..1f93167f0
--- /dev/null
+++ b/sdk/typescript/tests-ts/snyk-collection-evidence.test.ts
@@ -0,0 +1,128 @@
+import { expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+ listLocalExternalFindings,
+ normalizeSnykJson,
+ prepareLocalExternalImport,
+} from "../src/index.js";
+import { localFindingsFixture } from "./external-findings-local-helpers.js";
+import { snykJson, snykPluginExport } from "./support/snyk-import-fixtures.js";
+
+test("plugin imports version collection evidence without changing occurrence identities", async () => {
+ const bundle = snykPluginExport();
+ const first = bundle.findings[0]!;
+ for (const advisory of ["SNYK-EXAMPLE-2", "SNYK-EXAMPLE-3"]) {
+ const other = structuredClone(first);
+ other.id.value = other.id.value.replace(other.rule.id, advisory);
+ other.rule.id = advisory;
+ other.nativeRecord.id = advisory;
+ bundle.findings.push(other);
+ }
+ const scan = bundle.collection.scans[0]!;
+ scan.issueCount = 3;
+ const fixture = await localFindingsFixture({
+ remote: bundle.collection.target.repository,
+ });
+ try {
+ const path = join(fixture.root, "snyk.json");
+ const options = {
+ repository: fixture.repository,
+ provider: "snyk" as const,
+ sourceKey: "example/plugin-sca",
+ };
+ const dependencies = { environment: fixture.environment };
+ const importBundle = async () => {
+ await writeFile(path, JSON.stringify(bundle));
+ const prepared = await prepareLocalExternalImport(
+ path,
+ options,
+ dependencies,
+ );
+ const result = await prepared.import();
+ const { findings, ...context } = bundle;
+ expect(result.excluded).toEqual([]);
+ expect(result.findings.map((row) => row.evidence.source_data)).toEqual(
+ findings.map((finding) => ({ ...context, finding })),
+ );
+ return result;
+ };
+
+ const created = await importBundle();
+ expect(created.counts).toEqual({ created: 3, updated: 0, unchanged: 0 });
+
+ bundle.findings.pop();
+ first.nativeRecord.unknownField = "Revised vendor detail";
+ expect((await importBundle()).counts).toEqual({
+ created: 0,
+ updated: 1,
+ unchanged: 1,
+ });
+
+ scan.issueCount = 2;
+ expect((await importBundle()).counts).toEqual({
+ created: 0,
+ updated: 2,
+ unchanged: 0,
+ });
+
+ const stored = await listLocalExternalFindings(options, dependencies);
+ expect(
+ Object.fromEntries(
+ stored.map((row) => [row.sourceFindingId, row.version]),
+ ),
+ ).toEqual({
+ [created.findings[0]!.sourceFindingId]: 3,
+ [created.findings[1]!.sourceFindingId]: 2,
+ [created.findings[2]!.sourceFindingId]: 1,
+ });
+ } finally {
+ await fixture.dispose();
+ }
+});
+
+test("native JSON retains one advisory count across distinct dependency paths", () => {
+ const { packageManager, targetFile, vulnerabilities } = snykJson();
+ const retained = vulnerabilities[0]!;
+ const retainedPaths = [
+ retained,
+ {
+ ...retained,
+ },
+ ];
+ const project = { ok: false, packageManager, targetFile };
+ const before = normalizeSnykJson({
+ ...project,
+ vulnerabilities: [...retainedPaths, { ...retained, id: "SNYK-EXAMPLE-2" }],
+ uniqueCount: 2,
+ });
+ const after = normalizeSnykJson({
+ ...project,
+ vulnerabilities: retainedPaths,
+ uniqueCount: 1,
+ });
+ expect(before.findings).toHaveLength(3);
+ const retainedIds = after.findings.map(
+ (finding) => finding.source_finding_id,
+ );
+ expect(new Set(retainedIds).size).toBe(2);
+ expect(retainedIds).toEqual(
+ before.findings.slice(0, 2).map((finding) => finding.source_finding_id),
+ );
+ for (const [selection, uniqueCount] of [
+ [before, 2],
+ [after, 1],
+ ] as const) {
+ expect(
+ selection.findings
+ .slice(0, 2)
+ .map((finding) => finding.evidence.source_data),
+ ).toEqual(
+ retainedPaths.map((vulnerability) => ({
+ project: { ...project, uniqueCount },
+ vulnerability,
+ })),
+ );
+ }
+});