@opensip-cli/tool-osv-scanner 0.1.15

package/dist/parse-osv-json.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview OSV-Scanner JSON → normalized `Signal[]` (ADR-0090 §4, brief §4).
+ *
+ * OSV-Scanner emits a nested document: `results[]` (one per scanned source, e.g. a
+ * lockfile) → `packages[]` (one per resolved dependency) → `vulnerabilities[]`
+ * (one per advisory) plus a sibling `groups[]` (advisories collapsed by alias,
+ * carrying `max_severity` — a CVSS base-score string). One normalized
+ * `security` {@link Signal} is emitted per vulnerability.
+ *
+ * Severity resolution (richest first):
+ *   1. `groups[].max_severity` — a CVSS base score string ("7.5") → {@link
+ *      cvssToSeverity} (FIRST/NVD v3 bands).
+ *   2. `database_specific.severity` — the GHSA LABEL (`CRITICAL|HIGH|MODERATE|LOW`;
+ *      **MODERATE ⇒ medium**, the only non-obvious mapping).
+ *   3. neither present ⇒ default `medium` (a known vulnerability with an unknown
+ *      score is still worth surfacing; documented).
+ * The raw label is preserved on `metadata.nativeSeverity`; the raw CVSS string on
+ * `metadata.cvss`.
+ *
+ * OSV carries no per-line anchor (the finding is the lockfile-pinned dependency),
+ * so `code.line`/`code.column` are omitted — only `code.file` (the source path) is
+ * set. No credentials are present, so there is nothing to redact.
+ *
+ * Pure: defensive JSON navigation (never throws on malformed input → `[]`).
+ */
+import type { Signal } from '@opensip-cli/core';
+import type { AdapterRunContext, ParsedScannerOutput } from '@opensip-cli/external-tool-adapter';
+/**
+ * Parse OSV-Scanner JSON output into normalized signals. An empty/clean run
+ * (`{"results":[]}`, or "nothing scanned") yields no findings; each vulnerability
+ * maps to a `security` signal whose severity comes from the CVSS `max_severity`
+ * (preferred) or the GHSA label (`MODERATE ⇒ medium`), defaulting to `medium`.
+ */
+export declare function parseOsvJson(raw: ParsedScannerOutput, _ctx: AdapterRunContext): readonly Signal[];
+//# sourceMappingURL=parse-osv-json.d.ts.map

package/dist/parse-osv-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-osv-json.d.ts","sourceRoot":"","sources":["../src/parse-osv-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAaH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AA+IjG;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAYjG"}

