@stackwright-pro/sbom-enterprise

Enterprise SBOM features for Stackwright - CVE enrichment, signing, SLSA provenance, registry publishing, and compliance reporting

Features

• 🔒 CVE Enrichment: Automatically enrich SBOMs with vulnerability data from OSV.dev
• ✍️ SBOM Signing: Sign SBOMs using Sigstore or cosign for tamper evidence
• 📋 SLSA Provenance: Generate and attach SLSA Level 3 provenance attestations
• 📤 Registry Publishing: Publish SBOMs to GitHub, Artifactory, AWS, and Azure registries
• 📊 Compliance Reports: Generate NIST SSDF and FedRAMP alignment reports

Installation

# Install with peer dependencies
pnpm add @stackwright-pro/sbom-enterprise @stackwright/sbom-generator

# Or install peer dependency separately
pnpm add @stackwright/sbom-generator

Quick Start

Auto-Registration (Recommended)

Import the package to automatically register all hooks:

// Automatically registers CVE enrichment, signing, provenance, and publishing
import '@stackwright-pro/sbom-enterprise';

Manual Hook Usage

If you need more control, import specific functions:

import {
  enrichWithCVEs,
  signWithSigstore,
  generateProvenance,
} from '@stackwright-pro/sbom-enterprise';

// Enrich dependencies with CVE data
const enrichedDeps = await enrichWithCVEs(dependencies);

// Sign an SBOM document
const signature = await signWithSigstore(spdxDocument);

// Generate SLSA provenance
const provenance = await generateProvenance(context);

Configuration

Environment Variables

Configure the package using environment variables:

# OSV API
SBOM_ENTERPRISE_OSV_API_KEY=your-osv-api-key

# Sigstore
SBOM_ENTERPRISE_FULCIO_URL=https://fulcio.sigstore.dev
SBOM_ENTERPRISE_REKOR_URL=https://rekor.sigstore.dev
SBOM_ENTERPRISE_IDENTITY_TOKEN=your-oidc-token

# Feature Flags
SBOM_ENTERPRISE_ENABLE_CVE=true       # CVE enrichment (default: true)
SBOM_ENTERPRISE_ENABLE_SIGNING=false  # SBOM signing (default: false)
SBOM_ENTERPRISE_ENABLE_PROVENANCE=false # SLSA provenance (default: false)
SBOM_ENTERPRISE_ENABLE_PUBLISHING=false # Registry publishing (default: false)

Security Environment Variables

| Variable | Description | Required | | -------------------------------- | ---------------------------------------------------------- | ------------------ | | NODE_ENV | Set to production for production mode (signing required) | Yes | | SBOM_ENTERPRISE_OSV_API_KEY | OSV.dev API key for vulnerability enrichment | No | | SBOM_ENTERPRISE_IDENTITY_TOKEN | Sigstore OIDC token for signing | Production signing |

stackwright.yml Configuration

sbom:
  enterprise:
    osvApiKey: ${OSV_API_KEY}
    features:
      cveEnrichment: true
      signing: true
      provenance: true
      publishing: false
    sigstoreOpts:
      fulcioUrl: https://fulcio.sigstore.dev
      rekorUrl: https://rekor.sigstore.dev
    slsa:
      builderId: https://stackwright.dev/builder/sbom
      sourceRepo: https://github.com/your-org/your-repo

Registry Configuration

import { getEffectiveConfig } from '@stackwright-pro/sbom-enterprise';

const config = getEffectiveConfig();

// Add registries
config.registries = [
  {
    type: 'github',
    url: 'https://api.github.com',
    credentials: { envVar: 'GITHUB_TOKEN', type: 'token' },
    options: { repo: 'owner/repo' },
  },
  {
    type: 'artifactory',
    url: 'https://your-org.jfrog.io',
    credentials: { envVar: 'ARTIFACTORY_API_KEY', type: 'token' },
    options: { repository: 'sbom-local' },
  },
];

Hook Reference

The package auto-registers the following hooks with @stackwright/sbom-generator:

| Hook | Type | Priority | Critical | Description | | ----------------- | ------------- | -------- | -------- | -------------------------------------------------- | | slsa-provenance | preWrite | 5 | No | Generates SLSA provenance before files are written | | cve-enrichment | postAnalyze | 10 | No | Enriches dependencies with OSV vulnerability data | | sign-sbom | postFormat | 20 | Yes | Signs SBOM documents using Sigstore | | publish-sbom | postWrite | 90 | No | Publishes SBOMs to configured registries |

Hook Lifecycle

preGenerate
    ↓
postAnalyze ←── cve-enrichment (priority 10)
    ↓
preFormat
    ↓
postFormat ←── sign-sbom (priority 20) ⚠️ critical
    ↓
preWrite ←────── slsa-provenance (priority 5)
    ↓
postWrite ←──── publish-sbom (priority 90)

API Reference

Types

// Enriched dependency with vulnerability data
interface EnrichedDependency extends NormalizedDependency {
  vulnerabilities?: CVEFinding[];
}

// CVE vulnerability finding
interface CVEFinding {
  id: string; // e.g., "CVE-2024-1234"
  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN';
  score?: number; // CVSS score
  summary: string;
  details?: string;
  affectedVersionRange?: string;
  fixedVersion?: string;
  references?: string[];
}

// SBOM signature
interface SBOMSignature {
  format: 'spdx' | 'cyclonedx' | 'build-manifest';
  signature: string;
  keyId?: string;
  method: 'sigstore' | 'cosign' | 'gpg';
  timestamp: string;
  certificate?: string;
}

// SLSA Provenance
interface SLSBProvenance {
  version: string;
  buildType: string;
  invocationId: string;
  materials: ProvenanceMaterial[];
  builder: ProvenanceBuilder;
  metadata?: ProvenanceMetadata;
}

Functions

enrichWithCVEs(dependencies, context?)

Enrich dependencies with CVE vulnerability data from OSV.dev.

const enriched = await enrichWithCVEs(dependencies, context);

signWithSigstore(data, options?)

Sign data using Sigstore (fulcio + rekor).

const signature = await signWithSigstore(spdxJson, {
  fulcioUrl: 'https://fulcio.sigstore.dev',
  rekorUrl: 'https://rekor.sigstore.dev',
  identityToken: process.env.OIDC_TOKEN,
});

generateProvenance(context)

Generate SLSA Level 3 provenance attestation.

const provenance = await generateProvenance(context);

publishToRegistries(context)

Publish SBOMs to configured registries.

const urls = await publishToRegistries(context);
console.log('Published to:', urls);

Compliance Catalogs

Structured control catalog data for CMMC L2, NIST 800-171r3, and FedRAMP is extracted from the official source documents in compliance-sources/ by the scripts in scripts/compliance/.

Catalog JSON files are generated artifacts (.gitignored) — regenerate them with:

# From the repo root
tsx scripts/compliance/run-all.ts

| Catalog | Source | Controls | | ----------------------- | --------------------------------------------------------- | ------------------------ | | CMMC L2 practices | AssessmentGuideL2v2.pdf | 110 practices | | NIST SP 800-171 Rev 3 | NIST.SP.800-171r3.pdf | 130 controls + crosswalk | | FedRAMP Annual Controls | CSP_Annual_Assessment_Controls_Selection_Worksheet.xlsx | 103 unique controls |

Catalog TypeScript types are exported from: packages/sbom-enterprise/src/compliance/catalogs/index.ts

See scripts/compliance/README.md for full documentation.

Compliance Reports

Generate compliance reports for your SBOM to support regulatory requirements:

NIST SSDF Compliance

Map your SBOM capabilities to the NIST Secure Software Development Framework (NIST SP 800-218).

import {
  generateNISTSSDFReport,
  generateComplianceSummary,
} from '@stackwright-pro/sbom-enterprise';

// Generate NIST SSDF compliance report
const nistReport = await generateNISTSSDFReport(context, {
  includeEvidence: true,
  minVulnSeverity: 'HIGH',
  softwareVersion: '1.0.0',
});

