cdxgen
AGENTS.md1.1k starsChanged 14 days agoApache-2.0View on GitHub
This document helps AI coding agents (GitHub Copilot, Claude, Cursor, etc.) understand the cdxgen codebase conventions, architecture, and contribution rules so they can produce code that fits naturally with the existing style. cdxgen is a universal, polyglot CycloneDX Bill-of-Materials (BOM) generator. It produces SBOM, CBOM, OBOM, SaaSBOM, CDXA, and VDR documents in CycloneDX JSON format. It is distributed as an npm package (@cdxgen/cdxgen), a container image, and a Deno/Bun-compatible script. Primary entry points: Companion binaries:
- Reads credentials
- Installs packages
1 other project uses a version of this.
Trending
Quiet this year.about the whole repository
Most recently taken up by
- cdxgen/cdxgenword for word, first seen Oct 8, 2026
Who's talking about CycloneDX/cdxgen
- nodejs/node“npm on Windows fails with module not found for Node.js 22.0.0”GitHub · Apr 25, 2024 · 33 reactions
- CycloneDX/cyclonedx-go“Improve support for the `Component.Evidence.Identity` field in CycloneDX 1.6”GitHub · Jul 30, 2024 · 4 reactions
- cdxgen/cdxgen“Bazel build being run for non-Bazel projects, causing errors”GitHub · Sep 10, 2024 · 3 reactions
- cdxgen/cdxgen“[pnpm] Improve metadata collection with node_modules parsing”GitHub · Aug 7, 2025 · 2 reactions
- cdxgen/cdxgen“Add docs and fix for allowlist of hosts and commands”GitHub · Jun 29, 2025 · 2 reactions
The biggest 5 of 41 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 41
Talked about on GitHub and Bluesky (41 times).
On GitHub · 40
- Apr 25, 2024npm on Windows fails with module not found for Node.js 22.0.0 — nodejs/node33 reactions · 47 comments
- Jul 30, 2024Improve support for the `Component.Evidence.Identity` field in CycloneDX 1.6 — CycloneDX/cyclonedx-go4 reactions · 11 comments
- Sep 10, 2024Bazel build being run for non-Bazel projects, causing errors — cdxgen/cdxgen3 reactions · 3 comments
- Aug 7, 2025[pnpm] Improve metadata collection with node_modules parsing — cdxgen/cdxgen2 reactions · 6 comments
- Jun 29, 2025Add docs and fix for allowlist of hosts and commands — cdxgen/cdxgen2 reactions · 1 comment
35 more on GitHub
- May 1, 2025feat: make bazel query compatible with newer bazel versions and rules… — cdxgen/cdxgen2 reactions · 3 comments
- Oct 27, 2024Run some GitHub action jobs only on main repository — cdxgen/cdxgen2 reactions
- Jul 2, 2024Invalid Dotnet version detected and missing versions for the dependencies — cdxgen/cdxgen2 reactions · 12 comments
- Apr 22, 2024Add support for executing dependencies task in parallel for Gradle — cdxgen/cdxgen2 reactions · 6 comments
- Feb 1, 2024Added support for components properties filter — cdxgen/cdxgen2 reactions · 4 comments
- Dec 23, 2023[core] Improve exclude to match sub-directories — cdxgen/cdxgen2 reactions
- Oct 8, 2023Switching to java 21 — cdxgen/cdxgen2 reactions · 2 comments
- Sep 11, 2023Fix npm package deps tree — cdxgen/cdxgen2 reactions · 13 comments
- Jun 27, 20231.4 compatibility mode — cdxgen/cdxgen2 reactions
- May 26, 2023Even after setting CDX_MAVEN_INCLUDE_TEST_SCOPE=false some of the dependencies of test modules created in BOM — cdxgen/cdxgen2 reactions · 5 comments
- Oct 7, 2025Re-enable license fetching — MediaMarktSaturn/technolinator1 reaction · 1 comment
- Aug 15, 2025Extend data tracked for each package type and ecosystem with extra reference information — package-url/purl-spec1 reaction · 3 comments
- Jun 9, 2025bugfix: normalize component evidence identities to always be array — cdxgen/cdxgen1 reaction
- Jun 8, 2025Fix technique filtering logic by correctly checking for intersection — cdxgen/cdxgen1 reaction
- Apr 15, 2025Ignore uncommented lines in gradle build scripts — cdxgen/cdxgen1 reaction · 3 comments
- Feb 20, 2025Fix pnpm and yarn lock file detection — cdxgen/cdxgen1 reaction
- Jul 24, 2024Speed up SBOM generation by using newest features — apache/airflow1 reaction
- Jul 2, 2024Do not aggressively exclude while dealing with java projects — cdxgen/cdxgen1 reaction · 4 comments
- May 30, 2024Sanitize externalReferences URLs and exclude invalid ones + Strict JSON Schema validation — cdxgen/cdxgen1 reaction · 13 comments
- May 20, 2024Fix: Split linux-tests job into two jobs — cdxgen/cdxgen1 reaction
- Apr 30, 2024Adds a new workflow to generate SBOM — DefectDojo/django-DefectDojo1 reaction · 4 comments
- Apr 18, 2024Regenerate lock file and types. Adds vuln scanning — cdxgen/cdxgen1 reaction
- Mar 27, 2024cdx 1.6 spec support with some goodies — cdxgen/cdxgen1 reaction · 5 comments
- Jan 27, 2024Make 10.x branch the default — cdxgen/cdxgen1 reaction · 1 comment
- Jan 27, 2024Remove xml format — cdxgen/cdxgen1 reaction
- Nov 21, 2023Feature/nydus demo — cdxgen/cdxgen1 reaction
- Nov 16, 2023Fixes for Server params — cdxgen/cdxgen1 reaction · 5 comments
- Nov 15, 2023Support for private docker registry — cdxgen/cdxgen1 reaction · 2 comments
- Oct 23, 2023Generated license sometimes not valid according to BOM schema — cdxgen/cdxgen1 reaction · 6 comments
- Oct 12, 2023Filters and config files support — cdxgen/cdxgen1 reaction
- Jul 3, 2023MINOR: 9.1.0 release with deno, evidences and python dependency tree. 1 BREAKING change — cdxgen/cdxgen1 reaction · 2 comments
- Jun 30, 2023Provide possibility to define alternative NUGET API base url — cdxgen/cdxgen1 reaction · 3 comments
- May 29, 2023scanning setup.py doesn't work if "install_requires" is initialized to a variable instead of a list of strings — cdxgen/cdxgen1 reaction · 2 comments
- Mar 7, 2023Rendering multiple Subtrees in dependency tree tab of Dependency tracker — DependencyTrack/dependency-track1 reaction · 4 comments
- Feb 27, 2023Dependency Graph cannot be generated — cdxgen/cdxgen1 reaction · 11 comments
On Bluesky · 1
- Feb 4, 2025The first step towards #crypto #agility is to be able to make an inventory of all your crypto assets. Currently, there are no… — @seceng.bsky.social0 likes and reposts · 2 replies
Other versions1 project uses a version of this.
Word for word · 1
- cdxgen/cdxgen★ 1.1k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository7 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- bom-slimmerSkill
- custom-property-authorSkill
- cyclonedx-spec-reviewerSkill
- ecosystem-onboardingSkill
- sbom-fidelity-loopSkill
- SKILL.mdSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
68 rules. About 4 are common, 12 are distinctive, and 52 are very specific to this project.
≈4
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
52
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 27
When the optional trustinspector helper is present, host-path trust enrichment should be treated as batched rather than artificially capped.
- Very specific: line 108
Avoid regexes with nested quantifiers, overlapping alternations, or ambiguous greedy groups (for example (...*)*, broad .*/[\s\S]* capture …
- Distinctive: line 109
If regex is still the clearest tool, keep it linear-time, anchored, and narrowly scoped to one token at a time.
- Very specific: line 192
Keep this path layered as bin/evinse.js → lib/evinser/evinser.js → lib/ecosystems/golem.js.
- Very specific: line 229
When a per-language step produces data that postProcess needs (e.g.
- Very specific: line 246
Every directory under lib/ belongs to a numbered layer, and an import may only reach a strictly lower layer.
- Very specific: line 277
If you find yourself writing import { … } from "../../cli/index.js" in a lower layer, stop and extract the function downward first.
- Very specific: line 302
Never build a purl by string concatenation: it skips encoding and qualifier validation, which is how pkg:generic/name#/abs/path and …
- Very specific: line 317
Every cdx: property must be described in docs/CUSTOM_PROPERTIES.md.
- Very specific: line 324
Use schema-valid cryptoProperties.assetType values only:
- Very specific: line 332
If you add new osquery- or rootfs-derived crypto inventory, validate it against lib/validator/bomValidator.js expectations and the …
- Very specific: line 338
Do not emit raw go:generate command strings, raw environment values, embedded file contents, generated source contents, or full command …
- Very specific: line 339
Prefer scope-aware policy signals.
- Very specific: line 340
Prefer bounded defaults for data-flow in CI: --deep or --with-data-flow --golem-dataflow crypto with capped workers, capped …
- Very specific: line 341
Keep BOM audit rules in data/rules/golem-go.yaml aligned with emitted property names and document new rules in docs/BOM_AUDIT.md.
- Very specific: line 342
Keep cdxi pivots aligned with the analyst flow: .golemsummary for run context, .golemhotspots for risk review, and .golemcoverage for …
- Very specific: line 359
Prefer thoughtLog over ad-hoc console.log for introspective messages inside core logic so they can be silenced in production.
- Very specific: line 374
Always use the safe wrappers rather than the raw Node.js equivalents:
- Distinctive: line 388
When adding or modifying external-facing features (SCM/network integrations like release notes, git metadata, repository lookups), treat …
- Distinctive: line 391
Prefer parsing helpers that normalize and filter unsafe refs before selection.
- Distinctive: line 392
Never pass user/remote-derived refs directly into git log/git revision arguments without validation.
- Very specific: line 393
Use hardenedGitCommand() (or safeSpawnSync wrappers where applicable) instead of raw process execution.
- Very specific: line 394
Use cdxgenAgent for outbound HTTP and source tokens from options/environment without logging credentials.
- Very specific: line 398
When emitting CycloneDX properties, annotations, evidence objects, or service/component metadata, treat every value as potentially …
- Common: line 400
Never emit raw secrets or likely secret carriers into BOM fields, including:
- Distinctive: line 404
Prefer booleans, counts, categories, and field names over raw values.
- Distinctive: line 410
Treat URLs and URIs as untrusted.
- Common: line 414
Treat command strings as untrusted.
- Very specific: line 415
Treat free-text mirrored metadata as untrusted.
- Very specific: line 416
If a value is useful for analysis but may contain credentials, emit a safe derivative instead (count, host, scheme, basename, allowlisted …
- Common: line 417
Add or update tests whenever new emitted properties are introduced to assert that secrets are not copied into BOM output.
- Very specific: line 423
All cdxgen-specific variables use the CDXGEN_ prefix (or a well-known tool-specific name such as JAVA_HOME or PYTHON_CMD).
- Very specific: line 427
Read them with readEnvironmentVariable from lib/core/activity.js, never process.env directly — the helper records the read so dry-run mode …
- Very specific: line 450
Add a create<Language>Bom(path, options) function in lib/cli/index.js, following the same signature and return shape as the existing …
- Very specific: line 451
Add parser functions in lib/ecosystems/utils.js (for lock file / manifest parsing) or a new helper module under lib/helpers/.
- Very specific: line 453
Add a dispatch branch in createXBom / createBom in lib/cli/index.js.
- Very specific: line 455
Add fixture files to test/ and cover with a *.poku.js test.
- Very specific: line 456
If updating OSQuery table metadata in data/queries*.json (for example purlType or componentType), review all platform variants …
- Very specific: line 457
Always consider adding/expanding repotests.yml coverage with a representative public repository for the ecosystem change.
- Distinctive: line 501
Treat every unit/integration test as cross-platform unless a test is explicitly platform-scoped.
- Very specific: line 502
Always check string/path assertions against Windows and POSIX path separator differences (\ vs /).
- Very specific: line 503
Prefer node:path helpers, normalization, or separator-agnostic assertions over hard-coded path literals in tests.
- Very specific: line 504
When adding or changing tests that inspect file paths, temp directories, command arguments, or serialized activity/log output, verify they …
- Very specific: line 508
Unit coverage: use lib/managers/binary.poku.js for rootfs/container parsing logic, repository-source parsing, trusted-key modeling, and …
- Very specific: line 510
Rule coverage: use lib/stages/postgen/auditBom.poku.js when changing data/rules/*.yaml, lib/inventory/auditCategories.js, or …
- Very specific: line 511
Analyzer coverage: use lib/inventory/analyzer.poku.js, lib/inventory/cbomutils.poku.js, and lib/ecosystems/utils.poku.js when changing …
- Very specific: line 512
Binary E2E coverage: use lib/managers/binary.e2e.poku.js for real Trivy/rootfs integration when the local environment has the companion …
- Very specific: line 513
Docker-script parity checks: use ci/dockertests.sh plus ci/assertions.sh for archive vs reconstructed-rootfs parity, tool identity …
- Distinctive: line 518
Before finalizing work, review feedback from automated code review or validation tools.
- Distinctive: line 519
If a review comment is valid, fix it in the same change rather than leaving it behind.
- Distinctive: line 520
If a review comment is not valid, document why it was not applied in the final summary.
- Very specific: line 539
Use assert and describe/it/test from poku (they re-export Node's assert plus test grouping).
- Very specific: line 560
Test files are excluded from the Biome linter ("!test/" in biome.json), so slightly looser style is acceptable there, but still follow the …
- Very specific: line 608
All GitHub Actions workflows pin action SHA digests and have permissions: {} at the job level (least-privilege).
- Very specific: line 635
Follow each one with Link: and the URL of that issue, comment or pull request:
- Very specific: line 645
Put the trailers in every commit that uses the work, and repeat them under ## Credits in the pull request description.
- Distinctive: line 646
Do not use these trailers for bots, AI tools or yourself.
- Very specific: line 654
Do not use npm or yarn.
- Very specific: line 663
Do not: use spawnSync / execSync directly — use safeSpawnSync.
- Very specific: line 664
Do not: use existsSync / mkdirSync directly — use safeExistsSync / safeMkdirSync.
- Very specific: line 667
Do not: read process.argv inside library modules — accept options via the options object.
- Common: line 668
Do not: commit secrets, tokens, or credentials.
- Very specific: line 671
Do not: add console.log debug statements to production code without gating them on DEBUG_MODE or replacing them with thoughtLog.
- Very specific: line 672
Do not: add or update pnpm-lock.yaml unless changing package.json dependencies.
- Very specific: line 673
Do not: import from lib/cli/index.js inside lib/helpers/* or lib/stages/* — this creates a circular-like cross-layer dependency.
- Very specific: line 674
Do not: add logic that must execute once-per-BOM inside buildBomNSData — it is called once per language type.
- Very specific: line 675
Do not: add any generic functions to lib/cli/index.js and lib/ecosystems/utils.js.
- Distinctive: line 676
Do not: add complex all-in-one regex parsers for filenames or other externally sourced strings when tokenization plus small validators will …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — cdxgen contributor guide for AI agents
This document helps AI coding agents (GitHub Copilot, Claude, Cursor, etc.) understand the cdxgen codebase conventions, architecture, and contribution rules so they can produce code that fits naturally with the existing style.
Project overview
cdxgen is a universal, polyglot CycloneDX Bill-of-Materials (BOM) generator. It produces SBOM, CBOM, OBOM, SaaSBOM, CDXA, and VDR documents in CycloneDX JSON format. It is distributed as an npm package (@cdxgen/cdxgen), a container image, and a Deno/Bun-compatible script.
Primary entry points:
- CLI —
bin/cdxgen.js(calls intolib/cli/index.js) - Audit CLI —
bin/audit.js(cdx-auditpredictive supply-chain audit withconsole,json, andsarifreporters) - Conversion CLI —
bin/convert.js(cdx-convertCycloneDX → SPDX export) - Library —
lib/cli/index.jsexportscreateBom,submitBom - HTTP server —
lib/server/server.js(started viabin/repl.jsorcdxgen --server) - REPL —
bin/repl.js
Companion binaries:
- cdxgen opportunistically uses the optional companion package/repo
cdxgen-plugins-binfor heavyweight native helpers such as Trivy, osquery, SourceKitten, dosai, and golem. - Dynamic SBOM generation via tracebom depends only on
@cdxgen/safer-exec+@cdxgen/cdx-protofrom optional deps. No atom, no plugins-bin, no hbom. - Container/rootfs inventory flows through
lib/managers/binary.jsand may combine native parsing with plugin-enriched Trivy output. - Live-OS OBOM flows use the bundled osquery binary plus the query packs under
data/queries*.json. Linux query packs also include hardening-focused snapshots such assysctl_hardeningandmount_hardening. osquery 5.24.0 (cdxgen-plugins-bin 4.2.0) addspacman_packages,snap_packages,flatpak_packages, Homebrew on Linux,macports_packages,ai_agent_skills(converted byconvertAgentSkillRows()intofilecomponents that share theai-skillscan'scdx:skill:*vocabulary and have no purl),gpu_infoandchrome_search_engines;gpu_metricsstays out because its values change on every run. osquery has no apk table, so on Alpine, Wolfi and Chainguard hostslib/inventory/apkInstalledDb.jsreads the apk installed database instead. - An OS package has one purl wherever cdxgen finds it.
buildOsPackagePurl()inlib/inventory/osPackagePurl.jsnames deb, rpm, apk, pacman (alpm), Homebrew, MacPorts, snap and flatpak packages for the OBOM rows and the file-to-package resolver, with the distro from the samegetDistroInfo()the container scan reads. A package-manager row never carries a host path as its purl subpath; npm, pypi, browser extension and VS Code extension rows record where they were found inevidence.occurrencesinstead, and a Chromium or VS Code extension gets the purl-t chrome-extensionor-t vscode-extensiongives it. - When the optional
trustinspectorhelper is present, host-path trust enrichment should be treated as batched rather than artificially capped. Keep Authenticode, WDAC, code-signing, and notarization properties intact across large inventories. - GTFOBins enrichment is expected on Linux live-runtime osquery components in the same way LOLBAS enrichment is expected on Windows runtime components.
- Go Evinse flows use the bundled
golemhelper when available. Keepcdx:golem:*metadata and component properties safe, compact, and policy-friendly: counts, categories, scopes, source locations, data-flow rule IDs, taint-kind labels, crypto algorithm names/OIDs, and module facts are acceptable, but do not emit raw generator commands, environment values, HTTP parameter values, raw key material, embedded file contents, generated source contents, or secrets.
Module system and runtime
- The package is pure ESM (
"type": "module"inpackage.json). There is no CommonJS source except the generatedindex.cjsshim. - The project targets Node.js ≥ 24 with optional support for Bun and Deno (see
devEnginesinpackage.json). - Detect the runtime with the helpers exported from
lib/ecosystems/utils.js:export const isNode = globalThis.process?.versions?.node !== undefined; export const isBun = globalThis.Bun?.version !== undefined; export const isDeno = globalThis.Deno?.version?.deno !== undefined;
Import conventions
Always use the node: protocol for built-ins
// correct
import { readFileSync } from "node:fs";
import path from "node:path";
import process from "node:process";
// wrong — missing node: prefix
import { readFileSync } from "fs";Import ordering (enforced by Biome)
Biome (biome.json) enforces this exact three-group order, with a blank line between each group:
1. Node built-ins (node:*)
<blank line>
2. npm packages (@cdxgen/cdx-purl, semver, undici, …)
<blank line>
3. Local modules (../../helpers/utils.js, …)Code style (Biome)
The linter and formatter is Biome (not ESLint/Prettier).
| Setting | Value |
| Indent | 2 spaces |
| Formatter | enabled for lib/** and root JS/JSON (excludes test/, data/, contrib/, types/) |
| Linter | enabled for the same scope |
Run locally:
pnpm run lint # check + auto-fix
pnpm run lint:check # check only (only for CI)
pnpm run lint:errors # errors onlyKey rules to be aware of (see biome.json):
noUndeclaredVariables— error. Don't leave variables undeclared.noConstAssign— error.useDefaultParameterLast— error (default params must come last).useSingleVarDeclarator— error (one binding perconst/let).noUnusedVariables— warn (use_prefixfor intentionally unused vars).noParameterAssign— off (reassigning parameters is allowed).noForEach— off (.forEach()is acceptable).noDelete— off (delete obj.propis acceptable).noAssignInExpressions— off.- Comments starting with
// biome-ignoreare the escape hatch for individual rule suppressions.
Prefer deterministic parsing over monolithic regexes
- For filenames, URLs, refs, manifests, and other untrusted or user-controlled text, prefer
split(),startsWith(),endsWith(),indexOf(), and small anchored validators over a single large parsing regex. - Avoid regexes with nested quantifiers, overlapping alternations, or ambiguous greedy groups (for example
(...*)*, broad.*/[\s\S]*capture chains, or long optional hyphen-separated groups) because they are harder to review and can trigger CodeQL inefficient-regular-expression findings. - If regex is still the clearest tool, keep it linear-time, anchored, and narrowly scoped to one token at a time.
Repository layout
.agents/ Agent-facing skills and workspace configuration (see .agents/README.md)
bin/ CLI entry points (audit.js, cdxgen.js, convert.js, evinse.js, repl.js, verify.js, sign.js, validate.js)
lib/
audit/ Predictive supply-chain audit engine, scoring, progress, and reporters for `cdx-audit`
cli/ Core BOM generation logic (index.js ~9 000 lines)
evinser/ Evinse / SaaSBOM evidence generation
helpers/
analyzer.js JS/TS import/export analysis, MCP inventory, and crypto-aware AST extraction
asarutils.js Electron ASAR parsing, file inventory, hashes, and embedded manifest extraction
caxa.js Caxa (self-extracting) executable parsing
cbomutils.js Cryptography BOM helpers, OID lookup, and source-derived algorithm inventory
db.js SQLite / atom DB helpers
depsUtils.js mergeDependencies + trimComponents (shared BOM dependency utilities)
display.js Terminal output tables and summaries
dotnetutils.js .NET assembly / NuGet utilities
dynamic.js Dynamic process tracing SBOM generator
envcontext.js Git, env info, tool availability checks
formulationParsers.js CycloneDX formulation section builder; addFormulationSection()
golem.js Go Evinse helper integration, Golem invocation, and cdx:golem evidence mapping
inventoryStats.js Shared filters and counters for unpackaged native files and source-derived crypto pivots
logger.js thoughtLog / traceLog / THINK_MODE / TRACE_MODE
osPackageResolver.js Map dynamic libraries to operating system packages
protobom.js Protobuf-based BOM utilities
pythonutils.js Python venv / conda helpers
traceRunner.js Execute commands under safer-exec tracing and collect loaded library paths
utils.js ~18 000-line utility module; most parsing functions live here
bomValidator.js CycloneDX JSON schema validation
managers/
docker.js Docker daemon / OCI operations
oci.js OCI image layer extraction
piptree.js pip dependency tree
parsers/
iri.js IRI reference validator
npmrc.js .npmrc parser
server/
server.js connect-based HTTP server
stages/
postgen/ Post-processing (annotator.js, postgen.js)
pregen/ Pre-generation env setup (pregen.js, envAudit.js)
third-party/
arborist/ Forked npm arborist for workspace support
data/ Static data files (license SPDX list, frameworks list, …)
test/ Sample lockfiles, manifests, and fixtures used by poku tests
types/ Auto-generated TypeScript `.d.ts` declarations (do not edit)
docs/ Documentation (Markdown)
plugins/ cdxgen plugin entry point stubs
contrib/ Community scripts (not linted)
ci/ Dockerfiles for CI imagesKey abstractions
options object
Every public function accepts a single options plain object. It is created by the CLI argument parser in bin/cdxgen.js and threaded through the entire call chain without mutation. When adding new CLI flags, add them to the yargs builder in bin/cdxgen.js and pass them through options — never read process.argv directly inside library code.
createBom(path, options) — lib/cli/index.js
The top-level export. Dispatches to per-language create*Bom functions based on options.projectType. Returns { bomJson, dependencies, parentComponent, … }.
postProcess(bomNSData, options) — lib/stages/postgen/postgen.js
Runs after BOM generation: filtering, standards application, metadata enrichment, formulation population, and annotations. It is called exactly once per BOM generation cycle — by bin/cdxgen.js and lib/server/server.js — after createBom returns.
Any logic that must execute exactly once across all language types must live here, not inside buildBomNSData (which is invoked once per language type and therefore runs multiple times for multi-type projects).
prepareEnv(filePath, options) — lib/stages/pregen/pregen.js
Runs before BOM generation to install missing build tools via sdkman, nvm, rbenv, etc.
Go Evinse with Golem
evinse -l go calls lib/ecosystems/golem.js, which resolves the optional golem plugin binary, runs golem analyze --format json, and maps the report into CycloneDX evidence. Occurrences and call-stack frames are attached to matching Go module purls. Data-flow traces are mapped to occurrence and call-stack evidence when --deep, --with-data-flow, --profile research, or explicit --golem-dataflow options are used. Metadata-level cdx:golem:* properties are appended to bom.metadata.component; component-level cdx:golem:* properties are appended to matching dependency components; crypto evidence can add schema-valid cryptographic-asset components without purls.
Keep this path layered as bin/evinse.js → lib/evinser/evinser.js → lib/ecosystems/golem.js. Do not import CLI modules from helpers. When adding Golem evidence, update docs/GO_EVINSE_GOLEM.md, docs/CUSTOM_PROPERTIES.md, docs/EVINSE.md, docs/GO_EVINSE_GOLEM_THREAT_MODEL.md, docs/BOM_AUDIT.md, docs/LESSON14.md, repo-test assertions in .github/workflows/repotests.yml, and the REPL commands in bin/repl.js if the new property creates a useful analyst pivot.
BOM generation pipeline
Understanding the call chain is critical to placing new logic in the right spot.
bin/cdxgen.js (or server.js)
└── createBom(path, options) lib/cli/index.js
├── createXBom(path, options) — single project type
│ └── create<Language>Bom(path, options)
│ └── buildBomNSData(options, pkgList, ptype, context)
│ — called ONCE PER LANGUAGE TYPE
│ — returns { bomJson, nsMapping, dependencies, parentComponent, formulationList? }
│
└── createMultiXBom(pathList, options) — multiple types or container
├── createXBom() × N (one per type/path)
└── dedupeBom() → merges all per-type results
└── postProcess(bomNSData, options) lib/stages/postgen/postgen.js
— called EXACTLY ONCE after createBom returns
— correct place for: formulation, annotations, filtering, metadata enrichmentKey implication: multi-invocation of buildBomNSData
buildBomNSData is called once per language type. A command like
cdxgen -t js,java,python triggers three separate calls. Any side-effect
placed inside buildBomNSData will run three times.
Rule: Logic that must execute once per BOM (e.g. formulation, final
annotations, global deduplication) belongs in postProcess, not in
buildBomNSData or createMultiXBom.
Forwarding per-language data to postProcess
When a per-language step produces data that postProcess needs (e.g. Pixi
lock formulation components), attach it to bomNSData before returning:
// inside buildBomNSData:
if (context?.formulationList?.length) {
bomNSData.formulationList = context.formulationList;
}postProcess can then read bomNSData.formulationList and incorporate it
into the single formulation section it builds.
Module layering rules
Every directory under lib/ belongs to a numbered layer, and an import may only
reach a strictly lower layer. contrib/check-boundaries.js owns the table and
enforces it: node contrib/check-boundaries.js --strict must report zero cycles
and zero violations.
| Layer | Directories |
| 0 | lib/core |
| 1 | lib/parsers |
| 2 | lib/inventory, lib/helpers |
| 3 | lib/ecosystems |
| 4 | lib/managers, lib/stages/pregen, lib/stages/postgen |
| 5 | lib/cli, lib/evinser, lib/validator |
| 6 | lib/server, lib/audit |
lib/third-party is vendored and opts out of the rule.
Never import lib/cli/index.js from a lower layer. A utility both layers
need belongs in a layer both can reach:
| Utility | Location |
mergeDependencies | lib/inventory/depsUtils.js |
trimComponents | lib/inventory/depsUtils.js |
addFormulationSection | lib/inventory/formulationParsers.js |
Go Evinse/Golem evidence mapping belongs in lib/ecosystems/golem.js; the
enriched BOM write-back belongs in lib/evinser/evinser.js. Do not move that
logic into post-processing — Evinse is a separate enrichment command over an
existing BOM.
If you find yourself writing import { … } from "../../cli/index.js" in a lower
layer, stop and extract the function downward first.
Package URLs
Purls are built with @cdxgen/cdx-purl through the helpers in
lib/inventory/purl.js, which apply the registered per-type rules (namespace
requirements, permitted qualifiers, normalisation):
import { applyPurl, tryBuildPurl } from "../inventory/purl.js";
const purl = tryBuildPurl({
type: "npm",
namespace: "@scope",
name: "pkg",
version: "1.0.0",
});
// null when the coordinates cannot form a valid purl — drop the purl rather
// than emitting an invalid one.
applyPurl(component, purl, `library:${name}:${version}`);Never build a purl by string concatenation: it skips encoding and qualifier
validation, which is how pkg:generic/name#/abs/path and pkg:npm/test@ once
reached CI. Never invent a purl type that cdx-purl has no rules for — use
pkg:generic with a cdx:purl:proposedType property instead.
Hashes
An integrity string belongs in hashes[], never in a property. Set
_integrity on the package (sha512-<base64> for npm/ssri, sha256-<base64>
for Go sums) and processHashes converts it into a CycloneDX hashes[] entry
with the digest hex-encoded, so the same artefact hashes identically whichever
collector found it.
Custom properties
Every cdx: property must be described in docs/CUSTOM_PROPERTIES.md.
lib/customProperties.poku.js fails the build when a new namespace appears
without documentation.
Cryptographic assets and OS trust material
- Do not assign a purl to
type: "cryptographic-asset"components. cdxgen intentionally suppresses purls for cryptographic assets. - Use schema-valid
cryptoProperties.assetTypevalues only:certificatefor certificates such assecureboot_certificatesrelated-crypto-materialfor trusted key files, kernel keys, and similar key material
- Source-derived
assetType: "algorithm"components must carry a knowncryptoProperties.oid. If a detected algorithm cannot be mapped to an OID, skip it rather than emitting a validator-breaking component. - Current OS/container trust-material conventions:
- repository sources (
apt,ppa,yum) →type: "data"withcdx:os:repo:*properties - trusted key files →
type: "cryptographic-asset"withcryptoProperties.relatedCryptoMaterialProperties.type = "public-key" - repo-to-key trust relationships should be represented in
dependencieswhen the source file explicitly references a key (signed-by,gpgkey, etc.)
- repository sources (
- If you add new osquery- or rootfs-derived crypto inventory, validate it against
lib/validator/bomValidator.jsexpectations and the CycloneDX schema files underdata/.
Go Evinse and Golem property hygiene
- Preserve
cdx:golem:*as small strings: counts, booleans, enums, source locations, module paths, and comma-separated scope/category lists. - Preserve data-flow and crypto-flow evidence as categories, rule IDs, confidence/severity labels, taint kinds, source locations, and call-stack frames. Do not emit raw source values, key material, plaintext, ciphertext, HTTP parameter values, environment values, generated source contents, or full command lines.
- Do not emit raw
go:generatecommand strings, raw environment values, embedded file contents, generated source contents, or full command lines. - Prefer scope-aware policy signals.
cdx:golem:usageScopes=runtimeis a stronger release signal than test-only usage;cdx:golem:testOnly=trueis useful triage context but should not be treated as proof of no risk. - Prefer bounded defaults for data-flow in CI:
--deepor--with-data-flow --golem-dataflow cryptowith capped workers, capped--golem-max-procs, slice/trace limits, generated-file skipping, and tests skipped unless--golem-testsis required. - Keep BOM audit rules in
data/rules/golem-go.yamlaligned with emitted property names and document new rules indocs/BOM_AUDIT.md. - Keep
cdxipivots aligned with the analyst flow:.golemsummaryfor run context,.golemhotspotsfor risk review, and.golemcoveragefor evidence coverage.
HTTP requests
All outbound HTTP is done through cdxgenAgent, exported from lib/ecosystems/utils.js. It is a small undici-backed, got-compatible client created by createHttpClient() in lib/core/httpClient.js — it supports .get/.post/.put/.head, .extend(), responseType, throwHttpErrors, followRedirect, timeouts, and beforeRequest/afterResponse/beforeError hooks (which power dry-run enforcement, host allow-listing, network-activity recording, and HTTP trace logging). It also keeps an in-memory GET response cache for the run; CDXGEN_NO_CACHE and --no-cache turn off only the on-disk caches. The cache keys on the URL, the response type and a digest of the request headers, so responses fetched with different credentials never mix; pass cache: false for anything short-lived, such as a token exchange. A beforeNetwork hook runs only when a request misses the cache, which is how withHostRateLimit(url, issue, { deferGate: true }) in lib/inventory/fetchBatch.js keeps cached reads from waiting for a rate-limit slot. Read Maven POMs, jars and hashes through lib/inventory/jvmLocalRepos.js before going to a remote repository. Never talk to the network directly (raw undici, fetch, http, etc.) in new code — use cdxgenAgent, or pass it through the options object. The one exception is Docker/Podman daemon communication, which uses the unix-socket/TLS connection helper in lib/managers/dockerConnection.js.
Logging conventions
| Function | Purpose | Activation |
console.log / console.warn / console.error | Operational messages | Always |
thoughtLog(msg, args?) from lib/core/logger.js | Internal reasoning / debug thinking | CDXGEN_THINK_MODE=true or CDXGEN_DEBUG_MODE=verbose |
traceLog(type, args) from lib/core/logger.js | Structured trace of commands & HTTP | CDXGEN_TRACE_MODE=true or CDXGEN_DEBUG_MODE=verbose |
DEBUG_MODE constant from lib/ecosystems/utils.js | Guards verbose console.log calls | CDXGEN_DEBUG_MODE=debug or debug |
Prefer thoughtLog over ad-hoc console.log for introspective messages inside core logic so they can be silenced in production.
Security conventions
cdxgen has a secure mode (CDXGEN_SECURE_MODE=true or running under Node.js --permission). Guards:
import { isSecureMode } from "../helpers/utils.js";
if (isSecureMode) {
/* skip risky operation */
}Always use the safe wrappers rather than the raw Node.js equivalents:
| Safe wrapper | Replaces |
safeExistsSync(path) | existsSync(path) |
safeMkdirSync(path, opts) | mkdirSync(path, opts) |
safeSpawnSync(cmd, args, opts) | spawnSync(cmd, args, opts) |
safeSpawnSync also validates cmd against CDXGEN_ALLOWED_COMMANDS and records every invocation in commandsExecuted.
For user-supplied strings that will be used in file paths or URLs, check hasDangerousUnicode(str) and isValidDriveRoot(root) (Windows) before use.
Environment variables from auditEnvironment (lib/stages/pregen/envAudit.js) are checked at startup to detect dangerous NODE_OPTIONS values.
When adding or modifying external-facing features (SCM/network integrations like release notes, git metadata, repository lookups), treat all input values as untrusted by default:
- Validate git refs/tags/branches with
isSafeGitRefName()before using them in git revision/range arguments. - Prefer parsing helpers that normalize and filter unsafe refs before selection.
- Never pass user/remote-derived refs directly into
git log/gitrevision arguments without validation. - Use
hardenedGitCommand()(orsafeSpawnSyncwrappers where applicable) instead of raw process execution. - Use
cdxgenAgentfor outbound HTTP and source tokens fromoptions/environment without logging credentials.
BOM property-value hygiene
When emitting CycloneDX properties, annotations, evidence objects, or service/component metadata, treat every value as potentially secret-bearing unless it is already a small, enumerated, non-sensitive token.
- Never emit raw secrets or likely secret carriers into BOM fields, including:
- bearer tokens, API keys, passwords, client secrets, cookies, session IDs, private keys, signed URLs, or authorization headers
- raw environment variable values, command-line arguments, header values, or config blobs that may contain credentials
- free-form copied text from user/config-controlled sources when it could embed secrets
- Prefer booleans, counts, categories, and field names over raw values. For example:
credentialExposure=truecredentialIndicatorCount=3credentialExposureFieldCount=2credentialReferenceCount=1header:Authorizationas a field label is acceptable; the header value is not
- Treat URLs and URIs as untrusted. Before emitting them, remove or avoid:
- query strings and fragments
userinfo(https://user:pass@host/...)- signed-token parameters such as
token,sig,signature,X-Amz-Signature,X-Goog-Signature,access_token,id_token,client_secret,api_key, and similar aliases
- Treat command strings as untrusted. Do not emit full commands when arguments may contain credentials; prefer the executable name, transport type, or a redacted/summarized form instead.
- Treat free-text mirrored metadata as untrusted. Fields such as
cdx:agent:description,cdx:skill:metadata,cdx:agent:permission,cdx:crewai:*,cdx:mcp:description,cdx:mcp:resourceUri,cdx:mcp:configuredEndpoints,cdx:mcp:command, and futurecdx:mcp:auth:*values must be reviewed for secret-bearing content before being added. - If a value is useful for analysis but may contain credentials, emit a safe derivative instead (count, host, scheme, basename, allowlisted enum, or
"redacted"marker). - Add or update tests whenever new emitted properties are introduced to assert that secrets are not copied into BOM output.
Environment variables
All cdxgen-specific variables use the CDXGEN_ prefix (or a well-known
tool-specific name such as JAVA_HOME or PYTHON_CMD). docs/ENV.md lists
every supported variable.
Read them with readEnvironmentVariable from lib/core/activity.js, never
process.env directly — the helper records the read so dry-run mode can report
which variables a scan consulted:
import { readEnvironmentVariable } from "../core/activity.js";
const target = readEnvironmentVariable("BAZEL_TARGET") || "//...";Variables that gate behaviour globally are derived once into a module-level constant and imported, rather than re-read deep in a call stack:
export const DEBUG_MODE =
["debug", "verbose"].includes(readEnvironmentVariable("CDXGEN_DEBUG_MODE")) ||
readEnvironmentVariable("SCAN_DEBUG_MODE") === "debug";Adding support for a new language/ecosystem
- Add a
create<Language>Bom(path, options)function inlib/cli/index.js, following the same signature and return shape as the existing functions. - Add parser functions in
lib/ecosystems/utils.js(for lock file / manifest parsing) or a new helper module underlib/helpers/. - Register the new project type in
PROJECT_TYPE_ALIASESandPACKAGE_MANAGER_ALIASESinlib/ecosystems/utils.js. - Add a dispatch branch in
createXBom/createBominlib/cli/index.js. - Update
docs/PROJECT_TYPES.md. - Add fixture files to
test/and cover with a*.poku.jstest. - If updating OSQuery table metadata in
data/queries*.json(for examplepurlTypeorcomponentType), review all platform variants (queries.json,queries-win.json, andqueries-darwin.json) and keep shared table entries aligned. - Always consider adding/expanding
repotests.ymlcoverage with a representative public repository for the ecosystem change; if a stable public repo is not practical, add fixture-backed repo tests undertest/data/and exercise them fromrepotests.yml. - For container/rootfs or OBOM feature work, also review the companion integration surfaces that usually need to stay aligned:
lib/managers/binary.js,lib/managers/binary.poku.js,lib/managers/binary.e2e.poku.js,lib/stages/postgen/auditBom.poku.js,ci/dockertests.sh,ci/assertions.sh,data/component-tags.json,bin/repl.js, and any relevant docs/rules. - For CBOM source-analysis work, keep
lib/inventory/analyzer.js,lib/inventory/analyzer.poku.js,lib/inventory/cbomutils.js, and thecreateCryptoCertsBom()path inlib/cli/managedBom.jsaligned. The analyzer is intentionally lightweight, so prefer conservative constant propagation over broad speculative inference.
Testing
Framework: poku
Tests are co-located with the source as <module>.poku.js files. The test runner is poku.
lib/ecosystems/utils.poku.js ← tests for utils.js
lib/ecosystems/pythonutils.poku.js ← tests for pythonutils.js
lib/cli/index.poku.js ← tests for index.js
lib/stages/pregen/envAudit.poku.js
…Configuration is in .pokurc.jsonc:
{
"include": ["lib"],
"filter": ".poku.js",
"reporter": "verbose",
}Run all tests:
pnpm testWatch mode:
pnpm run watchCross-platform test expectations
- Treat every unit/integration test as cross-platform unless a test is explicitly platform-scoped.
- Always check string/path assertions against Windows and POSIX path separator differences (
\vs/). - Prefer
node:pathhelpers, normalization, or separator-agnostic assertions over hard-coded path literals in tests. - When adding or changing tests that inspect file paths, temp directories, command arguments, or serialized activity/log output, verify they still pass on Windows runners and do not assume
/tmp-style paths.
Container / OBOM regression coverage
- Unit coverage: use
lib/managers/binary.poku.jsfor rootfs/container parsing logic, repository-source parsing, trusted-key modeling, and osquery invocation behavior. - OBOM and container parity: the parity cases at the end of
lib/managers/binary.poku.jsput recorded trivy output and the osquery rows (or apk database) of the same images through both paths and require the same purl, bom-ref and version for every package. A change to how either side names an OS package must keep them passing, and support for a new distro should add a case. - Rule coverage: use
lib/stages/postgen/auditBom.poku.jswhen changingdata/rules/*.yaml,lib/inventory/auditCategories.js, or hardening-related query packs. - Analyzer coverage: use
lib/inventory/analyzer.poku.js,lib/inventory/cbomutils.poku.js, andlib/ecosystems/utils.poku.jswhen changing crypto-aware AST extraction, GTFOBins/LOLBAS enrichment, or osquery-to-component transforms. - Binary E2E coverage: use
lib/managers/binary.e2e.poku.jsfor real Trivy/rootfs integration when the local environment has the companion repo and container runtime available. - Docker-script parity checks: use
ci/dockertests.shplusci/assertions.shfor archive vs reconstructed-rootfs parity, tool identity evidence, container-risk audit coverage, unpackaged native-file count assertions, and OS repo/trusted-key crypto assertions. Thenerdctllane must keep working even when Docker itself is absent. - For macOS OBOM changes, validate the real bundled osquery behavior and keep
docs/OBOM_MACOS_TROUBLESHOOTING.mdin sync when execution mode or permissions expectations change.
Review feedback handling
- Before finalizing work, review feedback from automated code review or validation tools.
- If a review comment is valid, fix it in the same change rather than leaving it behind.
- If a review comment is not valid, document why it was not applied in the final summary.
- Thoroughness is preferred over speed when resolving valid review feedback.
Test anatomy
import { strict as assert } from "node:assert"; // or:
import { assert, describe, it, test } from "poku";
import { myFunction } from "./my-module.js";
describe("myFunction()", () => {
it("does X when Y", () => {
const result = myFunction(input);
assert.strictEqual(result, expected);
});
});- Use
assertanddescribe/it/testfrompoku(they re-export Node's assert plus test grouping). - Tests run with
CDXGEN_NO_CACHE=true, loaded fromtest/poku.env, so a stubbed registry answer never reaches this machine's on-disk metadata cache and no test is answered from it. A test of that cache unsets the variable and pointsCDXGEN_CACHE_DIRat a temporary directory. - For async tests, return the promise or use
async/awaitinsideit/test. - For tests that need to mock ES-module dependencies, use esmock + sinon:
import esmock from "esmock";
import sinon from "sinon";
// cdxgenAgent is built by createHttpClient(); mock that seam to inject a fake
// client, or stub cdxgenAgent.get/.post directly for simpler cases.
const agentStub = sinon.stub().returns({ json: sinon.stub().resolves({}) });
agentStub.get = sinon.stub().resolves({ statusCode: 200, body: {} });
const { submitBom } = await esmock("./index.js", {
"../helpers/httpClient.js": {
createHttpClient: sinon.stub().returns(agentStub),
},
});- Test files are excluded from the Biome linter (
"!test/**"inbiome.json), so slightly looser style is acceptable there, but still follow the same import conventions. - TypeScript generation (
pnpm run gen-types) excludes*.poku.jsfiles viatsconfig.json.
TypeScript types
Types are generated — do not write or edit files under types/ manually. Source JSDoc is the source of truth:
/**
* Parses a Cargo.lock file and returns a list of component objects.
*
* @param {string} cargoLockFile Path to Cargo.lock
* @param {Object} options CLI options
* @returns {Object[]} Array of component objects
*/
export function parseCargoData(cargoLockFile, options) { … }pnpm run gen-types finishes in a few seconds (it took about an hour until
#4555). A change that adds or changes exported functions, or their JSDoc, runs
it and commits the regenerated types/ in the same pull request; review the
types/ diff, since it shows how the change looks to library users. Never wire
it into a test or a golden: the test suite stays independent of how fresh
types/ is.
pnpm run gen-types
git diff --stat types/CI overview
| Workflow | Trigger | What it does |
nodejs.yml | PR / push to master | Unit tests (poku) on a matrix of Node versions × OS |
lint.yml | PR / push to master | pnpm run lint:check (Biome) |
repotests.yml | PR / push to master | Integration tests against real projects |
repotests-quick.yml | PR / merge-group | Quick tier of the repo tests; required status check |
snapshot-tests.yml | PR / push | Snapshot comparisons of generated BOMs |
codeql.yml | Push / schedule | CodeQL security analysis |
build-image.yml | PR / push | Docker image builds |
Node versions to test against are read from .versions/node_* files (not hardcoded). OS matrix: Ubuntu 22.04, Ubuntu 24.04, Windows, macOS (both x64 and ARM).
All GitHub Actions workflows pin action SHA digests and have permissions: {} at the job level (least-privilege).
Planning, issues and the project board
Work is tracked on the cdxgen roadmap, a GitHub project that holds issues. Its built-in workflows set Status from what happens to the issue and its pull request, and the maintainer sets Horizon, Priority and the milestone. The fields and rules are described in project/README.md and plans in plans/README.md, both in the organization's .github repository.
Start from an issue. If the task has none, put the proposed title and a short description at the top of the pull request description, and tell the maintainer. Do not open issues or pull requests from a subagent: the main session does that when the maintainer asks, and then labels the pull request with the ai-* level from CONTRIBUTING.md plus the type labels, and lts for a backport.
Write Closes #123 in the pull request description for the issue it resolves, and Refs #123 for a partial change or an epic. The board follows that link: an issue moves to In progress when a pull request that closes it is opened, and to Done when the pull request merges. GitHub records no closing link for a pull request that targets a branch other than the default, such as a backport to release/12.0.x, so name the issue there too, and expect the maintainer to close it.
Leave the planning fields to the maintainer. Do not create or assign milestones, set Horizon or Priority, add an issue to an epic, or edit the board with gh project or the GraphQL API unless the maintainer asks for that in the session. master carries the next release, which is the version in package.json. If a change belongs in that release, say so in the pull request description.
When you are blocked or a decision is the maintainer's to make, say so in the pull request description under a "Needs decision" or "Blocked by" heading, and in your final message to the maintainer. They apply the blocked and needs-decision labels. Do not guess and carry on.
Larger work gets a plan document and an epic, as described in the plans guide. Draft the plan locally and give it to the maintainer to publish. If the plan depends on test data that does not belong in git, list it in a corpus manifest with a SHA-256 digest, and refer to the data by that digest.
Crediting contributors
People outside the project report bugs, track down root causes, write reproducers and post sample code. When a change uses that work, credit them in the commit message. A thank-you in an issue comment reaches neither the git history nor the release notes.
Reported-by: Name <email>names the person who filed the bug report the change fixes.Helped-by: Name <email>names anyone whose idea, sample code, reproducer, fixtures, investigation or earlier pull request the change uses.
Follow each one with Link: and the URL of that issue, comment or pull request:
Reported-by: Jane Doe <12345678+janedoe@users.noreply.github.com>
Link: https://github.com/OWNER/REPO/issues/123
Helped-by: John Roe <87654321+johnroe@users.noreply.github.com>
Link: https://github.com/OWNER/REPO/issues/123#issuecomment-456- Take the name from the person's GitHub profile. Use their noreply address,
<id>+<login>@users.noreply.github.com(gh api users/<login> --jq .idprints the id), unless they asked for a different address. - Put the trailers in every commit that uses the work, and repeat them under
## Creditsin the pull request description. A merge commit keeps only the pull request title, so the description alone does not reach the history. - Do not use these trailers for bots, AI tools or yourself.
Dependency management
- Package manager: pnpm ≥ 10 (
packageManagerfield inpackage.json). - Install:
pnpm install --config.strict-dep-builds=true --frozen-lockfile --package-import-method copy - Do not use
npmoryarn. - Runtime dependencies are in
dependencies; test/dev tools indevDependencies; optional heavy packages (atom, protobuf, server middleware) inoptionalDependencies. - Dependency updates are managed by Renovate (see
renovate.json). Do not bump dependency versions in PRs unless directly required.
What to avoid
- Do not talk to the network directly (raw
undici,fetch,http/https) in new library code — usecdxgenAgentfromlib/ecosystems/utils.js(orlib/managers/dockerConnection.jsfor the container daemon). - Do not use
spawnSync/execSyncdirectly — usesafeSpawnSync. - Do not use
existsSync/mkdirSyncdirectly — usesafeExistsSync/safeMkdirSync. - Do not shell out to the Electron
asarCLI or add a runtime dependency for ASAR parsing — use the native reader inlib/ecosystems/asarutils.js. - Do not construct PURL strings by concatenation — use
new PackageURL(…).toString(). - Do not read
process.argvinside library modules — accept options via theoptionsobject. - Do not commit secrets, tokens, or credentials.
- Do not copy raw secret-bearing values into emitted BOM properties, annotations, evidence, endpoints, or service metadata; aggregate, classify, or redact them instead.
- Do not modify generated files under
types/directly. - Do not add
console.logdebug statements to production code without gating them onDEBUG_MODEor replacing them withthoughtLog. - Do not add or update
pnpm-lock.yamlunless changingpackage.jsondependencies. - Do not import from
lib/cli/index.jsinsidelib/helpers/*orlib/stages/*— this creates a circular-like cross-layer dependency. Extract the shared function tolib/helpers/instead. - Do not add logic that must execute once-per-BOM inside
buildBomNSData— it is called once per language type. UsepostProcessinlib/stages/postgen/postgen.jsinstead. - Do not add any generic functions to
lib/cli/index.jsandlib/ecosystems/utils.js. - Do not add complex all-in-one regex parsers for filenames or other externally sourced strings when tokenization plus small validators will do; that pattern is difficult to maintain and may fail CodeQL inefficient-regex checks.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