package/dist/parse-osv-json.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview OSV-Scanner JSON → normalized `Signal[]` (ADR-0090 §4, brief §4).
+ *
+ * OSV-Scanner emits a nested document: `results[]` (one per scanned source, e.g. a
+ * lockfile) → `packages[]` (one per resolved dependency) → `vulnerabilities[]`
+ * (one per advisory) plus a sibling `groups[]` (advisories collapsed by alias,
+ * carrying `max_severity` — a CVSS base-score string). One normalized
+ * `security` {@link Signal} is emitted per vulnerability.
+ *
+ * Severity resolution (richest first):
+ *   1. `groups[].max_severity` — a CVSS base score string ("7.5") → {@link
+ *      cvssToSeverity} (FIRST/NVD v3 bands).
+ *   2. `database_specific.severity` — the GHSA LABEL (`CRITICAL|HIGH|MODERATE|LOW`;
+ *      **MODERATE ⇒ medium**, the only non-obvious mapping).
+ *   3. neither present ⇒ default `medium` (a known vulnerability with an unknown
+ *      score is still worth surfacing; documented).
+ * The raw label is preserved on `metadata.nativeSeverity`; the raw CVSS string on
+ * `metadata.cvss`.
+ *
+ * OSV carries no per-line anchor (the finding is the lockfile-pinned dependency),
+ * so `code.line`/`code.column` are omitted — only `code.file` (the source path) is
+ * set. No credentials are present, so there is nothing to redact.
+ *
+ * Pure: defensive JSON navigation (never throws on malformed input → `[]`).
+ */
+import { createSignal } from '@opensip-cli/core';
+import { asArray, asObject, cvssToSeverity, getString, parseCvss, safeParseJson, withNativeSeverity, } from '@opensip-cli/external-tool-adapter';
+/** Read the parsed OSV document from the descriptor payload, defensively. */
+function osvDocument(raw) {
+    // The run loop pre-parses JSON for `kind: 'json'`; fall back to the raw bytes
+    // (the acceptance-harness path) so the parser is total either way.
+    if (raw.json !== undefined)
+        return asObject(raw.json);
+    const parsed = safeParseJson(raw.raw);
+    return parsed.ok ? asObject(parsed.value) : undefined;
+}
+/**
+ * Map a GHSA `database_specific.severity` LABEL to a four-bucket severity.
+ * `MODERATE` (GHSA's term) and `MEDIUM` both collapse to `medium`; an unknown
+ * label yields `undefined` so the caller can fall through to the default.
+ */
+function labelToSeverity(label) {
+    switch (label?.toUpperCase()) {
+        case 'CRITICAL': {
+            return 'critical';
+        }
+        case 'HIGH': {
+            return 'high';
+        }
+        case 'MODERATE':
+        case 'MEDIUM': {
+            return 'medium';
+        }
+        case 'LOW': {
+            return 'low';
+        }
+        default: {
+            return undefined;
+        }
+    }
+}
+/**
+ * The `max_severity` CVSS string for a vulnerability: the `groups[]` entry whose
+ * `ids` include this vuln id carries it (OSV collapses aliased advisories into one
+ * group). Empty/absent ⇒ `undefined`.
+ */
+function maxSeverityForVuln(groups, vulnId) {
+    for (const group of groups) {
+        const ids = asArray(asObject(group)?.ids) ?? [];
+        if (ids.includes(vulnId)) {
+            const score = getString(group, 'max_severity');
+            if (score !== undefined && score.length > 0)
+                return score;
+        }
+    }
+    return undefined;
+}
+/** Compose the human message: `<summary> (<pkg>@<version>)`, with defensive fallbacks. */
+function buildMessage(summary, ruleId, pkg, installed) {
+    const base = summary ?? ruleId;
+    if (pkg === undefined)
+        return base;
+    const ref = installed === undefined ? pkg : `${pkg}@${installed}`;
+    return `${base} (${ref})`;
+}
+/**
+ * Normalize one OSV vulnerability (within a package + source) to a {@link Signal}.
+ * Returns `undefined` for a non-object entry so a malformed element is skipped
+ * rather than throwing.
+ */
+function normalizeVulnerability(entry, groups, context) {
+    const vuln = asObject(entry);
+    if (vuln === undefined)
+        return undefined;
+    const ruleId = getString(vuln, 'id') ?? 'osv-vulnerability';
+    const summary = getString(vuln, 'summary');
+    const details = getString(vuln, 'details');
+    const aliases = (asArray(vuln.aliases) ?? []).filter((a) => typeof a === 'string');
+    const label = getString(asObject(vuln.database_specific), 'severity');
+    // Severity: CVSS max_severity (numeric) first, then the GHSA label, then default.
+    const cvss = maxSeverityForVuln(groups, ruleId);
+    const cvssScore = parseCvss(cvss);
+    const severity = cvssScore === undefined ? (labelToSeverity(label) ?? 'medium') : cvssToSeverity(cvssScore);
+    const metadata = withNativeSeverity({
+        aliases,
+        ecosystem: context.ecosystem ?? null,
+        pkg: context.pkg ?? null,
+        installed: context.installed ?? null,
+        cvss: cvss ?? null,
+    }, 
+    // Preserve the scanner's own severity label (null when it emits none).
+    label ?? null);
+    return createSignal({
+        source: 'osv-scanner',
+        category: 'security',
+        severity,
+        ruleId,
+        message: buildMessage(summary, ruleId, context.pkg, context.installed),
+        ...(details === undefined ? {} : { suggestion: details }),
+        // OSV anchors a finding at the lockfile (no line) — set only `code.file`.
+        code: { file: context.sourcePath },
+        metadata,
+    });
+}
+/** Normalize every vulnerability inside one `packages[]` entry. */
+function normalizePackage(entry, sourcePath) {
+    const packageEntry = asObject(entry);
+    if (packageEntry === undefined)
+        return [];
+    const pkgInfo = asObject(packageEntry.package);
+    const context = {
+        sourcePath,
+        pkg: getString(pkgInfo, 'name'),
+        installed: getString(pkgInfo, 'version'),
+        ecosystem: getString(pkgInfo, 'ecosystem'),
+    };
+    const groups = asArray(packageEntry.groups) ?? [];
+    const signals = [];
+    for (const vuln of asArray(packageEntry.vulnerabilities) ?? []) {
+        const signal = normalizeVulnerability(vuln, groups, context);
+        if (signal !== undefined)
+            signals.push(signal);
+    }
+    return signals;
+}
+/**
+ * Parse OSV-Scanner JSON output into normalized signals. An empty/clean run
+ * (`{"results":[]}`, or "nothing scanned") yields no findings; each vulnerability
+ * maps to a `security` signal whose severity comes from the CVSS `max_severity`
+ * (preferred) or the GHSA label (`MODERATE ⇒ medium`), defaulting to `medium`.
+ */
+export function parseOsvJson(raw, _ctx) {
+    const doc = osvDocument(raw);
+    const results = asArray(doc?.results) ?? [];
+    const signals = [];
+    for (const result of results) {
+        const sourcePath = getString(asObject(result)?.source, 'path') ?? '';
+        for (const packageEntry of asArray(asObject(result)?.packages) ?? []) {
+            signals.push(...normalizePackage(packageEntry, sourcePath));
+        }
+    }
+    return signals;
+}
+//# sourceMappingURL=parse-osv-json.js.map

