Skip to content

Commit 6f574fc

Browse files
committed
feat: add neox-verify CLI, sample PDF audit reports, PyPI packaging
- tools/neox_verify.py: open-source receipt verifier (pip install neox-verify) - 5 commands: verify, verify --verbose, verify --report, info, batch - colored PASS/FAIL/WARN/REVK terminal output, exit codes 0/1/2 - tests passing against all 4 demo scenarios - tools/setup.cfg: PyPI package config (entry point: neox = neox_verify:main) - examples/sample-reports/: 4 PDF audit reports from demo receipts - COMPLIANT: RFP summarization (happy path) - NON-COMPLIANT: CUI/ITAR exfiltration blocked - REVIEW REQUIRED: human checkpoint rejected - REVOKED: key compromise revocation - README.md: updated Quick Start with verifier install + sample PDF links - README.md: updated repo structure to reflect new tools/ and sample-reports/
1 parent 4c69846 commit 6f574fc

File tree

9 files changed

+702
-4
lines changed

9 files changed

+702
-4
lines changed

README.md

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,16 @@ The **Agent Accountability Receipt** is a structured, hash-chained, HMAC-signed
8080

8181
## Quick Start
8282

83+
**Option A — Verify a receipt in 30 seconds (no clone required):**
84+
85+
```bash
86+
pip install neox-verify
87+
neox verify examples/demo-receipt.json
88+
# Exit code 0 = ALL CHECKS PASSED. Works offline. No account required.
89+
```
90+
91+
**Option B — Generate receipts from the reference implementation:**
92+
8393
```bash
8494
# Clone the repository
8595
git clone https://github.com/NeoXFortress/agent-accountability-receipt.git
@@ -97,11 +107,17 @@ python3 generate_receipt.py
97107
# PASS: HMAC-SHA256 signature verified
98108
# PASS: Receipt validates against schema.json
99109
# ALL CHECKS PASSED
100-
101-
# View the generated receipt
102-
cat ../examples/demo-receipt.json | python3 -m json.tool
103110
```
104111

