abom-cli 0.1.0__tar.gz

abom_cli-0.1.0/.env.example

@@ -0,0 +1,26 @@
+# Copy to .env and adjust. All keys are prefixed ABOM_ (see src/abom/config.py).
+
+ABOM_DATABASE_URL=postgresql+asyncpg://abom:abom@localhost:5432/abom
+ABOM_TEMPORAL_HOST=localhost:7233
+ABOM_TEMPORAL_NAMESPACE=default
+ABOM_TASK_QUEUE=abom-cli
+
+ABOM_S3_ENDPOINT=http://localhost:9000
+ABOM_S3_ACCESS_KEY=minioadmin
+ABOM_S3_SECRET_KEY=minioadmin
+ABOM_S3_BUCKET=abom-artifacts
+
+# Local, OpenAI-compatible model server (vLLM). Set MODEL_USE_MOCK=false to use it.
+ABOM_MODEL_BASE_URL=http://localhost:8001/v1
+ABOM_MODEL_NAME=local/qwen2.5-coder
+ABOM_MODEL_USE_MOCK=true
+
+# Auth: leave JWKS empty for dev mode (static token grants all roles).
+ABOM_OIDC_JWKS_URL=
+ABOM_OIDC_AUDIENCE=abom
+ABOM_DEV_STATIC_TOKEN=dev-token
+
+# Execution
+ABOM_SANDBOX_IMAGE=python:3.12-slim
+ABOM_WORKSPACE_ROOT=/tmp/abom-workspaces
+ABOM_GATE_TIMEOUT_SECONDS=600

abom_cli-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.env
+cli/demo/out/
+.DS_Store
+
+# build artifacts
+dist/
+build/
+*.egg-info/
+.abom/
+
+# abom scan output
+abom.json

abom_cli-0.1.0/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1 PYTHONPATH=/app/src
+
+COPY pyproject.toml ./
+RUN pip install --no-cache-dir -e "." || pip install --no-cache-dir \
+    fastapi "uvicorn[standard]" pydantic pydantic-settings "sqlalchemy[asyncio]" \
+    asyncpg alembic temporalio httpx boto3 "python-jose[cryptography]" typer
+
+COPY src ./src
+COPY scripts ./scripts
+
+EXPOSE 8000
+CMD ["uvicorn", "abom.api:app", "--host", "0.0.0.0", "--port", "8000"]

abom_cli-0.1.0/MVP_SPEC.md

