Software Bill of Materials

1. Overview

A Software Bill of Materials (SBOM) is a complete, machine-readable inventory of every open-source and third-party component inside a piece of software — the equivalent of an ingredients list on a food label.

The Equinox Platform implements SBOM generation as a per-service npm script (npm run sbom:generate). The script uses the industry-standard CycloneDX format (spec version 1.5), scans the service’s node_modules and package.json, and writes an enriched JSON artifact to a local sbom/ directory. Two variants of the script exist:

• Basic variant — used by eq-auth-service (and similar). Generates a CycloneDX document and appends a small set of build/runtime metadata properties.
• Enhanced variant — used by eq-inventory-service (and similar). Adds a full sbomConfig declaration block that maps every backend framework, database driver, cloud SDK, custom library, DevOps component, test framework, third-party integration, and microservice endpoint. It also auto-detects AWS CDK resources from the cdk/ directory and merges security/AI/MCP status metadata.

The generated file is consumed by security scanners, audit tools (e.g. Snyk, OWASP Dependency-Check), license-compliance pipelines, and any procurement/regulatory process that requires a full supply chain manifest.

Business Value

Who Uses It

Related Resources

• CycloneDX specification: https://cyclonedx.org/specification/overview/
• cdxgen tool: https://github.com/CycloneDX/cdxgen
• SBOM output location: <service-root>/sbom/
• Versioned filename: <pkg-name>-<version>-cyclonedx.json
• Always-current copy: <pkg-name>-latest-cyclonedx.json

2. Core Features

3. How It Works — Generation Pipeline

