agentleFS
CycloneDXCycloneDX/cdxgen/SKILL.md

SKILL.md

Skill1.1k starsChanged 14 days agoApache-2.0View on GitHub

cdxgen is a universal, polyglot CLI tool that generates valid CycloneDX Bill-of-Materials (BOM) documents in JSON format. It produces SBOM, HBOM, CBOM, OBOM, SaaSBOM, VDR, and CDXA outputs for source code, containers, VMs, live operating systems, and supported hardware hosts. Supports CycloneDX spec versions 1.6–2.0 (default: 1.7, with HBOM currently targeting 1.7; 1.4/1.5 are rejected as generation targets). 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…

  • Reads credentials
  • Installs packages

200 other projects use a version of this.

Trending

Quiet this year.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the CycloneDX/cdxgen repository that our weekly crawl found. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about CycloneDX/cdxgen

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

35 more on GitHub

Used with

Projects with it also use crypto-intelligence, heart and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Arcanea-LabsSkill

    crypto-intelligence

    Vertical-tier skill for Crypto Intelligence Domain Sub-Stack. Auto-activates inside verticals/crypto-intelligence/ or on /crypto-* commands. Enforces R5 non-advisory clause, voice (architect), refusal patterns, composition with Wealth IS umbrella per Board 2026-05-17. Loads verticals/crypto-intelligence/SKILL.md wrapper for full doctrine.

    Also in 3 projects that use this

  • Arcanea-LabsSkill

    heart

    Ops health monitor for the machine substrate. Checks Memory Bus, brain_watchdog, Voice Operator, dashboard, audit-log freshness, and scheduled tasks. Cross-cutting skill that any repo can invoke when daemons feel off or before starting a heavy work session.

    Also in 3 projects that use this

  • +10 more from Arcanea-Labs

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. 0 are common, 1 is distinctive, and 19 are very specific to this project.

  • 0

    Common

    Most of the 116 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 19

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All boolean flags accept --no- prefix to invert behavior

    line 42
  2. Very specific:

    Use the bundled cdx-audit command when the user already has one or more CycloneDX JSON BOMs and wants forward-looking supply-chain exposure …

    line 134
  3. Very specific:

    Use --workspace-dir to reuse cloned repositories and cached child SBOMs across runs

    line 146
  4. Very specific:

    Use --reports-dir to persist per-target artifacts plus an aggregate JSON report

    line 147
  5. Very specific:

    Start with --scope required --max-targets 25 for large BOMs or triage-first workflows.

    line 170
  6. Very specific:

    Use --include-trusted only when the user explicitly wants a broader baseline that includes packages already carrying trusted publishing …

    line 171
  7. Very specific:

    Use --only-trusted only when the user wants to inspect just that subset.

    line 172
  8. Very specific:

    Never pass --include-trusted together with --only-trusted.

    line 173
  9. Very specific:

    Use --workspace-dir when the user expects repeated runs or iterative analysis.

    line 174
  10. Very specific:

    Use cdxgen --bom-audit: when the user wants findings embedded during BOM generation.

    line 191
  11. Very specific:

    Use cdx-audit for Cargo/Rust BOMs too: when the BOM contains pkg:cargo/...

    line 192
  12. Very specific:

    ALWAYS: use absolute paths for [path] and -o.

    line 203
  13. Very specific:

    NEVER: run as root when CDXGEN_SECURE_MODE=true.

    line 204
  14. Very specific:

    When using server mode or BOM upload features, keep CDXGEN_ALLOWED_HOSTS and related host allowlists narrow.

    line 212
  15. Very specific:

    When reviewing generated BOMs that include AI/MCP inventory or Chrome extension metadata, still inspect emitted properties before sharing …

    line 213
  16. Very specific:

    Default behavior automatically validates against spec (--no-validate to skip)

    line 224
  17. Very specific:

    Run cdxgen with --dry-run first.

    line 248
  18. Very specific:

    Prefer --activity-report json or --activity-report jsonl so the pending reads, blocked writes, blocked command execution, blocked network …

    line 249
  19. Very specific:

    Ask for permission before rerunning without --dry-run.

    line 251
  20. Distinctive:

    Only perform real execution after the user explicitly approves it.

    line 252

“Common” is measured: kept by at least 6 in 10 of the 116 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: OWASP cdxgen (CycloneDX BOM Generator)

Description

