icebox-gov 0.1.1

Runtime governance for autonomous offensive security — the single seam every human operator, REST client, and LLM agent must pass through before anything touches a target.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# SDK: Python

`pip install icebox-sdk` gives you `icebox.Governance`, which drives
the same charter / scope / risk / approval gates that guard native
ICEBOX modules — so any Python agent can be governed by the single seam.

```sh
pip install icebox-sdk
```

The SDK wraps the compiled `libicebox` C ABI via `ctypes`. If the
native lib is not found, build it (`cargo build`) or set
`ICEBOX_CAPI` to its path.

## Govern a task

```python
from icebox import Governance

gov = Governance({
    "charter": {"accepted": True, "engagement": "demo", "rules_of_engagement": []},
    "scope": {"allow": ["10.0.0.0/24"]},
    "max_risk": "high",
    "role": "admin",
})

task = {
    "name": "scan",
    "target": "10.0.0.5",
    "capabilities": ["network_scan"],
    "impact": "low",
    "destructive": False,
    "options": {"host": "10.0.0.5", "ports": "1-1024"},
}

# Supervised: approval-gated tasks return a "NeedsApproval" decision.
outcome = gov.check(task)
# Unsupervised: approval-gated tasks are auto-granted.
outcome = gov.run(task)

print(outcome)              # e.g. {"Allowed": {"result": null, "decision_id": 1}}
print(gov.audit_json())    # full audit log as JSON
print(gov.audit_csv())     # same, as CSV
```

## Risk / CVSS gating

A task may carry a CVSS score, which policies like `deny_if_cvss_above`
consult. The `cvss` field accepts either a bare number or an object:

```python
task = {
    "name": "exploit",
    "target": "10.0.0.5",
    "capabilities": ["privilege_escalation"],
    "impact": "high",
    "destructive": False,
    "cvss": 9.5,            # a bare number...
    # ...or the structured form (epss/kev enrich the weighted risk):
    # "cvss": {"cvss_v31": 9.5, "epss": 0.9, "kev": True},
}
```

Pair it with a policy that blocks high scores:

```python
gov = Governance({
    "charter": {"accepted": True, "engagement": "demo", "rules_of_engagement": []},
    "scope": {"allow": ["10.0.0.0/8"]},
    "max_risk": "critical",
    "role": "admin",
    "policy_set": {"rules": [{"deny_if_cvss_above": 7.0}], "version": 1},
})
print(gov.check(task))
# {'Blocked': {'reason': 'CVSS score 9.5 exceeds deny threshold 7.0', ...}}
```

## API

| Method | Purpose |
| --- | --- |
| `Governance(config)` | Construct a governed runtime from a dict. |
| `.check(task)` | Supervised evaluation; approval-gated tasks return `NeedsApproval`. |
| `.run(task)` | Unsupervised evaluation; approval-gated tasks are auto-granted. |
| `.approve(id)` / `.deny(id)` | Resolve a pending approval request. |
| `.pending()` | List pending approval requests. |
| `.audit_json()` / `.audit_csv()` | Export the full audit trail. |

## Examples

See `python/examples/governed_agent.py` for a complete governed-agent
loop.