@@ -0,0 +1,157 @@
+# ABOM — Step-1 MVP Specification
+
+*Build target for the lighthouse design partner. Detailed enough to scaffold from. Companion to the project docs (kept private) §7 and the project docs (kept private).*
+
+---
+
+## 1. Goal
+
+For **one real agent run, entirely inside the customer's boundary**, produce a
+signed **Agent Bill of Materials** and verify it:
+
+1. **Generate** — a signed **Composition Manifest** (what the agent is made of) and
+   a hash-chained **Action Provenance** chain (what it did).
+2. **Verify** — run **abom-verify** against policy and catch a real violation a raw
+   log would let ship silently (unapproved/shadow model, confidential-data egress,
+   missing approval, composition drift).
+3. **Prove** — show the provenance is tamper-evident: scrubbing a record breaks the
+   chain at the exact `seq`.
+
+Guiding constraint: *nothing leaves the boundary*. The ABOM format extends
+**CycloneDX ML-BOM**.
+
+---
+
+## 2. The workload
+
+An agent run (the MVP exercises a developer/document agent) whose actions —
+model calls, tool/egress calls, data access, gate results, approvals — are
+captured as Action Provenance and bound to a signed Composition Manifest.
+
+### Out of scope for MVP
+Full runtime auto-capture (eBPF/framework taps) · real ed25519/cosign signing
+(MVP uses an HMAC stand-in) · the persistent Notary registry · OPA/Rego (MVP uses
+a JSON policy) · web console · multi-tenancy · SIEM export · air-gap bundle.
+
+---
+
+## 3. The ABOM artifacts (the core)
+
+**Composition Manifest** — signed; `composition_sha256` is the join key.
+```json
+{ "abom":"0.1","extends":"CycloneDX ML-BOM","type":"CompositionManifest",
+  "agent":{"name":"…","version":"…","risk_class":"high (Annex III)"},
+  "components":[ {"type":"model","name":"…","weights_sha256":"…","egress":false},
+                 {"type":"tool","name":"http_fetch","allowed_endpoints":["…"]},
+                 {"type":"prompt","sha256":"…"},
+                 {"type":"dataSource","classification":"confidential"},
+                 {"type":"policy","engine":"OPA","sha256":"…"} ],
+  "controls":{"egress":"deny-by-default","hitl":"required-for-consequential","residency":"EU"},
+  "composition_sha256":"…","signature":{"alg":"…","value":"…"} }
+```
+
+**Action Provenance Record** — hash-chained (reuses the audit chain).
+```json
+{ "type":"ActionProvenance","run_id":"agent@ver","seq":1,
+  "data":{ "composition_sha256":"…","decision":"…",
+           "inputs":[…],"model_calls":[{"model":"…","tokens":…}],
+           "tools_invoked":[{"name":"…","endpoint":"…"}],
+           "data_touched":[{"classification":"confidential","egress":false}],
+           "policy_decisions":[{"rule":"approval_required","result":"required"}],
+           "approval":{"by":"…","decision":"approved"} },
+  "prev_hash":"…","hash":"…" }
+```
+
+Implemented in [src/abom/bom.py](src/abom/bom.py) (`build_composition`,
+`append_action`, `sign`/`verify_signature`) over the tamper-evident chain in
+[src/abom/audit.py](src/abom/audit.py).
+
+---
+
+## 4. abom-verify — policy checks
+
+`bom.verify_abom(composition, chain, policy)` → `{ok, findings[], actions}`. Rules:
+
+| Rule | Catches |
+|---|---|
+| `signature` | composition signature invalid |
+| `chain_integrity` | provenance mutated / scrubbed / reordered |
+| `composition_match` | an action references a different composition |
+| `model_allowlist` | a model not on the approved list was used |
+| `composition_drift` | a runtime model not in the signed manifest (shadow model) |
+| `residency` | confidential/restricted data egressed |
+| `egress_allowlist` | egress to an unapproved endpoint |
+| `approval_coverage` | a consequential action without approval |
+
+Phase-2 swaps the JSON policy for OPA/Rego behind the same interface.
+
+---
+
+## 5. Tech stack & substrate
+
+Where ABOMs are captured: the agent runs through the control-plane substrate so
+every action is observable. (Capture completeness is the product's hardest
+property — see the project docs (kept private) §3.2.)
+
+| Concern | Choice |
+|---|---|
+| Language | Python 3.12 |
+| API | FastAPI + Pydantic v2 |
+| Orchestration | Temporal (`temporalio`) |
+| DB / ORM | PostgreSQL 16 + SQLAlchemy 2.0 (async) |
+| Object store | MinIO (S3) |
+| Model serving | vLLM (OpenAI-compatible); `MockModelClient` for laptops |
+| Policy | JSON (MVP) → OPA/Rego |
+| Signing | HMAC stand-in (MVP) → ed25519 / cosign |
+| Deploy | Helm stub (`charts/abom`), any Kubernetes |
+
+---
+
+## 6. API surface (MVP)
+
+Bearer token; `roles` claim drives RBAC (`developer`, `operator`, `auditor`).
+
+| Method | Path | Role | Purpose |
+|---|---|---|---|
+| GET | `/healthz` `/readyz` | — | liveness / readiness |
+| POST | `/v1/runs` | developer | start an instrumented agent run |
+| GET | `/v1/runs/{id}/abom` | auditor | the run's Composition Manifest + Action Provenance |
+| GET | `/v1/abom/verify?run_id=` | auditor | run abom-verify → findings |
+| GET | `/v1/abom/chain/verify?run_id=` | auditor | recompute the provenance hash chain |
+| POST | `/v1/runs/{id}/approve` | operator | approve a consequential action |
+
+---
+
+## 7. Definition of done
+
+1. A run completes against a **local** model only — zero external egress, verifiable.
+2. The run emits a **signed Composition Manifest** and a **hash-chained Action Provenance** chain.
+3. **abom-verify** returns **clean** for a compliant run and **≥3 findings** for a violating run (shadow model + confidential egress + missing approval).
+4. Tampering with any provenance record makes `verify_abom` report a `chain_integrity` finding at the broken `seq`.
+5. RBAC enforced: `auditor` cannot start runs; `developer` cannot approve.
+6. `make demo` runs the generate → verify → tamper scenario with no infrastructure.
+
+The demo ([demo/demo.py](demo/demo.py)) already satisfies criteria 2–4 and 6.
+
+---
+
+## 8. Milestones (≈6 weeks, one engineer)
+
+| Wk | Deliverable |
+|---|---|
+| 1 | ABOM v0 schema + `bom.py` (composition, provenance, verify) + tamper test ✓ |
+| 2 | Control API: runs, `/v1/runs/{id}/abom`, `/v1/abom/verify`, RBAC |
+| 3 | Capture hooks in the model router + tool gateway (real model/tool/data events) |
+| 4 | Real ed25519/cosign signing; persist to a minimal Notary (append-only table) |
+| 5 | CycloneDX + SIEM export; second decidable verify rule hardened |
+| 6 | docker-compose end-to-end; Helm stub; design-partner demo |
+
+---
+
+## 9. Risk specific to the MVP
+
+**Capture completeness.** A provenance chain is only trustworthy if *every* action
+is recorded. The MVP supplies actions explicitly; the product earns completeness
+by generating from inside the runtime (control-plane taps + framework hooks + an
+eBPF egress backstop). Keep the `abom-gen` capture interface stable so those
+sources can be added without changing the artifacts.

