Skip to content

docs: simplify architecture diagram and reorder README #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benvinegar merged 1 commit into from
Feb 17, 2026
Merged

docs: simplify architecture diagram and reorder README #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 39 additions & 70 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,76 +16,6 @@ Every AI agent framework gives the model shell access and hopes for the best. Ho

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.

## Security Stack

| Layer | What | Survives prompt injection? |
|-------|------|---------------------------|
| **Source isolation** | Source repo is admin-owned, agent has zero read access. Deploy is one-way. | ✅ Filesystem-enforced |
| **iptables egress** | Per-UID firewall chain. Allowlisted ports only, no listeners, no reverse shells. | ✅ Kernel-enforced |
| **Process isolation** | `/proc` mounted `hidepid=2`. Agent can't see other PIDs. | ✅ Kernel-enforced |
| **Shell deny list** | `hornet-safe-bash` blocks rm -rf, reverse shells, fork bombs, curl\|sh. Root-owned. | ✅ Root-owned |
| **Tool call interception** | Pi extension blocks dangerous tool calls before they hit disk or shell. | ✅ Compiled into runtime |
| **Integrity manifest** | Deploy stamps SHA256 hashes of all files. Agent can verify its own runtime hasn't been tampered with. | ✅ Admin-signed |
| **Content wrapping** | External messages wrapped with security boundaries + Unicode homoglyph sanitization. | ⚠️ LLM-dependent |
| **Injection detection** | 12 regex patterns flag suspicious content. Log-only. | ⚠️ Detection, not prevention |
| **Filesystem hardening** | 700 dirs, 600 secrets, enforced on every boot. | ✅ Boot script |
| **Log redaction** | Scrubs API keys, tokens, private keys from session logs. | ✅ Boot script |
| **Extension scanning** | Static analysis for exfiltration, obfuscation, crypto-mining patterns. | ✅ Audit-time |

## Architecture

```
admin_user (your account)
├── ~/hornet/ ← source repo (agent CANNOT read this)
│ ├── bin/
│ │ ├── deploy.sh stages source → /tmp → agent runtime
│ │ ├── security-audit.sh security posture checks
│ │ ├── setup-firewall.sh iptables per-UID lockdown
│ │ ├── hornet-safe-bash shell command deny list (root-owned)
│ │ ├── hornet-docker Docker wrapper (blocks escalation)
│ │ ├── harden-permissions.sh filesystem hardening
│ │ ├── scan-extensions.mjs extension static analysis
│ │ └── redact-logs.sh secret scrubber for logs
│ ├── hooks/pre-commit ← self-modification guardrail
│ ├── pi/
│ │ ├── extensions/ source of truth for pi extensions
│ │ │ ├── tool-guard.ts ← 🔒 tool call interception
│ │ │ └── ...
│ │ └── skills/ source of truth for agent skills
│ ├── slack-bridge/
│ │ ├── bridge.mjs Slack ↔ agent bridge
│ │ └── security.mjs ← 🔒 content wrapping, rate limiting, auth
│ ├── setup.sh system setup (run once as root)
│ └── start.sh agent launcher (deployed to runtime)

hornet_agent (unprivileged uid)
├── ~/runtime/
│ ├── start.sh deployed launcher
│ ├── bin/ deployed utility scripts
│ └── slack-bridge/ deployed bridge + security module
├── ~/.pi/agent/
│ ├── extensions/ deployed pi extensions
│ ├── skills/ agent-owned operational knowledge
│ ├── hornet-version.json deploy version (git SHA, timestamp)
│ └── hornet-manifest.json SHA256 hashes of all deployed files
├── ~/workspace/ project repos + git worktrees
└── ~/.config/.env secrets (600 perms, not in repo)
```

### Deploy model

The admin owns the source. The agent owns the runtime. Deploy is a one-way push:

```
admin: ~/hornet/bin/deploy.sh
→ stages source to /tmp (world-readable temp dir)
→ copies to agent runtime via sudo -u hornet_agent
→ stamps hornet-version.json + hornet-manifest.json
→ cleans up staging dir
```

The agent can verify its own integrity via the manifest without needing source access.

## Quick Start

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

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.

## Architecture

```
admin_user (your account)
├── ~/hornet/ ← source repo (agent CANNOT read)
│ ├── bin/ deploy, firewall, security scripts
│ ├── pi/extensions/ 🔒 tool-guard, auto-name, etc.
│ ├── pi/skills/ agent skill templates
│ ├── slack-bridge/ 🔒 bridge + security module
│ └── setup.sh / start.sh system setup + launcher

hornet_agent (unprivileged uid)
├── ~/runtime/ ← deployed copies of bin/, bridge
├── ~/.pi/agent/
│ ├── extensions/ deployed extensions (read-only)
│ ├── skills/ agent-owned (can modify)
│ └── hornet-manifest.json SHA256 integrity hashes
├── ~/workspace/ project repos + worktrees
└── ~/.config/.env secrets (600 perms)
```

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.

## Security Stack

| Layer | What | Survives prompt injection? |
|-------|------|---------------------------|
| **Source isolation** | Source repo is admin-owned, agent has zero read access. Deploy is one-way. | ✅ Filesystem-enforced |
| **iptables egress** | Per-UID firewall chain. Allowlisted ports only, no listeners, no reverse shells. | ✅ Kernel-enforced |
| **Process isolation** | `/proc` mounted `hidepid=2`. Agent can't see other PIDs. | ✅ Kernel-enforced |
| **Shell deny list** | `hornet-safe-bash` blocks rm -rf, reverse shells, fork bombs, curl\|sh. Root-owned. | ✅ Root-owned |
| **Tool call interception** | Pi extension blocks dangerous tool calls before they hit disk or shell. | ✅ Compiled into runtime |
| **Integrity manifest** | Deploy stamps SHA256 hashes of all files. Agent can verify its own runtime hasn't been tampered with. | ✅ Admin-signed |
| **Content wrapping** | External messages wrapped with security boundaries + Unicode homoglyph sanitization. | ⚠️ LLM-dependent |
| **Injection detection** | 12 regex patterns flag suspicious content. Log-only. | ⚠️ Detection, not prevention |
| **Filesystem hardening** | 700 dirs, 600 secrets, enforced on every boot. | ✅ Boot script |
| **Log redaction** | Scrubs API keys, tokens, private keys from session logs. | ✅ Boot script |
| **Extension scanning** | Static analysis for exfiltration, obfuscation, crypto-mining patterns. | ✅ Audit-time |

## Security Details

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