1. Home
2. Docs
3. Concepts
4. Security and SBOM

Vulnerability Scanning & SBOM Architecture

This document outlines how PackagingTools will enrich packaging runs with software bill of materials (SBOM) generation and vulnerability scanning, satisfying enterprise governance and supply-chain security requirements.

Implementation details for the Linux pipeline, including configuration flags and output locations, are summarised in Linux Security Artifacts.

Objectives

• Produce SBOMs for every packaging artifact (Windows, macOS, Linux) using industry standards (CycloneDX, SPDX).
• Execute vulnerability scanning (CVEs, malware signatures, policy scans) pre-publication.
• Capture results alongside packaging artifacts for auditing and policy enforcement.
• Support provider extensibility to integrate with customer-specific scanners (e.g., Trivy, Grype, Defender for Cloud, Anchore).

Architecture Overview

Packaging Pipeline
 ├─ Build artifacts (MSIX/MSI/PKG/DMG/DEB/RPM/AppImage/etc.)
 ├─ SBOM Generation
 │    ├─ Format-specific generators (CycloneDX JSON)
 │    └─ Aggregation service storing SBOMs in audit store
 └─ Vulnerability Scanning
      ├─ Scan orchestrator tickets artifacts
      ├─ Normalises results (CVSS, severity, identifiers)
      └─ Policy evaluator ensures blocking thresholds obeyed

Core Components

1. ISbomGenerator

   • Interface responsible for producing SBOM documents from PackageFormatContext.
   • Implementation per platform using native tooling (e.g., dotnet cyclonedx for .NET apps, syft for Linux packages).
   • Linux pipeline stores SBOMs under the packaging output directory _Sbom/<artifact-name>.cdx.json.

2. IVulnerabilityScanner

   • Runs configured scanner with artifact path and optionally SBOM.
   • Normalises results into VulnerabilityReport (list of findings with severity, CVE, advisory URL, fix versions).
   • Supports gating: pipeline fails when severity exceeds policy thresholds.

3. Security Policy

   • Extends PolicyEngineEvaluator to honour security configuration keys:
     • security.vuln.maxSeverity (e.g., block on Critical/High).
     • security.vuln.requiredProviders (ensures mandated scanners ran).
     • security.sbom.required toggles mandatory SBOM presence.

4. Audit Integration

   • SBOMs materialise on disk (e.g., _Sbom/*.cdx.json) and scanners surface findings through PackagingResult.Issues.
   • Telemetry events carry security.* dimensions for downstream aggregation.

Data Flow

1. Format provider finishes packaging.
2. Pipeline invokes SBOM generator (when security.sbom.enabled).
3. SBOM written to _Sbom/; informational issue logged.
4. Vulnerability scanners run (when security.vuln.enabled).
5. Findings converted into PackagingIssue entries and validated against policy.
6. Issues exposed via PackagingResult for CLI/GUI display and telemetry.

Extensibility

• Multiple SBOM generators/scanners can run; configuration selects primary output.
• Pluggable connectors allow uploading results to external systems (e.g., Defender, Harbor, GitHub Advanced Security).

Configuration Keys

Key	Description
security.sbom.enabled	Enable SBOM generation (default true).
security.sbom.format	Desired format (cyclonedx-json, spdx-json).
security.vuln.enabled	Enable vulnerability scanning.
security.vuln.providers	Comma-separated provider IDs (e.g., trivy,msdefender).
security.vuln.maxSeverity	Maximum allowed severity (Low, Medium, High, Critical).
security.vuln.failOnError	Fail packaging run if scanners return errors.

Next Steps

1. Expand SBOM generators beyond Linux/CycloneDX to Windows and macOS formats.
2. Add additional vulnerability providers (e.g., Grype, Microsoft Defender) and multi-scanner orchestration.
3. Feed security issues into policy engine gating rules and compliance exports.
4. Surface SBOM/vulnerability status in CLI output and GUI dashboards.