112+
**See what a PDF audit report looks like:**
113+
114+
👉 [**COMPLIANT** — RFP Summarization](examples/sample-reports/sample-01-compliant-rfp-summarization.pdf)
115+
👉 [**NON-COMPLIANT** — CUI Exfiltration Blocked](examples/sample-reports/sample-02-non-compliant-cui-blocked.pdf)
116+
👉 [**REVIEW REQUIRED** — Human Checkpoint Rejected](examples/sample-reports/sample-03-review-required-human-rejected.pdf)
117+
👉 [**REVOKED** — Key Compromise](examples/sample-reports/sample-04-revoked-receipt.pdf)
118+
119+
*PDF reports are generated by the [NeoXFortress AAE](https://neoxfortress.com) — enterprise, self-hosted. Contact [neoxfortress.com/contact](https://neoxfortress.com/contact) for access.*
120+
105121
## Repository Structure
106122

107123
```
@@ -111,6 +127,9 @@ agent-accountability-receipt/
111127
├── LICENSE ← MIT (schema) + proprietary notice
112128
├── NOTICE ← Copyright attribution
113129
├── requirements.txt ← Python dependencies
130+
├── tools/
131+
│ ├── neox_verify.py ← ✅ Open-source receipt verifier CLI (pip install neox-verify)
132+
│ └── setup.cfg ← PyPI package configuration
114133
├── reference_impl/
115134
│ ├── generate_receipt.py ← Reference generator + verifier
116135
│ ├── scenario_cui_blocked.py ← CUI exfiltration blocked scenario
@@ -120,7 +139,12 @@ agent-accountability-receipt/
120139
├── demo-receipt.json ← ✅ Happy path: RFP summarization (6 steps)
121140
├── cui-exfiltration-blocked.json ← 🚫 Agent tried to send CUI to Slack, blocked
122141
├── human-checkpoint-rejected.json ← ❌ Reviewer rejected hallucinated DFARS answer
123-
└── receipt-revoked.json ← 🔒 Valid receipt revoked after key compromise
142+
├── receipt-revoked.json ← 🔒 Valid receipt revoked after key compromise
143+
└── sample-reports/ ← 📄 PDF audit reports generated from above receipts
144+
├── sample-01-compliant-rfp-summarization.pdf
145+
├── sample-02-non-compliant-cui-blocked.pdf
146+
├── sample-03-review-required-human-rejected.pdf
147+
└── sample-04-revoked-receipt.pdf
124148
```
125149

126150
## Example Scenarios

examples/sample-reports/README.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Sample PDF Audit Reports
2+
3+
These are real PDF audit reports generated by the [NeoXFortress Agent Accountability Engine (AAE)](https://neoxfortress.com) from the four demo receipts in this repository.
4+
5+
Each PDF is a CMMC-ready audit artifact that a C3PAO assessor or compliance officer can review to understand what an AI agent did, what data it touched, and whether it operated within policy.
6+
7+
## Downloads
8+
9+
| Scenario | Verdict | Download |
10+
|----------|---------|----------|
11+
| RFP Intelligence Agent — happy path, CUI detected and contained, human approved |**COMPLIANT** | [sample-01-compliant-rfp-summarization.pdf](sample-01-compliant-rfp-summarization.pdf) |
12+
| Contract Drafting Agent — ITAR/CUI exfiltration to external Slack **blocked** |**NON-COMPLIANT** | [sample-02-non-compliant-cui-blocked.pdf](sample-02-non-compliant-cui-blocked.pdf) |
13+
| DFARS Compliance Advisor — human reviewer **rejected** hallucinated output | ⚠️ **REVIEW REQUIRED** | [sample-03-review-required-human-rejected.pdf](sample-03-review-required-human-rejected.pdf) |
14+
| Vendor Onboarding Agent — receipt **revoked** due to key compromise | 🔒 **REVOKED** | [sample-04-revoked-receipt.pdf](sample-04-revoked-receipt.pdf) |
15+
16+
## What's in Each Report
17+
18+
Every report contains 9 sections:
19+
20+
1. **Receipt Identification** — receipt ID, agent, operator, org, verdict badge
21+
2. **Executive Summary** — plain-English summary for non-technical reviewers
22+
3. **Compliance Verdict** — framework, active controls, violated controls, risk score
23+
4. **Execution Timeline** — step-by-step table: type, description, status, duration
24+
5. **CUI Flow & Data Protection** — classification, handling action, boundary crossings
25+
6. **Human Oversight Record** — reviewer ID, decision, notes, timestamp
26+
7. **Integrity Verification** — hash chain status, HMAC signature, independent verification instructions
27+
8. **Policy Snapshot** — policy ID/version active at time of execution
28+
9. **Agent Provenance** — deployment fingerprint, operator, execution timestamps
29+
30+
## Independent Verification
31+
32+
Any party can verify the underlying receipt independently:
33+
34+
```bash
35+
pip install neox-verify
36+
neox verify examples/demo-receipt.json
37+
```
38+
39+
The PDF is derived from the receipt JSON. The receipt is the authoritative artifact.
40+
41+
---
42+
43+
PDF reports are generated by the **NeoXFortress Agent Accountability Engine (AAE)** — enterprise, self-hosted, CMMC-grade.
44+
Contact [neoxfortress.com/contact](https://neoxfortress.com/contact) for licensing.
Binary file not shown.
16.6 KB
Binary file not shown.
Binary file not shown.
16.3 KB
Binary file not shown.

tools/PYPI_README.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# neox-verify
2+
3+
**Open-source CLI verifier for [NeoXFortress Agent Accountability Receipts](https://github.com/NeoXFortress/agent-accountability-receipt)**
4+
5+
Independently verify the cryptographic integrity of any Agent Accountability Receipt produced by the NeoXFortress AAE — no account, no cloud, no dependencies beyond stdlib.
6+
7+
## Install
8+
9+
```bash
10+
pip install neox-verify
11+
```
12+
13+
## Usage
14+
15+
```bash
16+
# Full verification (hash chain + HMAC + schema)
17+
neox verify receipt.json
18+
19+
# Step-by-step hash chain trace
20+
neox verify receipt.json --verbose
21+
22+
# Human-readable summary without crypto
23+
neox info receipt.json
24+
25+
# Verify all receipts in a directory
26+
neox batch ./receipts/
27+
28+
# Generate PDF verification report (AAE license required)
29+
neox verify receipt.json --report
30+
```
31+
32+
## Exit Codes
33+
34+
| Code | Meaning |
35+
|------|---------|
36+
| `0` | ALL CHECKS PASSED |
37+
| `1` | One or more checks FAILED |
38+
| `2` | File not found or invalid JSON |
39+
40+
Scriptable in CI/CD pipelines.
41+
42+
## What It Verifies
43+
44+
1. **Schema structure** — Receipt conforms to Agent Accountability Receipt schema v0.1.1
45+
2. **Revocation status** — Receipt has not been revoked
46+
3. **Hash chain integrity** — Every step's `prev_step_hash` matches SHA-256 of prior step; any tampering breaks the chain deterministically
47+
4. **HMAC-SHA256 signature** — Signature block is well-formed and structurally valid
48+
49+
Full cryptographic HMAC verification requires the organization's signing key (not required for assessor use — structural verification is sufficient for CMMC evidence review).
50+
51+
## Example Output
52+
53+
```
54+
╔══════════════════════════════════════════════════════════╗
55+
║ NEOXFORTRESS RECEIPT VERIFIER v0.1.1 ║
56+
╚══════════════════════════════════════════════════════════╝
57+
Receipt ID: rcpt-252afd32242d20be
58+
Agent: RFP Intelligence Agent
59+
Status: SUCCESS
60+
Verdict: COMPLIANT
61+
62+
PASS Schema v0.1.1 structure
63+
PASS Revocation status
64+
PASS Hash chain integrity (6 steps)
65+
PASS HMAC-SHA256 signature structure
66+
67+
✓ ALL CHECKS PASSED
68+
```
69+
70+
## Links
71+
72+
- **Schema & Spec:** [github.com/NeoXFortress/agent-accountability-receipt](https://github.com/NeoXFortress/agent-accountability-receipt)
73+
- **Enterprise PDF Reports:** [neoxfortress.com](https://neoxfortress.com)
74+
- **CMMC / NIST 800-171 Evidence Packages:** [neoxfortress.com/contact](https://neoxfortress.com/contact)
75+
76+
---
77+
78+
MIT License — Copyright (c) 2026 Julio Berroa / NeoXFortress LLC

0 commit comments

Comments
 (0)