package/dist/parse-osv-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-osv-json.js","sourceRoot":"","sources":["../src/parse-osv-json.ts"],"names":[],"mappings":"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"}

package/dist/tool.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `@opensip-cli/tool-osv-scanner` Tool descriptor (ADR-0090 / ADR-0091 / ADR-0092).
+ *
+ * The second External Tool Adapter: it wraps the user-installed `osv-scanner`
+ * dependency-vulnerability scanner as an ordinary opensip-cli `Tool` via {@link
+ * defineExternalToolAdapter}. The substrate owns binary resolution, the run loop
+ * (resolve → execFile → ingest → normalize → persist via the host artifact seam),
+ * provenance, and the auto-added `doctor`/`version` commands; this module declares
+ * only the osv-scanner identity, the wrapped binary, and the `scan` command (args
+ * + JSON parser).
+ *
+ * Like gitleaks, this is a JSON adapter (it routes OSV-Scanner's `--format json`,
+ * which is richer than its SARIF output, through a per-adapter `parse`, NOT the
+ * shared `ingestSarif`).
+ *
+ * Layer 4: imports the substrate + `@opensip-cli/core` ONLY — never the CLI,
+ * output, or any other adapter (dependency-cruiser enforced).
+ *
+ * This is an OPT-IN, installed tool (NOT in `bundled-tools.manifest.json`): the
+ * host never imports this runtime; an `opensip osv-scanner` / `opensip osv`
+ * invocation forks a worker that re-discovers + imports it and runs the handler.
+ * Installed tools are deny-by-default — a run needs
+ * `OPENSIP_CLI_ALLOW_INSTALLED_TOOLS` to include the osv-scanner id.
+ */
+import type { Tool, ToolIdentity } from '@opensip-cli/core';
+import type { AdapterRunContext } from '@opensip-cli/external-tool-adapter';
+/** Human/aliased identity (`opensip osv-scanner` / `opensip osv`). */
+export declare const OSV_SCANNER_IDENTITY: ToolIdentity;
+/** Stable UUID identity (ADR-0048); mirrors `opensipTools.stableId` in package.json. */
+export declare const OSV_SCANNER_STABLE_ID = "d25a4471-3289-4660-b5ab-63830072d0e1";
+/**
+ * Normalize the `osv-scanner --version` stdout to a bare semver. OSV-Scanner
+ * prints a multi-line banner whose first line is e.g. `osv-scanner version: 1.9.1`
+ * (or, on some builds, just `1.9.1`); take the first semver-shaped token and strip
+ * a leading `v`.
+ *
+ * VERIFY-against-installed-binary: exact `osv-scanner --version` output format.
+ */
+export declare function parseOsvVersion(stdout: string): string;
+/**
+ * Build the osv-scanner scan argv (no shell — args are passed to `execFile`).
+ * Scans the project recursively (`-r <root>`) and writes a JSON report to the
+ * host-owned artifact path the substrate composes for this run. OSV-Scanner ships
+ * an embedded/offline advisory DB, so the scan is local-only (no network, no auth).
+ *
+ * VERIFY-against-installed-binary: this is the stable v1.x flat invocation
+ * (`osv-scanner --format json --output <path> -r <root>`). OSV-Scanner v2.x
+ * reorganized the surface to `osv-scanner scan source -r <root>`; if v2 becomes the
+ * floor, switch on the doctor-detected version. (The flags `--format`, `--output`,
+ * `-r` are stable across both.)
+ */
+export declare function buildScanArgs(ctx: AdapterRunContext): readonly string[];
+/**
+ * The osv-scanner external-tool adapter `Tool`. The host loads it by name through
+ * the installed-tool worker-dispatch path (the barrel re-exports it as `tool`).
+ */
+export declare const tool: Tool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,YAGlC,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,yCAAyC,CAAC;AAE5E;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAEvE;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,EAAE,IAgDjB,CAAC"}