abom_cli-0.1.0/Makefile

@@ -0,0 +1,32 @@
+.PHONY: install test scan verify demo build up down migrate lint
+
+install:
+	pip install -e ".[dev]"
+
+test:
+	PYTHONPATH=src pytest -q
+
+scan:
+	PYTHONPATH=src python -m abom.cli scan . -o abom.json
+
+verify:
+	PYTHONPATH=src python -m abom.cli verify abom.json
+
+build:
+	rm -rf dist && python -m build && twine check dist/*
+
+up:
+	docker compose up -d --build
+
+down:
+	docker compose down -v
+
+migrate:
+	PYTHONPATH=src python scripts/init_db.py
+	@echo "(MVP) tables created via metadata. For prod, switch to Alembic migrations."
+
+demo:
+	python3 demo/demo.py
+
+lint:
+	ruff check src tests

abom_cli-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: abom-cli
+Version: 0.1.0
+Summary: ABOM — the Agent Bill of Materials. Scan, sign, and verify what your AI agents are made of.
+Project-URL: Homepage, https://abom.ai
+Project-URL: Repository, https://github.com/josephassiga/abom
+Project-URL: Specification, https://github.com/josephassiga/abom/tree/main/spec
+Author: ABOM Contributors
+License-Expression: Apache-2.0
+Keywords: agent,ai,ai-security,cyclonedx,llm,ml-bom,provenance,sbom,supply-chain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: jsonschema>=4.21; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: alembic>=1.13; extra == 'server'
+Requires-Dist: asyncpg>=0.30; extra == 'server'
+Requires-Dist: boto3>=1.35; extra == 'server'
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: httpx>=0.27; extra == 'server'
+Requires-Dist: pydantic-settings>=2.6; extra == 'server'
+Requires-Dist: pydantic>=2.9; extra == 'server'
+Requires-Dist: python-jose[cryptography]>=3.3; extra == 'server'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'server'
+Requires-Dist: temporalio>=1.8; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.32; extra == 'server'
+Description-Content-Type: text/markdown
+
+# abom-cli
+
+The reference implementation of [ABOM](../spec/) — the Agent Bill of Materials.
+Scan a repo, emit a **signed** Composition Manifest, and **verify** it.
+
+```bash
+pip install abom-cli        # (until published: pip install -e .)
+abom scan .                 # → abom.json (signed with ed25519)
+abom verify abom.json       # check signature
+abom verify abom.json --policy policy.json   # + enforce a policy (exit 1 on violations)
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `abom scan [PATH]` | Detect agent components (models, prompts, tools, MCP servers, frameworks, vector stores, guardrails) and emit a signed Composition Manifest. `-o -` writes to stdout. |
+| `abom verify [FILE]` | Verify the ed25519 signature; with `--policy`, enforce model allowlist / residency / egress / approval rules. Non-zero exit on findings (CI-friendly). |
+| `abom keygen` | Show (or create) the local ed25519 signing key (`~/.abom/signing_key.pem`, override with `ABOM_KEY`). |
+| `abom version` | Print the tool and spec versions. |
+
+### Example
+
+```
+$ abom scan .
+  ABOM · my-agent @ 1.2.0
+  models                  3  gpt-4o-mini, claude-3-5-sonnet, OpenAI (SDK)
+  frameworks              2  LangChain, LangGraph
+  MCP servers             2  filesystem, github
+  tools                   1  lookup_customer
+  prompts                 1  prompts/system.txt
+  signed: ed25519 · key 5846eabc738b3542
+  → wrote abom.json
+```
+
+## How detection works
+
+`abom scan` is a static scanner (pure stdlib + `cryptography`):
+- **Dependencies** (`requirements*.txt`, `pyproject.toml`, `package.json`) → frameworks, model SDKs, vector stores, guardrails.
+- **Source** → concrete model names (`gpt-4o`, `claude-*`, …) and `@tool`-decorated functions.
+- **Prompt files** (`*.prompt`, `prompts/*.txt|md`) → hashed.
+- **MCP configs** (`mcp.json`, `claude_desktop_config.json`, …) → MCP servers.
+
+Each component records `detected_from` so the manifest is auditable. The output
+validates against [`spec/abom-0.1.schema.json`](../spec/abom-0.1.schema.json).
+
+## Signing
+
+`abom scan` signs with **ed25519** (`cryptography`). The key lives at
+`~/.abom/signing_key.pem` (override with `ABOM_KEY`); the public key + a short
+`key_id` are embedded so `abom verify` is self-contained. A Notary / key registry
+pins trusted key ids in production.
+
+## Dev
+
+```bash
+make install          # pip install -e ".[dev]"
+make test             # pytest (audit chain, scanner, signing)
+make scan && make verify
+make build            # wheel + sdist + twine check
+python demo/demo.py   # generate → verify → tamper-evidence walkthrough
+```
+
+## What else is in this package
+
+`src/abom/` also contains a **prototype control-plane** (`api.py`, `db.py`,
+`orchestration.py`, the Notary) behind the optional `[server]` extra — the
+beginnings of the commercial layer. It is **not** required for `scan`/`verify`
+and is not part of the v0.1 spec. See [MVP_SPEC.md](MVP_SPEC.md).

abom_cli-0.1.0/README.md

@@ -0,0 +1,69 @@
+# abom-cli
+
+The reference implementation of [ABOM](../spec/) — the Agent Bill of Materials.
+Scan a repo, emit a **signed** Composition Manifest, and **verify** it.
+
+```bash
+pip install abom-cli        # (until published: pip install -e .)
+abom scan .                 # → abom.json (signed with ed25519)
+abom verify abom.json       # check signature
+abom verify abom.json --policy policy.json   # + enforce a policy (exit 1 on violations)
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `abom scan [PATH]` | Detect agent components (models, prompts, tools, MCP servers, frameworks, vector stores, guardrails) and emit a signed Composition Manifest. `-o -` writes to stdout. |
+| `abom verify [FILE]` | Verify the ed25519 signature; with `--policy`, enforce model allowlist / residency / egress / approval rules. Non-zero exit on findings (CI-friendly). |
+| `abom keygen` | Show (or create) the local ed25519 signing key (`~/.abom/signing_key.pem`, override with `ABOM_KEY`). |
+| `abom version` | Print the tool and spec versions. |
+
+### Example
+
+```
+$ abom scan .
+  ABOM · my-agent @ 1.2.0
+  models                  3  gpt-4o-mini, claude-3-5-sonnet, OpenAI (SDK)
+  frameworks              2  LangChain, LangGraph
+  MCP servers             2  filesystem, github
+  tools                   1  lookup_customer
+  prompts                 1  prompts/system.txt
+  signed: ed25519 · key 5846eabc738b3542
+  → wrote abom.json
+```
+
+## How detection works
+
+`abom scan` is a static scanner (pure stdlib + `cryptography`):
+- **Dependencies** (`requirements*.txt`, `pyproject.toml`, `package.json`) → frameworks, model SDKs, vector stores, guardrails.
+- **Source** → concrete model names (`gpt-4o`, `claude-*`, …) and `@tool`-decorated functions.
+- **Prompt files** (`*.prompt`, `prompts/*.txt|md`) → hashed.
+- **MCP configs** (`mcp.json`, `claude_desktop_config.json`, …) → MCP servers.
+
+Each component records `detected_from` so the manifest is auditable. The output
+validates against [`spec/abom-0.1.schema.json`](../spec/abom-0.1.schema.json).
+
+## Signing
+
+`abom scan` signs with **ed25519** (`cryptography`). The key lives at
+`~/.abom/signing_key.pem` (override with `ABOM_KEY`); the public key + a short
+`key_id` are embedded so `abom verify` is self-contained. A Notary / key registry
+pins trusted key ids in production.
+
+## Dev
+
+```bash
+make install          # pip install -e ".[dev]"
+make test             # pytest (audit chain, scanner, signing)
+make scan && make verify
+make build            # wheel + sdist + twine check
+python demo/demo.py   # generate → verify → tamper-evidence walkthrough
+```
+
+## What else is in this package
+
+`src/abom/` also contains a **prototype control-plane** (`api.py`, `db.py`,
+`orchestration.py`, the Notary) behind the optional `[server]` extra — the
+beginnings of the commercial layer. It is **not** required for `scan`/`verify`
+and is not part of the v0.1 spec. See [MVP_SPEC.md](MVP_SPEC.md).

abom_cli-0.1.0/charts/abom/Chart.yaml

@@ -0,0 +1,9 @@
+apiVersion: v2
+name: abom
+description: ABOM — production control plane for agentic AI (MVP Helm stub)
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+# MVP stub. Real chart adds: Operator CRDs, Temporal subchart, vLLM/KServe
+# serving, NetworkPolicies (zero egress), Vault integration, OTel collector,
+# and an offline/air-gap values overlay.

abom_cli-0.1.0/charts/abom/values.yaml

@@ -0,0 +1,36 @@
+# MVP stub values. The production chart enforces sovereignty defaults
+# (egressPolicy: deny-all, airgap mode, signed images only).
+
+image:
+  repository: ghcr.io/abom/abom
+  tag: "0.1.0"
+  pullPolicy: IfNotPresent
+
+api:
+  replicas: 2
+  port: 8000
+
+worker:
+  replicas: 2
+
+postgres:
+  # In prod, use CloudNativePG / customer-managed Postgres.
+  url: "postgresql+asyncpg://abom:abom@abom-postgres:5432/abom"
+
+temporal:
+  host: "abom-temporal:7233"
+  namespace: default
+
+modelServing:
+  # vLLM on customer GPUs (KServe in prod).
+  baseUrl: "http://abom-vllm:8000/v1"
+  model: "local/qwen2.5-coder"
+
+sovereignty:
+  airgap: false           # true => no managed control channel, offline updates only
+  egressPolicy: deny-all  # NetworkPolicy posture; egress only via gated gateway
+  requireSignedImages: true
+
+audit:
+  retentionDays: 3650
+  wormCopy: false         # Phase-2: WORM object copy + periodic anchoring

abom_cli-0.1.0/demo/README.md

@@ -0,0 +1,69 @@
+# ABOM demo — generate · verify · prove tamper-evidence
+
+This is the demonstration that matters for ABOM: it generates an **Agent Bill of
+Materials** for an agent run and shows **abom-verify** catching real policy
+violations a raw log would let ship silently — then proves the record can't be
+quietly scrubbed.
+
+## Run it
+
+```bash
+cd cli
+python3 demo/demo.py        # or: make demo
+```
+
+No infrastructure required — no Temporal, Postgres, GPU. The model is a
+deterministic mock; the **test gate is a real subprocess**, and the **signing,
+hash-chaining, and policy verification are real** ([../src/abom/bom.py](../src/abom/bom.py),
+[../src/abom/audit.py](../src/abom/audit.py)).
+
+## What it does
+
+It emits one signed **Composition Manifest** (what the agent is made of) and runs
+an agent two ways, each producing a hash-chained **Action Provenance** chain
+(what the agent did), then runs **abom-verify**:
+
+| Run | What happens | abom-verify |
+|---|---|---|
+| **Compliant** | approved model, no bad egress, consequential action approved | **CLEAN** — 0 findings |
+| **Violating** | shadow (unapproved) model, confidential data egressed to an unapproved endpoint, consequential action with no approval | **BLOCKED** — 5 findings |
+
+The five findings on the violating run: `model_allowlist`, `composition_drift`,
+`approval_coverage`, `residency`, `egress_allowlist`.
+
+Then it tampers — edits the provenance record to **erase the egress** — and shows
+the hash chain breaks (`chain_integrity` finding), so the evidence can't be
+silently scrubbed.
+
+## Expected output
+
+```
+abom-verify [compliant]: CLEAN ✓  over 2 actions
+abom-verify [violating]: BLOCKED ✗  (5 findings)  over 2 actions
+    • [high] model_allowlist (seq 0): unapproved model used: external/gpt-4o
+    • [high] composition_drift (seq 0): runtime model not in signed manifest: external/gpt-4o
+    • [high] approval_coverage (seq 0): consequential action without approval
+    • [high] residency (seq 1): confidential data egressed
+    • [medium] egress_allowlist (seq 1): egress to unapproved endpoint: telemetry.vendor.example
+scrubbing the record → chain integrity: BROKEN (detected)
+✓ DEMO ASSERTIONS PASSED
+```
+
+## Artifacts (written to `demo/out/`)
+
+- `composition.json` — the signed Composition Manifest.
+- `provenance_compliant.json` / `provenance_violating.json` — the hash-chained Action Provenance chains.
+- `verify.json` — the machine-checkable abom-verify results.
+
+## What this proves — and what it doesn't
+
+It proves the four ABOM mechanics: **composition** is captured and signed,
+**provenance** is recorded and tamper-evident, **verify** catches policy
+violations that would otherwise ship silently, and scrubbing the evidence is
+**detected**.
+
+It does **not** prove capture *completeness* — here the actions are supplied by
+the demo. The real product earns completeness by generating from inside the agent
+runtime / control plane (see the project docs (kept private) §3.2),
+which is the next thing to build and the metric to put in front of a design
+partner.