// Check compliance score
console.log(`Overall Compliance: ${nistReport.summary.overallCompliance}%`);
console.log(
  `Controls Passed: ${nistReport.summary.controlsPassed}/${nistReport.summary.totalControls}`
);

// View gaps
for (const gap of nistReport.vulnerabilityManagement.gaps) {
  console.log(`Gap: ${gap}`);
}

// Print human-readable summary
console.log(generateComplianceSummary(nistReport));

SSDF Controls Assessed:

• PO.1 - Organization-wide Software Security Practices
• PO.2 - Software Security Requirements
• PO.3 - Threat Modeling
• PS.1 - Secure Software Infrastructure
• PS.2 - Software Integrity
• PW.1 - Secure Coding Practices
• PW.4 - Software Integrity Verification
• PW.9 - Software Release Practices
• RV.1 - Vulnerability Analysis and Remediation

FedRAMP Alignment

Generate FedRAMP control alignment reports for Moderate and High impact systems.

import {
  generateFedRAMPReport,
  generateFedRAMPSummary,
  exportControlsAsCSV,
} from '@stackwright-pro/sbom-enterprise';

// Generate FedRAMP alignment report
const fedrampReport = await generateFedRAMPReport(context, {
  systemName: 'My FedRAMP System',
  authorizationBoundary: 'Cloud Services - Production',
  impactLevel: 'Moderate',
  includeEvidence: true,
});

// Check compliance score
console.log(`FedRAMP Compliance: ${fedrampReport.summary.compliancePercentage}%`);
console.log(
  `Implemented: ${fedrampReport.summary.implemented}/${fedrampReport.summary.applicable}`
);

// View recommendations
for (const rec of fedrampReport.recommendations) {
  console.log(`Recommendation: ${rec}`);
}

// Print human-readable summary
console.log(generateFedRAMPSummary(fedrampReport));

// Export controls as CSV for SSP/POA&M
const csv = exportControlsAsCSV(Object.values(fedrampReport.controls));
console.log(csv);

FedRAMP Controls Assessed: | Control | Name | Relevance to SBOM | |---------|------|-------------------| | SA-4 | Acquisition Process | Software component inventory for supply chain requirements | | SA-8 | Security Engineering Principles | Software transparency and supply chain visibility | | SA-11 | Developer-Provided Training | Vulnerability data for developer security awareness | | SA-15 | Development Process, Standards, and Tools | SBOM tooling documentation | | CM-2 | Baseline Configuration | SBOM as configuration baseline | | CM-8 | System Component Inventory | Full SBOM generation and publishing | | SI-2 | Flaw Remediation | Vulnerability tracking and remediation | | SI-10 | Information Input Validation | Component validation and PURL support |

Report Output Example

// NIST SSDF Report
const nistReport = generateNISTSSDFReport(context);
console.log(generateComplianceSummary(nistReport));

/*
═══════════════════════════════════════════════════════════════
                    NIST SSDF COMPLIANCE REPORT
═══════════════════════════════════════════════════════════════

Generated: 2024-01-15T10:00:00Z
Software:  [email protected]

───────────────────────────────────────────────────────────────
                       SUMMARY
───────────────────────────────────────────────────────────────
Overall Compliance: 67%
Controls Passed:    6/9
Controls Partial:   2
Controls Failed:    1

───────────────────────────────────────────────────────────────
                       CONTROLS
───────────────────────────────────────────────────────────────
✓ PASS   PO.1 - Organization Practices
✓ PASS   PO.2 - Security Requirements
◐ PARTIAL PS.1 - Secure Infrastructure
✗ FAIL   PS.2 - Software Integrity
...
*/

// FedRAMP Report
const fedrampReport = generateFedRAMPReport(context, {
  systemName: 'Cloud Service System',
  impactLevel: 'Moderate',
});
console.log(generateFedRAMPSummary(fedrampReport));