cdxgen is a universal, polyglot CLI tool that generates valid CycloneDX Bill-of-Materials (BOM) documents in JSON format. It produces SBOM, HBOM, CBOM, OBOM, SaaSBOM, VDR, and CDXA outputs for source code, containers, VMs, live operating systems, and supported hardware hosts. Supports CycloneDX spec versions 1.6–2.0 (default: 1.7, with HBOM currently targeting 1.7; 1.4/1.5 are rejected as generation targets). 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). When the optional companion binaries from @cdxgen/cdxgen-plugins-bin are available, cdxgen also enriches container/rootfs and live-OS scans with Trivy/osquery-powered metadata, Linux GTFOBins runtime context, platform trust posture, and Go Evinse evidence through the golem helper. HBOM collection is dynamically provided by the optional @cdxgen/cdx-hbom library on supported darwin/arm64, linux/amd64, linux/arm64, windows/amd64, and windows/arm64 hosts. CBOM mode can also extract cryptographic algorithm inventory from JavaScript and TypeScript source through lightweight AST analysis.

✅ When to Invoke

  • User requests an SBOM/BOM for a repository, directory, container image, or live OS.
  • User requests a hardware BOM / HBOM for the current host.
  • User needs dependency inventory, license resolution, or vulnerability triage context.
  • User wants to export to Dependency-Track, sign/validate a BOM, convert CycloneDX JSON to SPDX JSON-LD, or generate evidence/callstacks.
  • User wants a predictive audit of an existing CycloneDX BOM with cdx-audit, especially for npm or PyPI package compromise posture.
  • User wants Go dependency evidence, usage scopes, call graph context, data-flow/crypto-flow evidence, local replacement review, vendoring/license evidence, crypto components, or security-sensitive API signals from evinse -l go with Golem.

📦 Prerequisites & Installation

RequirementDetail
RuntimeNode.js ≥ 24
JavaNot required on most platforms: atom ships as a native binary on linux-amd64, linux-arm64 (glibc), linux-amd64-musl, darwin-arm64, and windows-amd64. Only the jar-based triples (darwin-amd64, windows-arm64, linux-arm64-musl) need Java ≥ 23, where older versions fail silently or produce incomplete BOMs.
Installnpm i -g @cdxgen/cdxgen or pnpm dlx @cdxgen/cdxgen
Containerdocker run --rm -v $(pwd):/app:rw -t ghcr.io/cdxgen/cdxgen:master /app

Notes:

  • The optional @cdxgen/cdxgen-plugins-bin packages provide native helpers such as Trivy and osquery.
  • The same plugin package also provides golem for Go Evinse semantic evidence when a platform binary is available.
  • Container and rootfs scans can surface repository source components plus trusted-key cryptographic assets when those binaries are present.
  • Container and rootfs scans also emit cdx:container:unpackagedExecutableCount and cdx:container:unpackagedSharedLibraryCount metadata properties so agents can spot native file inventory that was not traced to OS package ownership.
  • Linux live-OS profiles include hardening-oriented sysctl_hardening and mount_hardening snapshots plus GTFOBins enrichment on privileged and network-active runtime rows.
  • The optional trustinspector helper adds macOS code-signing/notarization and Windows Authenticode/WDAC properties across large host inventories without truncating path inspection after the first few hundred paths.
  • macOS live-OS OBOM collection uses the bundled osquery binary in shell mode and may still require Full Disk Access or elevated privileges for some tables.

💻 Core Syntax

cdxgen [path] [options]
  • path defaults to . (current directory)
  • All boolean flags accept --no- prefix to invert behavior
  • Config precedence: CLI args > CDXGEN_* env vars > .cdxgenrc/.cdxgen.json/.cdxgen.yml/.cdxgen.yaml

🔑 Key Parameters & Profiles

CategoryFlagPurpose
Scope-t, --type <type>Language/platform (auto-detected if omitted). Pass multiple: -t java -t js
-r, --recurseScan mono-repos (default: true). Use --no-recurse to disable
--deepEnable deep parsing (C/C++, OS, OCI, live systems)
Output-o, --output <file>Destination path (default: bom.json)
-p, --printPrint human-readable table/tree to stdout
--dry-runRead-only preview mode. Record reads plus blocked writes, commands, temp dirs, network, and submissions before any real execution
--activity-report <fmt>Hidden machine-readable dry-run/debug report: json or jsonl
--spec-version <ver>CycloneDX generation target: 1.6, 1.7 (default), 2.0. 1.4 and 1.5 are rejected; downgrade an existing document with cdx-convert --to instead
Profiles--profile <name>generic (default), appsec, research, operational, threat-modeling, license-compliance, ml/machine-learning, ml-deep/deep-learning, ml-tiny, introspect
Lifecycles--lifecycle <phase>pre-build (no installs), build (default), post-build (binaries/containers)
Filtering--required-onlyInclude only production/non-dev dependencies
--filter <purl>Exclude components matching string in purl/properties
--only <purl>Include ONLY components matching string in purl
Advanced--evidenceGenerate SaaSBOM with usage/callstack evidence
--include-cryptoInclude CBOM-oriented cryptographic assets, certificates, and source-derived crypto algorithms
--include-formulationAdd git metadata & build tool versions
--serverStart HTTP server on 127.0.0.1:9090
--validateAuto-validate BOM against JSON schema (default: true)
--generate-key-and-signGenerate RSA keys & sign BOM with JWS

