Skip to content
This repository was archived by the owner on Jun 23, 2026. It is now read-only.

Commit bace2ea

Browse files
hummbl-devclaude
andauthored
docs(readme): harden OWASP mapping + fix stale counts (#4)
* docs(readme): harden OWASP mapping, fix stale counts, add badges - OWASP table: add source links and "How" column for each risk - Test counts: 64 → 58 (actual), per-file breakdown corrected - Production reference: 476 → 583 tests (current hummbl-governance) - Add CI, Python, Tests, Dependencies, License badges - Add "Need 10/10?" callout linking to full hummbl-governance mapping - Link to Governance Tuple paper (Zenodo DOI) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(readme): correct author GitHub link to hummbl-dev Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 58b51a0 commit bace2ea

1 file changed

Lines changed: 27 additions & 17 deletions

File tree

README.md

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
11
# Agent Governance
22

3+
[![CI](https://github.com/hummbl-dev/agent-governance-demo/actions/workflows/ci.yml/badge.svg)](https://github.com/hummbl-dev/agent-governance-demo/actions/workflows/ci.yml)
4+
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()
5+
[![Tests](https://img.shields.io/badge/tests-58%20passing-brightgreen)]()
6+
[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)]()
7+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
8+
39
Runtime safety primitives for AI agent systems. Zero third-party dependencies.
410

5-
```
11+
```bash
612
pip install -e ".[test]"
713
python -m pytest -v
814
```
@@ -42,19 +48,21 @@ Five production-grade governance primitives for AI agent systems, extracted from
4248
| `governance_bus.py` | Append-only JSONL audit log with SHA256 content hashing, thread-safe writes, and query by agent/type/time | ~80 |
4349
| `agent_runner.py` | Execution harness wiring all four primitives into a single `execute()` call with full audit trail | ~60 |
4450

45-
## Why This Matters
51+
## OWASP Coverage
4652

47-
These primitives address 7 of 10 risks in the [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/):
53+
These five primitives address 7 of 10 risks in the [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/):
4854

49-
| OWASP Risk | Primitive |
50-
|------------|-----------|
51-
| ASI01: Agent Goal Hijack | Kill switch (graduated shutdown) |
52-
| ASI03: Identity & Privilege Abuse | Delegation tokens (HMAC-signed, scoped) |
53-
| ASI04: Supply Chain Vulnerabilities | Zero dependencies (stdlib only) |
54-
| ASI06: Memory & Context Poisoning | Governance bus (append-only, content-hashed) |
55-
| ASI07: Insecure Inter-Agent Communication | Delegation tokens (chain depth enforcement) |
56-
| ASI08: Cascading Failures | Circuit breaker (isolates failing adapters) |
57-
| ASI10: Rogue Agents | Agent runner (token verification before execution) |
55+
| OWASP Risk | Primitive | How |
56+
|------------|-----------|-----|
57+
| **ASI01** Agent Goal Hijack | [kill_switch.py](src/agent_governance/kill_switch.py) | 4-mode graduated shutdown stops hijacked agents mid-execution |
58+
| **ASI03** Identity & Privilege Abuse | [delegation_token.py](src/agent_governance/delegation_token.py) | HMAC-signed scoped tokens with chain-depth limits (max 3 hops) |
59+
| **ASI04** Supply Chain | Zero dependencies | Stdlib-only. No transitive dependency tree to compromise |
60+
| **ASI06** Memory & Context Poisoning | [governance_bus.py](src/agent_governance/governance_bus.py) | Append-only JSONL with SHA256 content hashing; tamper-evident |
61+
| **ASI07** Insecure Inter-Agent Comms | [delegation_token.py](src/agent_governance/delegation_token.py) | Chain depth enforcement prevents privilege escalation across agents |
62+
| **ASI08** Cascading Failures | [circuit_breaker.py](src/agent_governance/circuit_breaker.py) | CLOSED/HALF_OPEN/OPEN FSM isolates failing components |
63+
| **ASI10** Rogue Agents | [agent_runner.py](src/agent_governance/agent_runner.py) | Token verification before every execution; audit trail on every action |
64+
65+
**Need 10/10?** The production library [`hummbl-governance`](https://github.com/hummbl-dev/hummbl-governance) covers all 10 risks with 20 primitives, 583 tests, and the same zero-dependency guarantee. See the [full OWASP mapping](https://hummbl.io/owasp.html).
5866

5967
## Test Suite
6068

@@ -63,19 +71,21 @@ $ python -m pytest -v
6371
6472
tests/test_kill_switch.py 15 tests
6573
tests/test_circuit_breaker.py 14 tests
66-
tests/test_delegation_token.py 15 tests
67-
tests/test_governance_bus.py 10 tests
74+
tests/test_delegation_token.py 11 tests
75+
tests/test_governance_bus.py 8 tests
6876
tests/test_integration.py 10 tests
6977
--------
70-
64 tests, 0 dependencies
78+
58 tests, 0 dependencies
7179
```
7280

7381
The integration test tells a complete story: agent starts, executes tasks successfully, encounters failures, circuit breaker trips, kill switch engages, governance bus records every event.
7482

7583
## Background
7684

77-
Built by [Reuben Bowlby](https://github.com/rpbowlby) as part of [HUMMBL](https://hummbl.io)'s AI governance platform. The production version (`pip install hummbl-governance`) has 476 tests across 20 modules. This repo is a clean-room demonstration of the core patterns.
85+
Built by [Reuben Bowlby](https://github.com/hummbl-dev) as part of [HUMMBL](https://hummbl.io)'s AI governance platform. The production version ([`pip install hummbl-governance`](https://pypi.org/project/hummbl-governance/)) has 583 tests across 20 modules. This repo is a clean-room demonstration of the core patterns.
86+
87+
For the formal governance primitive underlying these mitigations, see [The Governance Tuple](https://doi.org/10.5281/zenodo.19646940) (Bowlby, 2026).
7888

7989
## License
8090

81-
Apache-2.0
91+
Apache 2.0 — see [LICENSE](LICENSE).

0 commit comments

Comments
 (0)