/*
═══════════════════════════════════════════════════════════════════
                    FEDRAMP ALIGNMENT REPORT
═══════════════════════════════════════════════════════════════════

Generated: 2024-01-15T10:00:00Z
System:    Cloud Service System
Impact:    Moderate
Boundary:  Full system boundary

───────────────────────────────────────────────────────────────────
                       SUMMARY
───────────────────────────────────────────────────────────────────
FedRAMP Compliance: 75%
Controls:          6/8 Implemented
                    2 Partial
                    0 Not Implemented
                    0 Not Applicable

[SA] System and Services Acquisition
  ✓ SA-4 Acquisition Process - Implemented
  ◐ SA-8 Security Engineering - Partial
  ...

───────────────────────────────────────────────────────────────────
                       RECOMMENDATIONS
───────────────────────────────────────────────────────────────────
1. Enable SBOM signing with Sigstore to provide tamper evidence.
2. Generate SLSA provenance attestation to document build process.
*/

Compliance Control Mapping

The compliance control-mapping layer provides a framework-agnostic assessment engine, typed report generators for NIST 800-53 and CMMC L2, and three auditor-ready export formats (OSCAL JSON, CSV, Markdown).

Assessment Engine

import {
  assessControl,
  assessFramework,
  DEFAULT_ASSESSMENT_RULES,
} from '@stackwright-pro/sbom-enterprise';
import type { ControlEvidence } from '@stackwright-pro/sbom-enterprise';

// Assess a single control against collected evidence
const result = assessControl(control, evidence, {
  impactLevel: 'Moderate', // filters out non-applicable controls
  rules: DEFAULT_ASSESSMENT_RULES,
});
// result.status: 'Implemented' | 'Partial' | 'NotImplemented' | 'NA'

// Assess an entire framework catalog at once
const report = assessFramework('NIST-800-53', NIST_800_53_CONTROLS, evidence, {
  systemName: 'My FedRAMP System',
  impactLevel: 'Moderate',
});
console.log(`Compliance: ${report.summary.compliancePercentage}%`);

Status determination rules (default):

| Evidence available | Status | | ------------------------------------- | ---------------- | | Automated or hybrid | Implemented | | Manual only | Partial | | None | NotImplemented | | Control out of scope for impact level | NA |

Override rules via AssessmentRules:

assessControl(control, evidence, {
  rules: { requireAutomatedForImplemented: false, implementedThreshold: 2 },
});

NIST SP 800-53 Report Generator

import {
  generateNIST80053Report,
  generateNIST80053Summary,
} from '@stackwright-pro/sbom-enterprise';

const report = generateNIST80053Report(evidence, {
  systemName: 'My GovCloud System',
  impactLevel: 'Moderate', // Low | Moderate | High
});

// Controls grouped by family (CM, SA, SI, IA, AU, SR, …)
for (const family of report.controlFamilies) {
  console.log(`[${family.id}] ${family.name}`);
  for (const ctl of family.controls) {
    console.log(`  ${ctl.controlId}: ${ctl.status}`);
  }
}

// Human-readable terminal summary
console.log(generateNIST80053Summary(report));

CMMC Level 2 Report Generator

import { generateCMMCReport, generateCMMCSummary } from '@stackwright-pro/sbom-enterprise';

const report = generateCMMCReport(evidence, {
  systemName: 'My CUI System',
  impactLevel: 'Moderate',
});

console.log(`CMMC L2: ${report.summary.compliancePercentage}%`);
console.log(
  `Practices: ${report.summary.implemented}/${report.summary.totalPractices} Implemented`
);

// Each practice result includes the NIST SP 800-171r2 requirement mapping
for (const domain of report.controlDomains) {
  console.log(`[${domain.abbreviation}] ${domain.name}`);
  for (const practice of domain.controls) {
    console.log(`  ${practice.controlId} → 800-171r2: ${practice.nist171r2Requirement}`);
  }
}

console.log(generateCMMCSummary(report));

OSCAL Export (FedRAMP SSP / ATO packages)