📖 Common Workflows

# Basic auto-detect
cdxgen -o bom.json

# Multi-language mono-repo (disable recursion if not needed)
cdxgen -t java -t python --no-recurse -o bom.json

# Production-only dependencies
cdxgen --required-only -o bom.json

# Container/OCI image
cdxgen -t docker myimage:latest -o bom.json

# Reconstructed or mounted root filesystem
cdxgen /absolute/path/to/rootfs -t rootfs -o bom.json

# Offline rootfs hardening review
cdxgen /absolute/path/to/rootfs -t rootfs -o bom.json --bom-audit --bom-audit-categories rootfs-hardening

# Research/Security deep scan with evidence
cdxgen --profile research --evidence -o bom.json

# Live macOS/Linux/Windows operating-system inventory (OBOM)
obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime

# Live hardware inventory (HBOM)
hbom -o hbom.json

# Dynamic trace process execution SBOM
tracebom --cmd "node app.js" -o bom.json

# Catalog a packaged Electron ASAR archive
cdxgen -t asar --bom-audit --bom-audit-categories asar-archive -o bom.json /absolute/path/to/app.asar

# Pre-build scan (no package installations)
cdxgen --lifecycle pre-build -o bom.json

# Agent-safe dry-run preview before any real execution
cdxgen /absolute/path/to/project --dry-run --activity-report json

# Compact line-oriented dry-run preview for automation
cdxgen /absolute/path/to/project --dry-run --activity-report jsonl

# Start SBOM server
cdxgen --server --server-host 0.0.0.0 --server-port 8080

# Predictive audit of an existing BOM
cdx-audit --bom bom.json

# Go Evinse with Golem semantic evidence
cdxgen -t go -o bom.json /absolute/path/to/go/project
evinse -i bom.json -o bom.evinse.json -l go --golem-callgraph static /absolute/path/to/go/project
cdx-audit --bom bom.evinse.json --direct-bom-audit --categories golem

# Go Evinse crypto-flow evidence with bounded data-flow analysis
evinse -i bom.json -o bom.evinse.crypto.json -l go --with-data-flow --golem-dataflow crypto --golem-dataflow-pattern-packs crypto /absolute/path/to/go/project

# Machine-readable predictive audit
cdx-audit --bom bom.json --report sarif --report-file audit.sarif

🔎 Predictive Audit Command (cdx-audit)

Use the bundled cdx-audit command when the user already has one or more CycloneDX JSON BOMs and wants forward-looking supply-chain exposure analysis rather than BOM generation.

cdx-audit --bom /absolute/path/to/bom.json --report console
cdx-audit --bom-dir /absolute/path/to/boms --report json --report-file audit-report.json
cdx-audit --bom /absolute/path/to/bom.json --report sarif --report-file audit.sarif
  • Entry point in source: bin/audit.js (published command name remains cdx-audit)
  • Supported ecosystems today: npm and PyPI package URLs extracted from existing BOM components
  • Reporters: console, json, sarif
  • Exit code 3 indicates at least one audited target met or exceeded --fail-severity
  • Use --workspace-dir to reuse cloned repositories and cached child SBOMs across runs
  • Use --reports-dir to persist per-target artifacts plus an aggregate JSON report

Best-practice command patterns for agents

# Fast default review queue
cdx-audit --bom /absolute/path/to/bom.json --scope required --max-targets 25

# Broaden the queue to include trusted-publishing-backed packages
cdx-audit --bom /absolute/path/to/bom.json --scope required --include-trusted --max-targets 50

# Isolate the trusted-publishing-backed subset
cdx-audit --bom /absolute/path/to/bom.json --only-trusted

# Capture machine-readable output for code-scanning or follow-up automation
cdx-audit --bom /absolute/path/to/bom.json --report sarif --report-file /absolute/path/to/audit.sarif

# Show lightweight score/rationale summaries per package
CDXGEN_THINK_MODE=true cdx-audit --bom /absolute/path/to/bom.json --scope required --max-targets 10

