docs(security): three-component architecture (PTY + eBPF + SLM daemon)#75
Merged
Conversation
Major design update per 2026-05-18 external review. Three cooperating
pieces with a hard kernel/user-space split:
1. atty (PTY proxy, Zig) — sees command intent at typed-line time,
decides threat level via deterministic state machine, marks
high-risk PID trees in an eBPF hash map.
2. eBPF LSM (kernel, no custom module) — backstops the PTY blind
spot (postinstall scripts that fork detached processes never go
through atty's PTY but DO go through security_bprm_check).
3. atty-guard (Rust/Go daemon) — owns the ringbuf + ONNX SLM.
eBPF can't host the model (verifier rejects FP / >512B stack /
unbounded loops).
Hybrid async/sync mode driven by threat level: `git status` stays
async (zero perceptible latency); `npm install` / `curl | bash` /
interpreted-code-execution flip to synchronous block-and-classify.
PID-tree marking propagates the high-threat status to every child
process spawned under a risky parent, closing the postinstall
bypass.
Doc additions:
- TL;DR ASCII diagram of the three-component flow.
- Threat-level matrix (Benign/High/Critical with example commands).
- Spelled-out semantics of the two modes (async vs sync).
- Edge cases: terminal-escape obfuscation, non-PTY bypass, PID-tree
explosion on `make -j`, atty-guard down, state-sharing options.
- V2 section rewritten — atty-guard now ships TWO pieces (daemon +
eBPF object), with explicit "why three processes" rationale
(failure isolation, CAP_BPF boundary, model footprint).
- V3 stretch — Tier 3 SIGSTOP is subsumed by the eBPF backstop;
list process-group propagation + MFA on Critical as new stretch.
- Anti-patterns clarified: custom kernel module is OUT (use eBPF);
separate daemon is IN by design, not against the suckless ethos.
No code changes — design doc only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major update to `docs/security-guard-design.md` capturing the 2026-05-18 design conversation. Key shift: no custom kernel module, three cooperating user-space + eBPF pieces, hybrid sync/async driven by a PTY-proxy threat-level state machine.
Architectural reframe
```
atty (PTY proxy, Zig) ◀── UDS RPC ──▶ atty-guard (Rust/Go daemon)
│ │
▼ PID → threat level ▼
eBPF hash map ─────────────▶ ONNX-SLM (Tier 1 regex + Tier 2 model)
▲
│ kernel: bpf_lsm_security_bprm_check + sys_enter_execve
│
every execve gated by parent's threat-level entry
```
What the doc now covers
Test plan
🤖 Generated with Claude Code