OSCAL (Open Security Controls Assessment Language) is the mandated format for FedRAMP System Security Plans. exportAsOSCAL produces a valid OSCAL v1.1.2 assessment-results document:

import { assessFramework, exportAsOSCAL } from '@stackwright-pro/sbom-enterprise';
import { NIST_800_53_CONTROLS } from '@stackwright-pro/sbom-enterprise';

const report = assessFramework('NIST-800-53', NIST_800_53_CONTROLS, evidence, {
  systemName: 'My FedRAMP System',
  impactLevel: 'Moderate',
});

const oscal = exportAsOSCAL(report);
// Save as JSON for inclusion in your ATO package:
// fs.writeFileSync('compliance-results.oscal.json', JSON.stringify(oscal, null, 2));

OSCAL status mapping:

| Engine status | OSCAL finding state | | ---------------- | ------------------- | | Implemented | satisfied | | Partial | not-satisfied | | NotImplemented | not-satisfied | | NA | not-applicable |

For idempotent re-generation (stable document UUID across pipeline runs):

const oscal = exportAsOSCAL(report, {
  documentUuid: process.env.OSCAL_DOCUMENT_UUID, // pin this in CI
});

CSV Export (POA&M / SSP worksheets)

import { exportAsCSV, exportMultiFrameworkCSV } from '@stackwright-pro/sbom-enterprise';

// Single framework — compatible with POA&M worksheet imports
const csv = exportAsCSV(nistReport);
// fs.writeFileSync('nist-800-53-poa-m.csv', csv);

// Multi-framework merged CSV — side-by-side gap analysis
const merged = exportMultiFrameworkCSV([nistReport, cmmcReport]);
// fs.writeFileSync('all-frameworks-poa-m.csv', merged);

CSV columns: Control ID, Framework, Family, Title, Status, Evidence Summary, Gaps, Remediation.

Markdown Export (Review artifacts)

import { exportAsMarkdown } from '@stackwright-pro/sbom-enterprise';

const md = exportAsMarkdown(report);
// fs.writeFileSync('compliance-report.md', md);

Produces a human-readable report with summary statistics, per-control status table, and prioritised recommendations — suitable for engineering review and audit evidence packages.

Cross-Framework Crosswalk Matrix

Map a common security topic (e.g. "Software Bill of Materials") across all frameworks at once:

import {
  exportCrossWalkMatrix,
  formatCrossWalkMatrixAsCSV,
} from '@stackwright-pro/sbom-enterprise';

const matrix = exportCrossWalkMatrix(evidence);

// Human-readable text table
for (const row of matrix.rows) {
  console.log(`${row.topic}: NIST=${row.nist80053?.join(',')}, CMMC=${row.cmmc?.join(',')}`);
}

// CSV format for spreadsheet import
const csv = formatCrossWalkMatrixAsCSV(matrix);

Pipeline Hook — Auto-Generated Compliance Reports

When a compliance block is present in stackwright.yml, the generate-compliance-reports hook runs automatically in the postWrite phase of the SBOM pipeline:

# stackwright.yml
sbom:
  enterprise:
    compliance:
      frameworks:
        - nist80053 # → NIST SP 800-53 Rev 5
        - cmmc # → CMMC Level 2
        - fedramp # → FedRAMP Moderate/High
        - nistSsdf # → NIST SP 800-218 SSDF
      outputFormats:
        - oscal # OSCAL JSON (ATO packages)
        - csv # POA&M worksheets
        - markdown # Human-readable review artifacts
      outputDir: ./compliance-reports
      systemName: My CUI Processing System
      impactLevel: Moderate

Output files are written to outputDir as: <framework>-compliance.<oscal.json|csv|md>

The hook is non-critical — failures are logged as warnings and never block the SBOM pipeline.

Debug Logging

Enable debug output:

NODE_ENV=development STACKWRIGHT_DEBUG=true pnpm your-command

This outputs hook registration and execution details:

🔒 SBOM-Enterprise Debug: Hooks registered
[
  { type: 'postAnalyze', name: 'cve-enrichment', priority: 10, critical: false },
  { type: 'postFormat', name: 'sign-sbom', priority: 20, critical: true },
  ...
]

Error Handling

• Critical hooks (like sign-sbom): Errors will fail the entire SBOM generation
• Non-critical hooks (CVE, provenance, publishing): Errors are logged and skipped

// The signing hook is marked critical - SBOM generation will fail if signing fails
registerSBOMHook({
  type: 'postFormat',
  name: 'sign-sbom',
  priority: 20,
  critical: true, // Fail-fast for security-critical operations
  handler: signerHookHandler,
});

Security

This package implements enterprise-grade security controls:

Credential Management

• API keys loaded from environment variables (never hardcoded)
• Credentials masked in debug output
• Secure memory handling

Supply Chain Security

• SBOM signing via Sigstore/cosign
• SLSA Level 3 provenance attestation
• Rekor transparency log verification
• Production mode: Signing failures fail hard (no fallback to mock signatures)

Input Validation

• SSRF protection: Registry URLs validated against blocked IP ranges
• Path traversal prevention: File access restricted to project root
• SBOM content validation before signing
• TLS 1.2+ required for external API calls

Known Security Considerations

1. Airgapped Environments: Network-dependent features (CVE enrichment, registry publishing) require --no-enrichment flag
2. Signing in CI/CD: Requires cosign binary or Sigstore credentials in production
3. Registry Credentials: Use environment variables, not config files, for production

Troubleshooting

Signing Fails in Production

Error: CRITICAL: SBOM signing failed in production mode.

Solution: Ensure cosign is installed or Sigstore credentials are configured.

SSRF Error When Publishing

Error: Blocked hostname pattern: 169.254.x.x

Solution: Registry URLs must use public HTTPS endpoints. Internal IPs are blocked.

Path Traversal Error

Error: Path traversal detected: ../../../etc/passwd

Solution: Ensure projectRoot points to your project directory.

Security Testing

# Run security tests
pnpm test --grep "security"

# Verify SSRF protection
# Configure registry to internal IP - should reject
SBOM_ENTERPRISE_REGISTRY_URL="http://169.254.169.254/" pnpm test

# Verify credential masking
STACKWRIGHT_DEBUG=true SBOM_ENTERPRISE_OSV_API_KEY=secret123 pnpm build
# Check output does not contain "secret123"

Examples

Basic Usage with SBOM CLI

// stackwright.config.ts
import '@stackwright-pro/sbom-enterprise';

export default {
  // Your config...
};

Custom Hook Handler

import { registerSBOMHook } from '@stackwright/sbom-generator';
import { enrichWithCVEs } from '@stackwright-pro/sbom-enterprise';

// Add custom CVE handler with different priority
registerSBOMHook({
  type: 'postAnalyze',
  name: 'custom-cve-enrichment',
  priority: 5, // Run before default (10)
  critical: false,
  handler: async (ctx) => {
    if (ctx.dependencies) {
      // Use your own CVE source
      ctx.dependencies = await enrichWithCVEs(ctx.dependencies, ctx);
    }
  },
});

GitHub Actions Integration

# .github/workflows/sbom.yml
name: SBOM

on:
  push:
    branches: [main]

jobs:
  sbom:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      attestations: write
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install

      - name: Generate SBOM with enterprise features
        env:
          SBOM_ENTERPRISE_ENABLE_SIGNING: true
          SBOM_ENTERPRISE_ENABLE_PROVENANCE: true
          SBOM_ENTERPRISE_IDENTITY_TOKEN: ${{ steps.auth.outputs.token }}
        run: pnpm stackwright sbom generate

License

Proprietary - Stackwright Pro

See Also

• @stackwright/sbom-generator - Core SBOM generation
• OSV.dev - Open Source Vulnerabilities database
• Sigstore - Software signing and verification
• SLSA - Supply chain levels for software artifacts
• NIST SSDF - Secure Software Development Framework
• FedRAMP - Federal Risk and Authorization Management Program