verimu 0.0.9 → 0.0.13

package/dist/index.d.cts

@@ -8,7 +8,7 @@ import { execSync } from 'child_process';
  *                                     → CveSource → Vulnerability[]
  */
 /** Supported package ecosystems */
-type Ecosystem = 'npm' | 'nuget' | 'cargo' | 'maven' | 'pip' | 'go' | 'ruby' | 'composer';
+type Ecosystem = 'npm' | 'nuget' | 'cargo' | 'maven' | 'pip' | 'poetry' | 'uv' | 'go' | 'ruby' | 'composer' | 'deno';
 /** Supported CI/CD providers */
 type CiProvider = 'github' | 'gitlab' | 'bitbucket';
 /** A single resolved dependency from a lockfile */
@@ -37,8 +37,8 @@ interface ScanResult {
     /** Timestamp of when the scan was performed */
     scannedAt: string;
 }
-/** Supported SBOM output formats */
-type SbomFormat = 'cyclonedx-json' | 'cyclonedx-xml' | 'spdx-json';
+/** Supported software inventory output formats */
+type SbomFormat = 'cyclonedx-json' | 'cyclonedx-xml' | 'spdx-json' | 'swid-xml';
 /** A generated Software Bill of Materials */
 interface Sbom {
     /** The format of this SBOM */
@@ -52,6 +52,15 @@ interface Sbom {
     /** Timestamp of generation */
     generatedAt: string;
 }
+/** All software inventory artifacts generated for a scan */
+interface SbomArtifacts {
+    /** Primary CRA-compatible SBOM used for backend parsing */
+    cyclonedx: Sbom;
+    /** SPDX 2.3 JSON document for interoperability */
+    spdx: Sbom;
+    /** Minimal SWID XML tag for root product identity */
+    swid: Sbom;
+}
 /** Severity levels aligned with CVSS v3 */
 type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN';
 /** A single known vulnerability */
@@ -109,6 +118,8 @@ interface VerimuReport {
     };
     /** Generated SBOM */
     sbom: Sbom;
+    /** All generated software inventory artifacts (CycloneDX + SPDX + SWID) */
+    artifacts?: SbomArtifacts;
     /** CVE check results */
     cveCheck: CveCheckResult;
     /** Overall summary */
@@ -128,10 +139,12 @@ interface VerimuReport {
 interface VerimuConfig {
     /** Path to the project to scan */
     projectPath: string;
-    /** Where to write the SBOM file (default: ./sbom.cdx.json) */
+    /** Where to write the CycloneDX SBOM file (default: ./sbom.cdx.json) */
     sbomOutput?: string;
-    /** SBOM format (default: cyclonedx-json) */
+    /** Reserved for future per-format selection (currently all formats are generated) */
     sbomFormat?: SbomFormat;
+    /** CycloneDX spec version to generate (default: '1.7') */
+    cyclonedxVersion?: '1.4' | '1.5' | '1.6' | '1.7';
     /** Minimum severity to report (default: LOW) */
     severityThreshold?: Severity;
     /** Whether to fail CI on vulnerabilities at or above threshold */
@@ -183,6 +196,32 @@ interface GenerateSbomResult {
     /** ISO timestamp of generation */
     generatedAt: string;
 }
+/** Output of the pure `generateSpdxSbom()` function */
+interface GenerateSpdxSbomResult {
+    /** The SPDX document as a parsed JavaScript object */
+    sbom: Record<string, unknown>;
+    /** The SPDX document as a formatted JSON string */
+    content: string;
+    /** Number of dependency components represented in the document */
+    componentCount: number;
+    /** SPDX spec version used */
+    specVersion: string;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+}
+/** Output of the pure `generateSwidTag()` function */
+interface GenerateSwidTagResult {
+    /** The SWID XML tag */
+    tag: string;
+    /** Alias of `tag` for consistency with the JSON generators */
+    content: string;
+    /** Number of components represented in the tag */
+    componentCount: number;
+    /** SWID spec identifier */
+    specVersion: string;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+}
 
 /**
  * Generates an NTIA-compliant CycloneDX 1.7 SBOM from structured dependency data.
@@ -210,6 +249,21 @@ interface GenerateSbomResult {
  */
 declare function generateSbom(input: GenerateSbomInput): GenerateSbomResult;
 
+/**
+ * Generates an SPDX 2.3 JSON document from structured dependency data.
+ *
+ * This is a pure function with no filesystem or network access.
+ */
+declare function generateSpdxSbom(input: GenerateSbomInput): GenerateSpdxSbomResult;
+
+/**
+ * Generates a minimal SWID XML tag for the root software product.
+ *
+ * This is intentionally minimal for v1. The current tag describes the root
+ * product identity and generator metadata only.
+ */
+declare function generateSwidTag(input: GenerateSbomInput): GenerateSwidTagResult;
+
 /**
  * Verimu API client — communicates with the Verimu backend.
  *
@@ -257,6 +311,11 @@ interface ScanResponse {
         vulnerable_dependencies: number;
     };
 }
+interface SbomUploadBundle {
+    cyclonedx: Record<string, unknown>;
+    spdx?: Record<string, unknown>;
+    swid?: string;
+}
 declare class VerimuApiClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -272,9 +331,13 @@ declare class VerimuApiClient {
         platform?: string;
     }): Promise<UpsertProjectResponse>;
     /**
-     * Upload a CycloneDX SBOM to a project and trigger CVE scanning.
+     * Upload a software inventory artifact payload to a project and trigger CVE scanning.
+     *
+     * Backward-compatible:
+     * - string payloads are treated as legacy raw CycloneDX JSON
+     * - object payloads can include CycloneDX + SPDX + SWID together
      */
-    uploadSbom(projectId: string, sbomContent: string): Promise<ScanResponse>;
+    uploadSbom(projectId: string, payload: string | SbomUploadBundle): Promise<ScanResponse>;
     private headers;
     /**
      * Maps internal ecosystem names to what the backend expects.
@@ -295,7 +358,7 @@ interface UploadResult {
 /**
  * Main scan pipeline — orchestrates the full Verimu workflow:
  *   1. Detect ecosystem & parse lockfile
- *   2. Generate CycloneDX SBOM
+ *   2. Generate software inventory artifacts (CycloneDX + SPDX + SWID)
  *   3. Check dependencies for CVEs (via OSV)
  *   4. Produce report
  *   5. Upload to Verimu platform (if API key provided)
@@ -305,7 +368,7 @@ declare function scan(config: VerimuConfig): Promise<VerimuReport>;
  * Uploads scan results to the Verimu platform.
  *
  * 1. Upserts the project (create-if-not-exists by name)
- * 2. POSTs the SBOM for dependency tracking + CVE scanning
+ * 2. POSTs the artifact bundle for dependency tracking + CVE scanning
  */
 declare function uploadToVerimu(report: VerimuReport, config: VerimuConfig): Promise<UploadResult>;
 /**
@@ -752,6 +815,316 @@ declare class ComposerScanner implements DependencyScanner {
     private buildPurl;
 }
 
+/**
+ * Yarn dependency scanner.
+ *
+ * Supports Yarn v1 (Classic) and Yarn v2/v3/v4 (Berry) lockfile formats.
+ *
+ * - Yarn v1: Plain text format with indentation
+ * - Yarn v2+: YAML-based format with __metadata section
+ *
+ * Parses yarn.lock to extract the full resolved dependency tree.
+ * Also reads package.json to determine which dependencies are direct vs transitive.
+ *
+ * Note: Yarn uses the npm ecosystem since it's an alternative
+ * package manager for the npm registry.
+ */
+declare class YarnScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses yarn.lock file and extracts dependencies.
+     * Automatically detects and handles both v1 (Classic) and v2+ (Berry) formats.
+     */
+    private parseLockfile;
+    /**
+     * Detects if the lockfile is Yarn v2+ (Berry) format.
+     * v2+ uses YAML format and contains __metadata section.
+     */
+    private isYarnV2Plus;
+    /**
+     * Parses Yarn v2+ (Berry) lockfile format.
+     *
+     * Yarn v2+ format (YAML):
+     * ```yaml
+     * __metadata:
+     *   version: 6
+     *
+     * "package-name@npm:^1.0.0":
+     *   version: 1.2.3
+     *   resolution: "package-name@npm:1.2.3"
+     *   dependencies:
+     *     dep1: ^2.0.0
+     *   checksum: ...
+     *   languageName: node
+     *   linkType: hard
+     * ```
+     */
+    private parseLockfileV2Plus;
+    /**
+     * Extracts package name from Yarn v2+ resolution field.
+     * The resolution field contains the real package name.
+     * Examples:
+     *   "express@npm:4.18.2" → "express"
+     *   "@types/node@npm:20.11.5" → "@types/node"
+     *   "lodash@npm:4.17.21" → "lodash"
+     */
+    private extractPackageNameFromResolution;
+    /**
+     * Extracts package name from Yarn v2+ package key.
+     * Examples:
+     *   "express@npm:^4.18.0" → "express"
+     *   "@types/node@npm:^20.0.0" → "@types/node"
+     *   "pkg@npm:other@npm:^1.0.0" → "pkg" (aliased packages)
+     */
+    private extractPackageNameV2Plus;
+    /**
+     * Parses Yarn v1 (Classic) lockfile format.
+     *
+     * Yarn v1 format:
+     * ```
+     * "package-name@^1.0.0":
+     *   version "1.2.3"
+     *   resolved "https://..."
+     *   integrity sha512-...
+     *   dependencies:
+     *     dep1 "^2.0.0"
+     * ```
+     */
+    private parseLockfileV1;
+    /**
+     * Adds a dependency to the result list (deduplicates by name@version)
+     */
+    private addDependency;
+    /**
+     * Extracts package name from yarn.lock package declaration.
+     * Examples:
+     *   "express@^4.18.0" → "express"
+     *   "@types/node@^20.0.0" → "@types/node"
+     *   "pkg@npm:other@^1.0.0" → "pkg" (aliased packages)
+     */
+    private extractPackageName;
+    /**
+     * Builds a purl (Package URL) for an npm package.
+     *
+     * Per the purl spec:
+     * "The npm scope @ sign prefix is always percent encoded."
+     *
+     * So @types/node@20.11.5 → pkg:npm/%40types/node@20.11.5
+     * And express@4.18.2 → pkg:npm/express@4.18.2
+     */
+    private buildPurl;
+}
+
+/**
+ * pnpm dependency scanner.
+ *
+ * Parses pnpm-lock.yaml to extract the full resolved dependency tree
+ * and determine which dependencies are direct vs transitive.
+ *
+ * Note: pnpm uses the npm ecosystem since it's an alternative
+ * package manager for the npm registry.
+ */
+declare class PnpmScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses pnpm-lock.yaml file and extracts dependencies.
+     *
+     * pnpm-lock.yaml format (v5.4+):
+     * ```yaml
+     * lockfileVersion: 5.4
+     *
+     * dependencies:
+     *   express: 4.18.2
+     *
+     * devDependencies:
+     *   typescript: 5.0.0
+     *
+     * packages:
+     *   /express/4.18.2:
+     *     resolution: {integrity: sha512-...}
+     *     dependencies:
+     *       accepts: 1.3.8
+     *   /@types/node/20.11.5:
+     *     resolution: {integrity: sha512-...}
+     *     dev: true
+     * ```
+     *
+     * pnpm-lock.yaml format (v6.0+):
+     * ```yaml
+     * lockfileVersion: '6.0'
+     *
+     * dependencies:
+     *   express:
+     *     specifier: ^4.18.0
+     *     version: 4.18.2
+     *
+     * packages:
+     *   /express@4.18.2:
+     *     resolution: {integrity: sha512-...}
+     * ```
+     */
+    private parseLockfile;
+    /**
+     * Extracts direct dependency names from pnpm lockfile.
+     *
+     * Supports both formats:
+     * - pnpm v5.x: root-level dependencies/devDependencies
+     * - pnpm v6+: importers['.'].dependencies/devDependencies
+     */
+    private extractDirectDependencies;
+    /**
+     * Parses lockfile version (can be string or number)
+     */
+    private parseLockfileVersion;
+    /**
+     * Extracts dependencies from the lockfile packages section
+     */
+    private extractDependencies;
+    /**
+     * Parses package path to extract name and version.
+     *
+     * pnpm v5.x format:
+     *   "/express/4.18.2" → name: "express", version: "4.18.2"
+     *   "/@types/node/20.11.5" → name: "@types/node", version: "20.11.5"
+     *   "/accepts/1.3.8" → name: "accepts", version: "1.3.8"
+     *
+     * pnpm v6+ format:
+     *   "/express@4.18.2" → name: "express", version: "4.18.2"
+     *   "/@types/node@20.11.5" → name: "@types/node", version: "20.11.5"
+     *   "/accepts@1.3.8" → name: "accepts", version: "1.3.8"
+     *
+     * Also handles peer dependency suffixes:
+     *   "/pkg@1.0.0_dep@2.0.0" → name: "pkg", version: "1.0.0"
+     *   "/pkg@1.0.0(dep@2.0.0)" → name: "pkg", version: "1.0.0"
+     */
+    private parsePackagePath;
+    /**
+     * Parses v6+ format: "express@4.18.2" or "@types/node@20.11.5"
+     */
+    private parseV6Format;
+    /**
+     * Parses v5.x format: "express/4.18.2" or "@types/node/20.11.5"
+     */
+    private parseV5Format;
+    /**
+     * Builds a purl (Package URL) for an npm package.
+     *
+     * Per the purl spec:
+     * "The npm scope @ sign prefix is always percent encoded."
+     *
+     * So @types/node@20.11.5 → pkg:npm/%40types/node@20.11.5
+     * And express@4.18.2 → pkg:npm/express@4.18.2
+     */
+    private buildPurl;
+}
+
+/**
+ * Deno dependency scanner.
+ *
+ * Limitations:
+ * - HTTPS/remote imports (deno.lock `remote` section) are not scanned.
+ * - JSR packages are not directly supported by OSV so vulnerability scan will fail
+ *
+ * deno.lock v4/v5 format:
+ * ```json
+ * {
+ *   "version": "4",
+ *   "specifiers": {
+ *     "jsr:@std/assert@^1.0.0": "1.0.10",
+ *     "npm:express@^4.18.0": "4.21.2"
+ *   },
+ *   "jsr": {
+ *     "@std/assert@1.0.10": { "integrity": "..." },
+ *     "@std/internal@1.0.6": { "integrity": "..." }
+ *   },
+ *   "npm": {
+ *     "express@4.21.2": { "integrity": "...", "dependencies": {...} }
+ *   }
+ * }
+ * ```
+ *
+ * deno.lock v3 format:
+ * ```json
+ * {
+ *   "version": "3",
+ *   "packages": {
+ *     "specifiers": {
+ *       "jsr:@std/path@^1.0.0": "jsr:@std/path@1.0.8",
+ *       "npm:hono@^4.0.0": "npm:hono@4.6.20"
+ *     },
+ *     "jsr": {
+ *       "@std/path@1.0.8": { "integrity": "..." },
+ *       "@std/internal@1.0.6": { "integrity": "..." }
+ *     },
+ *     "npm": {
+ *       "hono@4.6.20": { "integrity": "...", "dependencies": {...} }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class DenoScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses the lockfile and extracts dependencies from both
+     * npm and jsr package registries.
+     *
+     * Supports v3 (packages nested under `packages`), v4, and v5 (top-level jsr/npm sections).
+     * Uses lockfile specifiers to determine direct vs transitive dependencies.
+     */
+    private parseLockfile;
+    /**
+     * Extracts direct dependency names from lockfile specifiers.
+     *
+     * Returns a set of ecosystem-qualified package names like "jsr:@std/assert" or "npm:express".
+     * The ecosystem prefix prevents collisions if the same package name exists in both registries.
+     */
+    private extractDirectDependencies;
+    /**
+     * Parses a package key like "@std/assert@1.0.10" or "express@4.21.2"
+     * into { name, version }.
+     *
+     * Handles scoped packages where the name starts with @ (e.g., @std/assert).
+     * In that case the version separator is the LAST @ sign.
+     */
+    private parsePackageKey;
+    /**
+     * Extracts the package name from a Deno import specifier.
+     *
+     * Examples:
+     *   "jsr:@std/assert@^1.0.0" → "@std/assert"
+     *   "npm:express@^4.18.0"    → "express"
+     *   "npm:@hono/hono@^4.0.0"  → "@hono/hono"
+     *   "lodash" (bare)          → "lodash"
+     */
+    private extractNameFromSpecifier;
+    /**
+     * Builds a purl for a JSR package.
+     *
+     * JSR packages use the "jsr" purl type (non-standard but descriptive).
+     * For scoped packages, both @ and all / characters are percent-encoded.
+     * Example: `pkg:jsr/%40std%2Fassert@1.0.10`
+     */
+    private buildJsrPurl;
+    /**
+     * Builds a purl for an npm package used via Deno.
+     *
+     * Uses the standard npm purl type since these are npm packages.
+     * Per npm purl spec, only @ is encoded, / remains as namespace separator.
+     * Example: `pkg:npm/%40std/assert@1.0.10` or `pkg:npm/express@4.21.2`
+     */
+    private buildNpmPurl;
+}
+
 /**
  * Registry of all available dependency scanners.
  * Auto-detects the correct scanner for a given project.
@@ -781,34 +1154,32 @@ interface SbomGenerator {
     generate(scanResult: ScanResult, toolVersion?: string): Sbom;
 }
 
+/** Supported CycloneDX spec versions */
+type CycloneDxSpecVersion = '1.4' | '1.5' | '1.6' | '1.7';
 /**
- * Generates CycloneDX 1.7 JSON SBOMs.
+ * Generates CycloneDX JSON SBOMs (versions 1.4 – 1.7).
  *
  * CycloneDX is the preferred SBOM format for CRA compliance.
- * Spec: https://cyclonedx.org/docs/1.7/json/
+ * Spec: https://cyclonedx.org/specification/overview/
  *
  * NTIA minimum elements are satisfied:
  *  - metadata.supplier (supplier of the root software)
  *  - components[].supplier (supplier of each dependency)
  *  - components[].name, version, purl, bom-ref
  *  - dependencies[] graph
+ *
+ * Schema differences handled per version:
+ *  - 1.4: metadata.tools is a flat array of { vendor, name, version, ... }
+ *  - 1.5+: metadata.tools is { components: [...] }
  */
 declare class CycloneDxGenerator implements SbomGenerator {
+    private readonly specVersion;
     readonly format: SbomFormat;
+    constructor(specVersion?: CycloneDxSpecVersion);
     generate(scanResult: ScanResult, toolVersion?: string): Sbom;
     private buildBom;
     /** Converts a Verimu Dependency to a CycloneDX component */
     private toComponent;
-    /**
-     * Derives a supplier name from a package name.
-     *
-     * For scoped packages like "@vue/reactivity" → "@vue"
-     * For unscoped packages like "express" → "express"
-     *
-     * This is the same heuristic used by Syft, Trivy, and other SBOM tools
-     * when registry metadata (author/publisher) isn't available from the lockfile.
-     */
-    private deriveSupplierName;
     /**
      * Builds the dependency graph section of the SBOM.
      *
@@ -821,8 +1192,28 @@ declare class CycloneDxGenerator implements SbomGenerator {
      * dependency relationship.
      */
     private buildDependencyGraph;
-    /** Extracts project name from path */
-    private extractProjectName;
+    /**
+     * Builds the tools metadata section.
+     *
+     * CycloneDX 1.4: tools is a flat array of { vendor, name, version, ... }
+     * CycloneDX 1.5+: tools is an object { components: [...] }
+     */
+    private buildTools;
+}
+
+/** Generates every supported software inventory artifact for a scan. */
+declare function generateSbomArtifacts(scanResult: ScanResult, toolVersion?: string, cyclonedxVersion?: CycloneDxSpecVersion): SbomArtifacts;
+
+/** Generates SPDX 2.3 JSON SBOMs. */
+declare class SpdxJsonGenerator implements SbomGenerator {
+    readonly format: SbomFormat;
+    generate(scanResult: ScanResult, toolVersion?: string): Sbom;
+}
+
+/** Generates a minimal SWID XML tag for the root software product. */
+declare class SwidTagGenerator implements SbomGenerator {
+    readonly format: SbomFormat;
+    generate(scanResult: ScanResult, toolVersion?: string): Sbom;
 }
 
 /**
@@ -930,4 +1321,4 @@ declare class ConsoleReporter implements Reporter {
     report(result: VerimuReport): string;
 }
 
-export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, RubyScanner, type Sbom, type SbomDependency, type SbomFormat, type ScanResult, ScannerRegistry, type Severity, type UploadResult, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, generateSbom, printReport, scan, shouldFailCi, uploadToVerimu };
+export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, printReport, scan, shouldFailCi, uploadToVerimu };