Metadata-Version: 2.4
Name: ecz-id-sbom
Version: 0.1.0
Summary: Inspects software bills of materials for ECZ-ID configuration references.
Project-URL: Documentation, https://developers.ecocitizenz.com
Project-URL: Machine Interface, https://machine.ecocitizenz.org/.well-known/ecz-machine.json
Project-URL: Resolver, https://resolver.ecocitizenz.org
Project-URL: Operator Setup, https://trustops.ecocitizenz.com/start
Project-URL: Developer Guidance, https://developers.ecocitizenz.com
Author-email: Ecocitizenz <ecocitizenz@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: ecz-id
Description-Content-Type: text/markdown

# 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:

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

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

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

## Example result

```text
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:

```console
$ 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

```console
$ 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.

```console
$ 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` &nbsp;|&nbsp; Import: `ecz_id_sbom` &nbsp;|&nbsp; Plugin group: `ecz_id.plugins`