npm run sbom:generate
        │
        ▼
  Read package.json
  (name, version, description, author)
        │
        ▼
  Read git metadata
  (git rev-parse --short HEAD → commit)
  (git rev-parse --abbrev-ref HEAD → branch)
        │
        ▼
  Create ./sbom/ directory (recursive, idempotent)
        │
        ▼
  Run @cyclonedx/cdxgen
  (-t js --spec-version 1.5
   --author "Equinox Platform Team"
   --supplier "Equinox"
   -o ./sbom/<name>-<version>-cyclonedx.json)
        │
        ▼
  Parse generated JSON
        │
        ├── [Basic variant stops here — skip to Metadata Enrichment]
        │
        ├── [Enhanced variant — auto-detect phase]
        │       detectCDKResources()
        │         └── scan ./cdk/*.ts / *.js for:
        │               lambda.Function → { type: "lambda" }
        │               apigateway       → { type: "api-gateway" }
        │               rds              → { type: "rds" }
        │               eventbridge      → { type: "eventbridge" }
        │       detectAPIEndpoints()
        │         └── read sbomConfig.microservices.services[].endpoints
        │
        ├── [Enhanced variant — component injection phase]
        │       Append to sbomData.components[]:
        │         1. Backend frameworks (type: library, group: Backend-Components, layer: Application Framework)
        │         2. Database drivers  (type: library, layer: Data Access)
        │         3. Cloud SDKs        (type: library, layer: Cloud SDK)
        │         4. Custom libraries  (type: library, layer: custom)
        │         5. Compute platform  (type: platform, layer: Compute)
        │         6. Infrastructure    (type: application, layer: Infrastructure)
        │         7. CI/CD pipelines   (type: application, layer: CI/CD)
        │         8. Containers        (type: container, layer: Containerization)
        │         9. E2E tests         (type: library, scope: optional, layer: E2E Testing)
        │        10. Unit tests        (type: library, scope: optional, layer: Unit Testing)
        │        11. API test libs     (type: library, scope: optional, layer: API Testing)
        │        12. Reporting libs    (type: library, scope: optional, layer: Test Reporting)
        │        13. Auth integrations (type: application, supplier: vendor)
        │        14. DB integrations   (type: application)
        │        15. Event streaming   (type: application)
        │        16. Caching           (type: application, status: optional)
        │        17. Monitoring        (type: application)
        │        18. Microservices     (type: application, endpoints, dataClassification, trustBoundary)
        │        19. Admin consoles    (type: application, access-level, security)
        │
        ▼
  Metadata Enrichment (sbomData.metadata.properties[])
  ─────────────────────────────────────────────────────
  equinox:build:timestamp  → ISO 8601 datetime
  equinox:build:commit     → short git SHA (or "unknown")
  equinox:build:branch     → branch name (or "unknown")
  equinox:runtime:nodejs   → process.version (e.g. v22.x)
  equinox:service:type     → e.g. "fastify-lambda", "inventory-service"
  equinox:service:domain   → e.g. "inventory-management"
  [Enhanced only:]
  orchestration:platform   → "AWS Lambda with API Gateway"
  orchestration:eventBus   → "AWS EventBridge for async event processing"
  orchestration:cronJobs   → e.g. "EventBridge Rules for replenishment scheduling"
  security:vulnerability-scanning:tools   → ["npm audit","OWASP","Snyk"]
  security:vulnerability-scanning:status  → "Manual - integrate automated scanning"
  security:static-analysis:tool           → "SonarQube"
  security:headers:helmet                 → "Enabled with CSP, HSTS, X-Frame-Options"
  security:headers:cors                   → "Strict origin whitelist with credentials disabled"
  ai:status                               → "NOT_IMPLEMENTED"
  ai:planned                              → JSON array of planned AI features
  mcp:status                              → "NOT_IMPLEMENTED"
  mcp:planned                             → JSON array of planned MCP tools
  detected:cdk-resources                  → JSON array of CDK-detected AWS resources
  detected:api-endpoints                  → JSON array of API path strings
        │
        ▼
  Write versioned file:  ./sbom/<name>-<version>-cyclonedx.json
  Write latest copy:     ./sbom/<name>-latest-cyclonedx.json
        │
        ▼
  Console summary printed
  (version, commit, branch, Node.js, component counts)

4. SBOM Output Structure

The generated JSON is a valid CycloneDX 1.5 BOM document. Top-level fields:

metadata object

Component entry shape (injected components)

{
  "type": "library | platform | application | container",
  "bom-ref": "backend:@fastify/fastify",
  "group": "Backend-Components",
  "name": "Fastify Web Framework",
  "version": "detected",
  "description": "High-performance web framework for Node.js",
  "scope": "required | optional",
  "supplier": { "name": "AWS" },
  "externalReferences": [{ "type": "website", "url": "https://…" }],
  "properties": [
    { "name": "category", "value": "Backend Components & Libraries" },
    { "name": "layer",    "value": "Application Framework" },
    { "name": "custom",   "value": "true" }
  ]
}

5. Configuration — sbomConfig Block (Enhanced Variant)

The enhanced generate-sbom.js contains a single sbomConfig constant that acts as the declarative manifest for all non-npm components. Edit this block per service to reflect the service’s actual technology footprint.

sbomConfig sections

bom-ref naming convention

Each injected component gets a bom-ref that is globally unique within the document:

6. Running SBOM Generation

When to run

How to run (per service)

# Standard services (generate-sbom.js at root)
cd eq-auth-service       # or eq-cart-service, eq-oms-service, etc.
npm run sbom:generate

# Inventory service (script in tools/scripts/)
cd eq-inventory-service
npm run sbom:generate

# PIM service — also validate after generating
cd eq-pim-service
npm run sbom:generate
npm run sbom:validate

What you see in the console

Generating SBOM for eq-authservices v9.0.0...
Git: main@a1b2c3d
✓ Generated: eq-authservices-9.0.0-cyclonedx.json
✓ Updated: eq-authservices-latest-cyclonedx.json

SBOM Location: /path/to/sbom/eq-authservices-9.0.0-cyclonedx.json

Metadata:
  - Version: 9.0.0
  - Commit: a1b2c3d
  - Branch: main
  - Node.js: v22.x.x

Enhanced variant additionally prints:

Components Tracked:
  - Backend: 1 frameworks, 1 databases
  - DevOps: 1 compute, 2 infrastructure
  - QE: 2 test frameworks
  - Integrations: 5 services
  - Microservices: 1 services

7. Services Coverage

Note: eq-promotion-service does not have an SBOM script. It should have generate-sbom.js added and @cyclonedx/cdxgen added as a devDependency.

8. Output Files

<service-root>/
└── sbom/
    ├── <pkg-name>-<version>-cyclonedx.json    ← versioned, immutable archive
    └── <pkg-name>-latest-cyclonedx.json       ← always-current copy (overwritten on each run)

Example (inventory service):

eq-inventory-service/
└── sbom/
    ├── eq-inventoryservices-9.0.1-cyclonedx.json
    └── eq-inventoryservices-latest-cyclonedx.json

The versioned file is suitable for artifact storage (S3, GitHub Releases, Nexus). The latest file is convenient for tooling that always needs the current state without knowing the version.

9. Tool & Dependency Details

@cyclonedx/cdxgen

cdxgen invocation (exact command)

npx @cyclonedx/cdxgen \
  -t js \
  --spec-version 1.5 \
  --author "Equinox Platform Team" \
  --supplier "Equinox" \
  -o "./sbom/<pkg-name>-<version>-cyclonedx.json"

10. Auto-Detection Logic (Enhanced Variant)

CDK Resource Detection — detectCDKResources()

Scans every .ts and .js file in ./cdk/ using string-pattern matching:

Results are pushed into sbomData.metadata.properties as detected:cdk-resources (JSON array).

If ./cdk/ does not exist, the function returns an empty array silently.

API Endpoint Detection — detectAPIEndpoints()

Reads sbomConfig.microservices.services[].endpoints[] and deduplicates the list. Results pushed to detected:api-endpoints in metadata properties.

11. Metadata Properties Reference

All custom properties follow the equinox: namespace convention and are stored in sbomData.metadata.properties[] as { name, value } pairs.

12. Environment Variables / Prerequisites

The SBOM script itself reads no environment variables. It relies on the following being present:

Node.js version

The script uses process.version — whichever Node.js is active on PATH. The Equinox platform targets Node.js 22.x (nodejs22.x Lambda runtime).

13. FAQs

14. Glossary