How agents should choose filters

  • Start with --scope required --max-targets 25 for large BOMs or triage-first workflows.
  • Use --include-trusted only when the user explicitly wants a broader baseline that includes packages already carrying trusted publishing metadata.
  • Use --only-trusted only when the user wants to inspect just that subset.
  • Never pass --include-trusted together with --only-trusted.
  • Use --workspace-dir when the user expects repeated runs or iterative analysis.

Prioritization indicators agents should understand

cdx-audit queue order is explainable. When the queue is trimmed, it currently prioritizes:

  1. direct runtime dependencies
  2. explicit CycloneDX scope=required
  3. stronger source evidence via evidence.occurrences
  4. non-development packages ahead of development-only packages
  5. non-platform-specific packages ahead of platform-constrained packages

These indicators affect which packages are audited first, not the final severity. Final severity still comes from the child SBOM findings plus conservative corroboration logic.

When agents should and should not use cdx-audit

  • Use cdx-audit for existing CycloneDX BOMs where the user wants prioritization, upstream review guidance, or SARIF/JSON output.
  • Use cdxgen --bom-audit when the user wants findings embedded during BOM generation.
  • Use cdx-audit for Cargo/Rust BOMs too when the BOM contains pkg:cargo/... dependencies and the goal is upstream review prioritization.
  • For Cargo-focused work, combine predictive cdx-audit triage with normal BOM generation and --bom-audit rules so registry, workspace, and native-build signals are all visible.
  • For container/rootfs scans, expect cdxgen to include non-package operational inventory too, such as package-owned files, installed commands, repository source records, and trusted key material when present.
  • For container/rootfs review in cdxi, use .unpackagedbins and .unpackagedlibs to isolate executable and shared-library file components that sit outside OS package ownership.
  • For live Linux OBOM work, also expect GTFOBins properties on selected osquery-derived runtime artifacts and hardening-oriented findings from sysctl_hardening and mount_hardening.
  • For CBOM review in cdxi, use .sourcecryptos when you want just the JavaScript or TypeScript source-derived algorithm components rather than the full cryptographic asset list.
  • For Go Evinse review in cdxi, use .golemsummary, .golemhotspots, and .golemcoverage before drilling into .occurrences, .callstack, or .inspect <component>. For crypto-flow review, prioritize components with cdx:golem:cryptoDataFlow=true, cdx:golem:cryptoDataFlowCount, and rendered cryptographic-asset algorithms.

⛔ Anti-Hallucination & Safety Constraints

  1. cdxgen outputs CycloneDX JSON by default and can export SPDX JSON-LD via --format spdx; use cdx-convert for dedicated CycloneDX-to-SPDX conversion of existing BOM files.
  2. ALWAYS use absolute paths for [path] and -o. Relative paths or paths with spaces cause external tool failures.
  3. NEVER run as root when CDXGEN_SECURE_MODE=true. Node.js permissions will reject wildcard FS/child grants.
  4. DO NOT auto-invoke --install-deps (default: true) in CI, containers, or air-gapped environments. Use --no-install-deps or --lifecycle pre-build.
  5. Java is only needed on jar-based atom platforms. C/C++, Python, and CBOM source analysis uses the atom companion, which ships as a native binary (no JDK) on linux-amd64, linux-arm64 (glibc), linux-amd64-musl, darwin-arm64, and windows-amd64. On darwin-amd64, windows-arm64, and linux-arm64-musl it runs on the JVM and requires Java ≥ 23; older versions cause silent freezes.
  6. NEVER construct PackageURL (purl) strings manually in prompts or scripts. Let cdxgen handle resolution.
  7. Secure Mode (CDXGEN_SECURE_MODE=true) requires explicit Node.js --permission flags. Do not grant --allow-fs-read="*" or --allow-fs-write="*".
  8. Environment Variables: a CLI option can be set as CDXGEN_ plus the option name (e.g., CDXGEN_TYPE=java). Settings that are not CLI options keep their own names with no prefix (e.g., FETCH_LICENSE=true); see docs/ENV.md.
  9. ALWAYS run --dry-run first for agent-driven workflows. Review the activity summary, prefer --activity-report json or jsonl for machine-readable inspection, and ask the user for permission before rerunning without --dry-run.
  10. DO NOT mix hbom / hardware with software project types such as js, java, python, os, or oci in the same run. Generate HBOM separately.
  11. When using server mode or BOM upload features, keep CDXGEN_ALLOWED_HOSTS and related host allowlists narrow. Prefer exact hosts; server-side Dependency-Track submission interprets wildcard entries as real subdomains only (for example, *.example.com), not suffix matches.
  12. When reviewing generated BOMs that include AI/MCP inventory or Chrome extension metadata, still inspect emitted properties before sharing externally even though cdxgen now redacts common secret-bearing URL and token patterns.
  13. For packaged Electron releases, prefer -t asar so archive file inventory, integrity verification, and embedded Node manifest analysis are included in the BOM and BOM-audit output.
  14. For OS trust inventory, remember the modeling split: repository sources are normal data components, while trusted keys/certificates are cryptographic-asset components. Do not assume those crypto assets have purls.
  15. On macOS OBOM runs, use the troubleshooting guide if tables come back empty or permission-gated; shell-mode osquery execution avoids the older /var/osquery startup failure mode.
  16. For offline host or golden-image reviews, prefer --bom-audit --bom-audit-categories rootfs-hardening so repository trust, privileged helpers, and service drift are checked without requiring live osquery collection.
  17. Source-derived algorithm components must stay validator-safe. Emit only algorithms that can be mapped to a known OID.
  18. For Go Evinse/Golem evidence, do not expose raw go:generate commands, raw environment values, HTTP parameter values, raw key material, plaintext, ciphertext, embedded file contents, generated source contents, or secrets. Use the emitted cdx:golem:* counts, categories, rule IDs, taint kinds, scopes, call-stack frames, crypto algorithm/OID pivots, and module facts for review.