package/dist/tool.js

@@ -0,0 +1,116 @@
+/**
+ * `@opensip-cli/tool-osv-scanner` Tool descriptor (ADR-0090 / ADR-0091 / ADR-0092).
+ *
+ * The second External Tool Adapter: it wraps the user-installed `osv-scanner`
+ * dependency-vulnerability scanner as an ordinary opensip-cli `Tool` via {@link
+ * defineExternalToolAdapter}. The substrate owns binary resolution, the run loop
+ * (resolve → execFile → ingest → normalize → persist via the host artifact seam),
+ * provenance, and the auto-added `doctor`/`version` commands; this module declares
+ * only the osv-scanner identity, the wrapped binary, and the `scan` command (args
+ * + JSON parser).
+ *
+ * Like gitleaks, this is a JSON adapter (it routes OSV-Scanner's `--format json`,
+ * which is richer than its SARIF output, through a per-adapter `parse`, NOT the
+ * shared `ingestSarif`).
+ *
+ * Layer 4: imports the substrate + `@opensip-cli/core` ONLY — never the CLI,
+ * output, or any other adapter (dependency-cruiser enforced).
+ *
+ * This is an OPT-IN, installed tool (NOT in `bundled-tools.manifest.json`): the
+ * host never imports this runtime; an `opensip osv-scanner` / `opensip osv`
+ * invocation forks a worker that re-discovers + imports it and runs the handler.
+ * Installed tools are deny-by-default — a run needs
+ * `OPENSIP_CLI_ALLOW_INSTALLED_TOOLS` to include the osv-scanner id.
+ */
+import { readPackageVersion } from '@opensip-cli/core';
+import { defineExternalToolAdapter } from '@opensip-cli/external-tool-adapter';
+import { parseOsvJson } from './parse-osv-json.js';
+/** Human/aliased identity (`opensip osv-scanner` / `opensip osv`). */
+export const OSV_SCANNER_IDENTITY = {
+    name: 'osv-scanner',
+    aliases: ['osv'],
+};
+/** Stable UUID identity (ADR-0048); mirrors `opensipTools.stableId` in package.json. */
+export const OSV_SCANNER_STABLE_ID = 'd25a4471-3289-4660-b5ab-63830072d0e1';
+/**
+ * Normalize the `osv-scanner --version` stdout to a bare semver. OSV-Scanner
+ * prints a multi-line banner whose first line is e.g. `osv-scanner version: 1.9.1`
+ * (or, on some builds, just `1.9.1`); take the first semver-shaped token and strip
+ * a leading `v`.
+ *
+ * VERIFY-against-installed-binary: exact `osv-scanner --version` output format.
+ */
+export function parseOsvVersion(stdout) {
+    // Fully bounded ({1,5} digit runs, {1,2} dotted segments) so the matcher is
+    // linear — major.minor[.patch], optional leading `v`.
+    const match = /v?(\d{1,5}(?:\.\d{1,5}){1,2})/.exec(stdout);
+    return match?.[1] ?? stdout.trim();
+}
+/**
+ * Build the osv-scanner scan argv (no shell — args are passed to `execFile`).
+ * Scans the project recursively (`-r <root>`) and writes a JSON report to the
+ * host-owned artifact path the substrate composes for this run. OSV-Scanner ships
+ * an embedded/offline advisory DB, so the scan is local-only (no network, no auth).
+ *
+ * VERIFY-against-installed-binary: this is the stable v1.x flat invocation
+ * (`osv-scanner --format json --output <path> -r <root>`). OSV-Scanner v2.x
+ * reorganized the surface to `osv-scanner scan source -r <root>`; if v2 becomes the
+ * floor, switch on the doctor-detected version. (The flags `--format`, `--output`,
+ * `-r` are stable across both.)
+ */
+export function buildScanArgs(ctx) {
+    return ['--format', 'json', '--output', ctx.artifactPath('osv.json'), '-r', ctx.projectRoot];
+}
+/**
+ * The osv-scanner external-tool adapter `Tool`. The host loads it by name through
+ * the installed-tool worker-dispatch path (the barrel re-exports it as `tool`).
+ */
+export const tool = defineExternalToolAdapter({
+    identity: OSV_SCANNER_IDENTITY,
+    metadata: {
+        id: OSV_SCANNER_STABLE_ID,
+        version: readPackageVersion(import.meta.url),
+        description: 'Dependency vulnerability scanning via OSV-Scanner',
+        adapterPackage: '@opensip-cli/tool-osv-scanner',
+    },
+    binary: {
+        command: 'osv-scanner',
+        versionArgs: ['--version'],
+        versionParse: parseOsvVersion,
+        // The flat `--format json --output -r` invocation is stable from v1.4.
+        // VERIFY-against-installed-binary (v2.x moved verbs under `scan source`).
+        minVersion: '1.4.0',
+        // Operator pin (config `binaries.osv-scanner.path` / `OPENSIP_OSV_SCANNER_BIN`)
+        // beats PATH; resolution never fetches a binary.
+        resolution: ['config', 'path'],
+        installHint: 'Install osv-scanner: https://google.github.io/osv-scanner/installation/ (brew install osv-scanner)',
+    },
+    // OSV-Scanner queries its embedded/offline advisory DB via execFile — no
+    // network, no credentials.
+    network: 'local-only',
+    commands: [
+        {
+            name: 'scan',
+            description: 'Scan project dependencies for known vulnerabilities (OSV-Scanner)',
+            args: buildScanArgs,
+            output: { kind: 'json', path: 'osv.json' },
+            // ADR-0091 Phase-0 decision 4 (OSV): `0` clean, `1` findings, `>=2` fault.
+            // The exception is `128` ("no packages/lockfiles found") — a genuinely CLEAN
+            // no-op (a project with no dependency manifests), NOT a fault, so it joins the
+            // `ok` set. With `errorFrom: 2`, `127` (general/usage error) still faults.
+            // VERIFY-against-installed-binary: the exact nothing-scanned code (recollection
+            // 128) across versions.
+            exitCodes: { ok: [0, 128], findings: [1], errorFrom: 2 },
+            parse: parseOsvJson,
+            // A3 (no `excludeScan`): OSV-Scanner only parses recognized lockfiles/SBOMs,
+            // never an arbitrary JSON report, so it does NOT re-detect opensip's own
+            // persisted reports under `.runtime/` — there is no fingerprint churn to guard
+            // against, and OSV-Scanner v1.x exposes no path-exclude flag (only `--no-ignore`
+            // for .gitignore and vuln-id ignores). It is therefore left without an exclusion.
+        },
+    ],
+    // Scanner output is line-volatile → the line-shift-tolerant message hash, not the
+    // host `ruleId|file|line|col` default. Stamped worker-side in the run loop.
+    fingerprintStrategy: 'message-hash',
+});
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAE/E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD,sEAAsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,CAAC,KAAK,CAAC;CACjB,CAAC;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,qBAAqB,GAAG,sCAAsC,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,4EAA4E;IAC5E,sDAAsD;IACtD,MAAM,KAAK,GAAG,+BAA+B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3D,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,GAAsB;IAClD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;AAC/F,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAS,yBAAyB,CAAC;IAClD,QAAQ,EAAE,oBAAoB;IAC9B,QAAQ,EAAE;QACR,EAAE,EAAE,qBAAqB;QACzB,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAC5C,WAAW,EAAE,mDAAmD;QAChE,cAAc,EAAE,+BAA+B;KAChD;IACD,MAAM,EAAE;QACN,OAAO,EAAE,aAAa;QACtB,WAAW,EAAE,CAAC,WAAW,CAAC;QAC1B,YAAY,EAAE,eAAe;QAC7B,uEAAuE;QACvE,0EAA0E;QAC1E,UAAU,EAAE,OAAO;QACnB,gFAAgF;QAChF,iDAAiD;QACjD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC9B,WAAW,EACT,oGAAoG;KACvG;IACD,yEAAyE;IACzE,2BAA2B;IAC3B,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,MAAM;YACZ,WAAW,EAAE,mEAAmE;YAChF,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE;YAC1C,2EAA2E;YAC3E,6EAA6E;YAC7E,+EAA+E;YAC/E,2EAA2E;YAC3E,gFAAgF;YAChF,wBAAwB;YACxB,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;YACxD,KAAK,EAAE,YAAY;YACnB,6EAA6E;YAC7E,yEAAyE;YACzE,+EAA+E;YAC/E,iFAAiF;YACjF,kFAAkF;SACnF;KACF;IACD,kFAAkF;IAClF,4EAA4E;IAC5E,mBAAmB,EAAE,cAAc;CACpC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,138 @@
+{
+  "name": "@opensip-cli/tool-osv-scanner",
+  "version": "0.1.15",
+  "license": "Apache-2.0",
+  "description": "External Tool Adapter for OSV-Scanner — wraps the osv-scanner dependency vulnerability scanner as an opensip-cli tool (opensip osv-scanner / opensip osv)",
+  "keywords": [
+    "opensip-cli",
+    "static-analysis",
+    "code-quality"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opensip-ai/opensip-cli.git",
+    "directory": "packages/tool-osv-scanner"
+  },
+  "homepage": "https://github.com/opensip-ai/opensip-cli",
+  "bugs": {
+    "url": "https://github.com/opensip-ai/opensip-cli/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "opensipTools": {
+    "kind": "tool",
+    "id": "osv-scanner",
+    "identity": {
+      "name": "osv-scanner",
+      "aliases": [
+        "osv"
+      ]
+    },
+    "stableId": "d25a4471-3289-4660-b5ab-63830072d0e1",
+    "apiVersion": 1,
+    "requires": [
+      {
+        "resource": "subprocess",
+        "reason": "Executes the user-installed osv-scanner binary via execFile (no shell)"
+      },
+      {
+        "resource": "filesystem",
+        "reason": "Reads the project working tree and writes the raw scan artifact under .runtime/artifacts"
+      }
+    ],
+    "commands": [
+      {
+        "name": "osv-scanner",
+        "description": "Scan project dependencies for known vulnerabilities (OSV-Scanner)",
+        "aliases": [
+          "osv"
+        ],
+        "commonFlags": [
+          "json",
+          "cwd",
+          "quiet",
+          "verbose",
+          "debug",
+          "reportTo",
+          "apiKey",
+          "open"
+        ],
+        "options": [
+          {
+            "flag": "--gate-save",
+            "description": "Architecture-gate: save current findings as baseline in the project SQLite store (mutually exclusive with --gate-compare)",
+            "default": false
+          },
+          {
+            "flag": "--gate-compare",
+            "description": "Architecture-gate: compare current findings against the saved baseline; exit 1 on regression",
+            "default": false
+          }
+        ],
+        "scope": "project",
+        "output": "raw-stream",
+        "rawStreamReason": "runtime-render-dispatch"
+      },
+      {
+        "name": "doctor",
+        "description": "Check that the osv-scanner binary is installed and ready",
+        "parent": "osv-scanner",
+        "commonFlags": [
+          "json",
+          "cwd"
+        ],
+        "scope": "none",
+        "output": "raw-stream",
+        "rawStreamReason": "diagnostic-gate"
+      },
+      {
+        "name": "version",
+        "description": "Print the resolved osv-scanner binary version",
+        "parent": "osv-scanner",
+        "commonFlags": [
+          "json",
+          "cwd"
+        ],
+        "scope": "none",
+        "output": "raw-stream",
+        "rawStreamReason": "diagnostic-gate"
+      }
+    ],
+    "config": {
+      "namespace": "osv-scanner",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "binaries": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "typescript": "~6.0.3",
+    "@opensip-cli/external-tool-adapter": "0.1.15",
+    "@opensip-cli/contracts": "0.1.15",
+    "@opensip-cli/core": "0.1.15"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}