Skip to content

Commit 97fbbb0

Browse files
CyberStrategy1CyberStrategy1
authored
Merge pull request #215 from CyberStrategyInstitute/CyberStrategy1-patch-172152
Add files via upload
2 parents 0602182 + 14756f7 commit 97fbbb0

4 files changed

Lines changed: 2553 additions & 31 deletions

File tree

‎gateway/README.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# AI SAFE² Core Gateway — v3.0
2+
3+
**FastAPI async gateway implementing the full AI SAFE² v3.0 enforcement stack.**
4+
Drop this in front of any Anthropic API consumer. Every request is risk-scored, HITL-gated, and immutably logged before it ever reaches the upstream.
5+
6+
---
7+
8+
## Architecture
9+
10+
```
11+
Client → [HeartbeatMonitor] → [RateLimiter] → [RiskScorer] → [HITL Gate] → Upstream API
12+
↓
13+
[ImmutableAuditLog]
14+
↓
15+
[ResponseScanner] → Client
16+
```
17+
18+
### Enforcement components
19+
20+
| Component | Function |
21+
|-----------|----------|
22+
| `HeartbeatMonitor` | Validates `HEARTBEAT.md` freshness before every request. Missing, empty, or stale → safe mode. Never auto-creates. |
23+
| `ImmutableAuditLog` | HMAC-SHA256 chained JSONL. Each entry links to the previous hash. Startup chain verification. Break → safe mode. |
24+
| `RiskScorer` | 3-vector composite: action\_type (0.40) × target\_sensitivity (0.35) × historical\_context (0.25). +5 injection, +3 A2A. Capped 10.0. |
25+
| `HITLCircuitBreaker` | 4-tier: AUTO (0–3) / MEDIUM (4–6, token) / HIGH (7–8, token + reason ≥20 chars) / CRITICAL (>8, HMAC 2FA challenge). |
26+
| `ResponseScanner` | Inspects every upstream response for exfil patterns and tool\_use injection payloads before returning to client. |
27+
| `SafeMode` | Event-based hard stop. Activated by heartbeat failure or chain break. Deactivated only by operator key — never by agent. |
28+
29+
---
30+
31+
## Quick start
32+
33+
### 1. Prerequisites
34+
35+
```bash
36+
python3 -m pip install fastapi uvicorn httpx pyyaml
37+
```
38+
39+
### 2. Environment variables
40+
41+
```bash
42+
export ANTHROPIC_API_KEY="sk-ant-api..." # upstream key
43+
export AUDIT_CHAIN_KEY="$(openssl rand -hex 32)" # HMAC signing key — store securely
44+
export OPERATOR_DEACTIVATION_KEY="$(openssl rand -hex 16)" # safe mode recovery
45+
export ALERT_WEBHOOK_URL="https://hooks.slack.com/..." # optional
46+
```
47+
48+
### 3. Initialize heartbeat (first run only)
49+
50+
```bash
51+
python3 -c "
52+
from gateway.main import HeartbeatMonitor
53+
m = HeartbeatMonitor('HEARTBEAT.md')
54+
m.initialize_once()
55+
print('Heartbeat initialized.')
56+
"
57+
```
58+
59+
### 4. Run
60+
61+
```bash
62+
uvicorn gateway.main:app --host 127.0.0.1 --port 8080
63+
```
64+
65+
Point your Anthropic SDK at `http://localhost:8080` and set `base_url` accordingly.
66+
67+
---
68+
69+
## HITL tier reference
70+
71+
| Tier | Score | Client requirement |
72+
|------|-------|--------------------|
73+
| AUTO | 0–3 | None |
74+
| MEDIUM | 4–6 | `X-HITL-Token: <token>` (token returned on first 403) |
75+
| HIGH | 7–8 | `X-HITL-Token` + `X-HITL-Reason` (≥ 20 characters) |
76+
| CRITICAL | > 8 | Out-of-band 2FA: `HMAC-SHA256(AUDIT_CHAIN_KEY, challenge_token)[:16]` |
77+
78+
---
79+
80+
## Risk vector scoring
81+
82+
**Action type** (tool names / message keywords):
83+
84+
| Score | Tier | Examples |
85+
|-------|------|---------|
86+
| 0 | Read | `read`, `search`, `get`, `list` |
87+
| 5 | Write | `write`, `create`, `update`, `send` |
88+
| 10 | Exec/Delete | `execute`, `delete`, `run`, `deploy`, `kill` |
89+
90+
**Target sensitivity** (content patterns):
91+
92+
| Score | Classification |
93+
|-------|---------------|
94+
| 0 | Public / generic |
95+
| 5 | Personal data (`/home/`, `Documents/`, `private`) |
96+
| 10 | System / credentials (`/etc/`, `.ssh/`, `SECRET`, `TOKEN`) |
97+
98+
**Historical context** (per user+fingerprint frequency):
99+
100+
| Score | Frequency |
101+
|-------|-----------|
102+
| 0 | Frequent (≥ 5 seen) |
103+
| 5 | Rare (< 5 seen) |
104+
| 10 | Never seen |
105+
106+
---
107+
108+
## Audit log
109+
110+
Entries are written to `logs/audit.jsonl` as HMAC-SHA256 chained JSONL:
111+
112+
```json
113+
{
114+
"seq": 1,
115+
"timestamp": "2025-01-01T00:00:00.000000+00:00",
116+
"gateway_version": "3.0.0",
117+
"framework": "AI SAFE² v3.0",
118+
"user_id": "user@example.com",
119+
"request_hash": "sha256:...",
120+
"risk_score": 4.25,
121+
"risk_vectors": {"action_type": 5.0, "target_sensitivity": 5.0, "historical_context": 5.0},
122+
"hitl_tier": "MEDIUM",
123+
"blocked": false,
124+
"reason": null,
125+
"entry_hash": "sha256:..."
126+
}
127+
```
128+
129+
Verify chain integrity at any time:
130+
131+
```bash
132+
python3 -c "
133+
from gateway.main import ImmutableAuditLog
134+
import os
135+
log = ImmutableAuditLog('logs/audit.jsonl', os.environ['AUDIT_CHAIN_KEY'])
136+
ok, count, msg = log.verify_chain()
137+
print(f'Chain: {\"OK\" if ok else \"BROKEN\"} — {count} entries — {msg}')
138+
"
139+
```
140+
141+
---
142+
143+
## Safe mode
144+
145+
Safe mode blocks **all** traffic until an operator explicitly deactivates it.
146+
147+
```bash
148+
# Deactivate via API (requires OPERATOR_DEACTIVATION_KEY)
149+
curl -X POST http://localhost:8080/emergency/deactivate-safe-mode \
150+
-H "X-Operator-Key: $OPERATOR_DEACTIVATION_KEY"
151+
```
152+
153+
Triggers: missing/empty/stale `HEARTBEAT.md`, audit chain break, operator invocation.
154+
155+
---
156+
157+
## Health endpoint
158+
159+
```bash
160+
curl http://localhost:8080/health
161+
```
162+
163+
```json
164+
{
165+
"status": "healthy",
166+
"safe_mode": false,
167+
"heartbeat_valid": true,
168+
"framework": "AI SAFE² v3.0"
169+
}
170+
```
171+
172+
---
173+
174+
## Framework reference
175+
176+
AI SAFE² v3.0 · Cyber Strategy Institute · [github.com/CyberStrategyInstitute/ai-safe2-framework](https://github.com/CyberStrategyInstitute/ai-safe2-framework)

0 commit comments

Comments
 (0)