📤 Output & Validation

  • Primary output: Valid CycloneDX JSON at -o path
  • Default behavior automatically validates against spec (--no-validate to skip)
  • Exit code 0 = success & validation passed. Non-zero = parse/validation/execution failure
  • Protobuf export: --export-proto --proto-bin-file bom.cdx
  • Namespace mapping: Auto-generates <output>.map if class resolution enabled (--resolve-class)

🤖 Agent Execution Guidelines

ScenarioRecommended Action
Command fails silentlyCheck missing build tools, atom availability (native binary on most platforms; Java ≥ 23 only on darwin-amd64, windows-arm64, linux-arm64-musl), or secure mode restrictions. Suggest container image or --no-install-deps.
Network/registry timeoutsSet HTTP_PROXY/HTTPS_PROXY; cdxgen's HTTP client honors them automatically. Do not auto-retry without user confirmation.
Large mono-reposUse --no-recurse + explicit -t <lang> or --exclude-type to limit scope.
Server mode invocationPoll /health first. POST to /sbom with JSON body or query params. Pass GITHUB_TOKEN via env if scanning private repos.
Aliasesobom = cdxgen -t os<br>cbom = cdxgen --include-crypto --evidence --deep (spec version defaults to 1.7). cbom rejects --component-type and -t os; use obom for OS inventory
HBOMhbom is the dedicated host-hardware command. Equivalent library path: cdxgen -t hbom. Do not mix it with other project types.
Output parsingUse -p for human-readable tables. Parse JSON at -o path programmatically. Never assume stdout contains the BOM unless -o is omitted.
Signature verificationUse bundled cdx-verify -i bom.json --public-key public.key.
SBOM signingUse bundled cdx-sign -i bom.json -k private.key.
Predictive auditingUse bundled cdx-audit --bom bom.json for existing BOMs. Prefer --report sarif --report-file audit.sarif for code-scanning uploads.
OBOM troubleshootingFor macOS permission/startup quirks, check docs/OBOM_MACOS_TROUBLESHOOTING.md; for live-host triage patterns, use docs/OBOM_LESSONS.md.
Go data-flow reviewUse evinse -l go --deep or --with-data-flow --golem-dataflow crypto for Golem data-flow. Keep worker/proc/slice limits bounded for CI and inspect cdx:golem:dataFlow* / cdx:golem:cryptoDataFlow* properties.

Dry-run-first workflow for agents

  1. Run cdxgen with --dry-run first.
  2. Prefer --activity-report json or --activity-report jsonl so the pending reads, blocked writes, blocked command execution, blocked network access, and blocked submissions are easy to inspect.
  3. Summarize the planned actions for the user.
  4. Ask for permission before rerunning without --dry-run.
  5. Only perform real execution after the user explicitly approves it.

Fidelity-loop workflow for agents

When the goal is a more accurate SBOM rather than a first scan, follow the sbom-fidelity-loop skill at .agents/skills/sbom-fidelity-loop/SKILL.md: scan with --profile introspect, read the JSON fidelity report, apply its ranked remediations (asking before installs, never modifying the project), and re-scan until the fidelity tiers stop improving.

📚 Reference Links

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.