Skip to content

Commit 39b7df2

Browse files
benvinegarbenvinegar
authored
docs: simplify architecture diagram and reorder README (#7)
1 parent 95815a2 commit 39b7df2

1 file changed

Lines changed: 39 additions & 70 deletions

File tree

‎README.md‎

Lines changed: 39 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -16,76 +16,6 @@ Every AI agent framework gives the model shell access and hopes for the best. Ho
1616

1717
Agents work on real files in real repos — no sandbox friction. They make real git branches, run real tests, and push real PRs. But they can't exfiltrate data, escalate privileges, or phone home.
1818

19-
## Security Stack
20-
21-
| Layer | What | Survives prompt injection? |
22-
|-------|------|---------------------------|
23-
| **Source isolation** | Source repo is admin-owned, agent has zero read access. Deploy is one-way. | ✅ Filesystem-enforced |
24-
| **iptables egress** | Per-UID firewall chain. Allowlisted ports only, no listeners, no reverse shells. | ✅ Kernel-enforced |
25-
| **Process isolation** | `/proc` mounted `hidepid=2`. Agent can't see other PIDs. | ✅ Kernel-enforced |
26-
| **Shell deny list** | `hornet-safe-bash` blocks rm -rf, reverse shells, fork bombs, curl\|sh. Root-owned. | ✅ Root-owned |
27-
| **Tool call interception** | Pi extension blocks dangerous tool calls before they hit disk or shell. | ✅ Compiled into runtime |
28-
| **Integrity manifest** | Deploy stamps SHA256 hashes of all files. Agent can verify its own runtime hasn't been tampered with. | ✅ Admin-signed |
29-
| **Content wrapping** | External messages wrapped with security boundaries + Unicode homoglyph sanitization. | ⚠️ LLM-dependent |
30-
| **Injection detection** | 12 regex patterns flag suspicious content. Log-only. | ⚠️ Detection, not prevention |
31-
| **Filesystem hardening** | 700 dirs, 600 secrets, enforced on every boot. | ✅ Boot script |
32-
| **Log redaction** | Scrubs API keys, tokens, private keys from session logs. | ✅ Boot script |
33-
| **Extension scanning** | Static analysis for exfiltration, obfuscation, crypto-mining patterns. | ✅ Audit-time |
34-
35-
## Architecture
36-
37-
```
38-
admin_user (your account)
39-
├── ~/hornet/ ← source repo (agent CANNOT read this)
40-
│ ├── bin/
41-
│ │ ├── deploy.sh stages source → /tmp → agent runtime
42-
│ │ ├── security-audit.sh security posture checks
43-
│ │ ├── setup-firewall.sh iptables per-UID lockdown
44-
│ │ ├── hornet-safe-bash shell command deny list (root-owned)
45-
│ │ ├── hornet-docker Docker wrapper (blocks escalation)
46-
│ │ ├── harden-permissions.sh filesystem hardening
47-
│ │ ├── scan-extensions.mjs extension static analysis
48-
│ │ └── redact-logs.sh secret scrubber for logs
49-
│ ├── hooks/pre-commit ← self-modification guardrail
50-
│ ├── pi/
51-
│ │ ├── extensions/ source of truth for pi extensions
52-
│ │ │ ├── tool-guard.ts ← 🔒 tool call interception
53-
│ │ │ └── ...
54-
│ │ └── skills/ source of truth for agent skills
55-
│ ├── slack-bridge/
56-
│ │ ├── bridge.mjs Slack ↔ agent bridge
57-
│ │ └── security.mjs ← 🔒 content wrapping, rate limiting, auth
58-
│ ├── setup.sh system setup (run once as root)
59-
│ └── start.sh agent launcher (deployed to runtime)
60-
61-
hornet_agent (unprivileged uid)
62-
├── ~/runtime/
63-
│ ├── start.sh deployed launcher
64-
│ ├── bin/ deployed utility scripts
65-
│ └── slack-bridge/ deployed bridge + security module
66-
├── ~/.pi/agent/
67-
│ ├── extensions/ deployed pi extensions
68-
│ ├── skills/ agent-owned operational knowledge
69-
│ ├── hornet-version.json deploy version (git SHA, timestamp)
70-
│ └── hornet-manifest.json SHA256 hashes of all deployed files
71-
├── ~/workspace/ project repos + git worktrees
72-
└── ~/.config/.env secrets (600 perms, not in repo)
73-
```
74-
75-
### Deploy model
76-
77-
The admin owns the source. The agent owns the runtime. Deploy is a one-way push:
78-
79-
```
80-
admin: ~/hornet/bin/deploy.sh
81-
→ stages source to /tmp (world-readable temp dir)
82-
→ copies to agent runtime via sudo -u hornet_agent
83-
→ stamps hornet-version.json + hornet-manifest.json
84-
→ cleans up staging dir
85-
```
86-
87-
The agent can verify its own integrity via the manifest without needing source access.
88-
8919
## Quick Start
9020

9121
```bash
@@ -163,6 +93,45 @@ Slack → bridge (access control + content wrapping) → pi agent → tools (too
16393

16494
Every layer assumes the previous one failed. The bridge wraps content and rate-limits, but tool-guard blocks dangerous commands even if wrapping is bypassed. Safe-bash blocks patterns even if tool-guard is somehow evaded. The firewall blocks exfiltration even if all software layers fail. Defense in depth, all the way down.
16595

96+
## Architecture
97+
98+
```
99+
admin_user (your account)
100+
├── ~/hornet/ ← source repo (agent CANNOT read)
101+
│ ├── bin/ deploy, firewall, security scripts
102+
│ ├── pi/extensions/ 🔒 tool-guard, auto-name, etc.
103+
│ ├── pi/skills/ agent skill templates
104+
│ ├── slack-bridge/ 🔒 bridge + security module
105+
│ └── setup.sh / start.sh system setup + launcher
106+
107+
hornet_agent (unprivileged uid)
108+
├── ~/runtime/ ← deployed copies of bin/, bridge
109+
├── ~/.pi/agent/
110+
│ ├── extensions/ deployed extensions (read-only)
111+
│ ├── skills/ agent-owned (can modify)
112+
│ └── hornet-manifest.json SHA256 integrity hashes
113+
├── ~/workspace/ project repos + worktrees
114+
└── ~/.config/.env secrets (600 perms)
115+
```
116+
117+
Deploy is a one-way push: `~/hornet/bin/deploy.sh` stages source → `/tmp` → copies as `hornet_agent` via `sudo -u` → stamps integrity manifest → cleans up.
118+
119+
## Security Stack
120+
121+
| Layer | What | Survives prompt injection? |
122+
|-------|------|---------------------------|
123+
| **Source isolation** | Source repo is admin-owned, agent has zero read access. Deploy is one-way. | ✅ Filesystem-enforced |
124+
| **iptables egress** | Per-UID firewall chain. Allowlisted ports only, no listeners, no reverse shells. | ✅ Kernel-enforced |
125+
| **Process isolation** | `/proc` mounted `hidepid=2`. Agent can't see other PIDs. | ✅ Kernel-enforced |
126+
| **Shell deny list** | `hornet-safe-bash` blocks rm -rf, reverse shells, fork bombs, curl\|sh. Root-owned. | ✅ Root-owned |
127+
| **Tool call interception** | Pi extension blocks dangerous tool calls before they hit disk or shell. | ✅ Compiled into runtime |
128+
| **Integrity manifest** | Deploy stamps SHA256 hashes of all files. Agent can verify its own runtime hasn't been tampered with. | ✅ Admin-signed |
129+
| **Content wrapping** | External messages wrapped with security boundaries + Unicode homoglyph sanitization. | ⚠️ LLM-dependent |
130+
| **Injection detection** | 12 regex patterns flag suspicious content. Log-only. | ⚠️ Detection, not prevention |
131+
| **Filesystem hardening** | 700 dirs, 600 secrets, enforced on every boot. | ✅ Boot script |
132+
| **Log redaction** | Scrubs API keys, tokens, private keys from session logs. | ✅ Boot script |
133+
| **Extension scanning** | Static analysis for exfiltration, obfuscation, crypto-mining patterns. | ✅ Audit-time |
134+
166135
## Security Details
167136

168137
See [SECURITY.md](SECURITY.md) for the full threat model and trust boundary diagram.

0 commit comments

Comments
 (0)