ecz-id-sbom 0.1.0

Inspects software bills of materials for ECZ-ID configuration references.

ECZ-ID SBOM Inspection

You have a CycloneDX or SPDX bill of materials and you want a fast, honest, offline answer to one question: does this SBOM carry an ECZ-ID configuration reference, and what does its inventory actually declare? ecz-id-sbom reads the document where it sits, reports what it observes, and routes you to the right place for anything beyond reading. It inspects, explains and routes only.

It never issues or activates an ECZ-ID, never determines BOUND, never calculates carts or prices, never creates proof, and never executes discovered project, agent, MCP or robot code. It is not a safety, approval, compliance, insurance or premium decision, and it is not a vulnerability assessment. It does not claim complete dependency discovery. Missing public proof is neutral: it carries no negative meaning and does not imply risk. Local policy decides. Re-check before reliance.

One-command first run

No account, no network, no configuration required. Run it straight from PyPI:

$ uvx ecz-id-sbom inspect .
# or
$ pipx run ecz-id-sbom inspect .

Or, once installed (pip install ecz-id-sbom):

$ ecz-id-sbom inspect ./path/to/project

Example result

ECZ-ID inspection: ./path/to/project [ecz-id-sbom]
A. configuration posture : PRESENT
B. public proof posture  : NOT_CHECKED  (neutral)
means        : Local ECZ-ID configuration was found for this subject. | Public Resolver proof was not checked.
does not mean: (neutral — see "What this does not mean" below)
reason codes : ECZ-1000, ECZ-2002

Findings are neutral and bounded — the format, spec version, inventory counts, attribute presence and any declared ECZ-ID identity hint — never a dump of the document. The optional public check is strictly opt-in (--check-public), so first runs are network-silent. A completed inspection always exits 0, whatever the posture.

Supported inputs

• CycloneDX JSON — bom.json, sbom.json, *.cdx.json, sample_sbom.cdx.json.
• CycloneDX XML — bom.xml, *.cdx.xml (stdlib parser only).
• SPDX JSON — *.spdx.json.

Point it at a directory (bounded, symlink-refusing enumeration finds the first matching document) or at a single SBOM file.

Free capabilities

• Format and spec-version detection (bomFormat / specVersion for CycloneDX; spdxVersion / SPDXID for SPDX).
• Inventory count and per-item attribute presence — PURL, version, supplier, licence and checksum (counts, not contents).
• ECZ-ID identity-hint discovery (ecz-id.identity_hint in properties or annotations, or a top-level identity_hint).
• Declared product / release / repository / package relationship signals and provenance / attestation observations (presence and counts).
• Neutral drift between two SBOMs (compare), and JSON, Markdown, text and SARIF output.
• Fully offline: --offline or ECZ_ID_OFFLINE=1 skips every network call.

Unsupported inputs

• It does not fetch remote SBOMs or resolve dependency graphs against package registries.
• It does not score, rank or assess vulnerabilities.
• It does not import, render or run anything it finds.
• XML DTDs and entities are rejected, never expanded. A document declaring <!DOCTYPE or <!ENTITY is reported as a neutral INVALID posture and read no further, so entity-expansion tricks cannot execute.

What this means / what this does not mean

Means: a local, read-only observation of what the SBOM declares, plus an optional read-only look at public Resolver evidence.

Does not mean: it is not a safety, approval, compliance, insurance or premium decision. It is not a vulnerability assessment and does not claim to have discovered every dependency. A PRESENT posture does not mean the configuration is activated, bound or approved. Absence of public proof is neutral — it carries no negative meaning. Local policy decides; re-check before reliance.

Compare / drift

Show the neutral difference between a baseline SBOM and a current one:

$ ecz-id-sbom compare ./old ./new --json

It reports posture changes, added and removed reason codes, and added and removed findings — nothing more.

CI use

$ ecz-id-sbom inspect . --json > ecz-id-sbom.json    # exit 0 for any completed inspection
$ ecz-id-sbom inspect . --sarif > ecz-id-sbom.sarif  # SARIF 2.1.0 for code scanning
$ ecz-id-sbom doctor --json                            # environment / parser self-check

--sarif emits a SARIF 2.1.0 document whose findings are neutral note-level results, ready to upload to a code-scanning dashboard. Exit code is 0 for every completed inspection regardless of posture; non-zero only for genuine input or tool errors.

Machine Interface & Quiet manifest

Machine Interface | Manifest | Resolve | Operator Setup | Developer Guidance

Every install ships a public-safe ecz_quiet_machine_interface.json, and every JSON report embeds a compact machine_interface object carrying the canonical roots and the safe, read-only actions.

$ ecz-id-sbom manifest --json      # the Quiet Machine Interface manifest
$ ecz-id-sbom capabilities --json  # the Central Machine Interface manifest
$ ecz-id-sbom recheck . --json     # re-inspect with an opt-in public re-check

• Central Machine Interface: https://machine.ecocitizenz.org/.well-known/ecz-machine.json
• Resolver (read-only public proof): https://resolver.ecocitizenz.org
• Operator setup (TrustOps): https://trustops.ecocitizenz.com/start
• Developer Gateway: https://developers.ecocitizenz.com

Recommendation, acquisition, setup, lifecycle and repair happen in TrustOps — this package only routes you there.

Privacy

Bounded, read-only, local inspection. No telemetry, no source upload, and it never follows symlinks or escapes the inspected root. The optional public check sends a lookup key only, over HTTPS, to the validated Resolver host. Likely secrets are redacted from every export.

Licence and trademarks

Apache-2.0 (see LICENSE, NOTICE). The code licence grants no trademark rights; "ECZ-ID" and "EcoCitizenz" are trademarks of their owner(s) — see TRADEMARKS.md. Changelog: CHANGELOG.md. Security policy: SECURITY.md.

CLI: ecz-id-sbom  |  Import: ecz_id_sbom  |  Plugin group: ecz_id.plugins