docs+polish: SECURITY.md, enforcement.md reflects shipped guards, clean eBPF unsafe

- SECURITY.md: disclosure policy + cosign signature verification.
- docs/enforcement.md: 'what's shipped' (egress connect4 v0.3.0, file fanotify v0.4.0) +
  staged-plan status; the file guard is fanotify, not LSM-BPF (bpf-lsm not enabled).
- Removed 8 redundant unsafe blocks in the eBPF probes (clean build).
- README: Security pointer.

Author: RoyLin

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to a3s-observer will be documented in this file.
 
+## [Unreleased]
+
+### Added / Changed
+
+- `SECURITY.md` — vulnerability disclosure policy + image-signature verification.
+- `docs/enforcement.md` reflects the **shipped** guards (egress `cgroup/connect4` v0.3.0, file
+  fanotify `FAN_OPEN_PERM` v0.4.0); the file guard uses fanotify, not LSM-BPF, because `bpf`
+  isn't in this kernel's `lsm=` set.
+- Removed redundant `unsafe` blocks in the eBPF probes (clean build).
+
 ## [0.5.1] — production hardening
 
 ### Changed

README.md

@@ -134,6 +134,11 @@ a3s-observer  →  NDJSON  →  OTel Collector (filelog → OTLP)  →  your bac
 
 Rust + [Aya](https://aya-rs.dev).
 
+## Security
+
+Privileged component — see [SECURITY.md](SECURITY.md) for the disclosure policy and how to
+verify a release image's signature (cosign / Sigstore).
+
 ## License
 
 MIT

SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+a3s-observer runs **privileged** — it loads eBPF and, opt-in, attaches uprobes / fanotify — so
+it sits inside the trust boundary. Please report vulnerabilities responsibly.
+
+## Reporting
+
+Open a **private security advisory** on the repository (Security → Advisories → *Report a
+vulnerability*). Do **not** file a public issue for a vulnerability. We aim to acknowledge
+within 72 hours.
+
+## Sensitive surfaces
+
+- **Privileged probe load.** The collector needs root / `CAP_BPF`+`CAP_PERFMON`; treat the
+  binary and image as privileged components.
+- **Content capture (`A3S_OBSERVER_SSL=1`).** Off by default. When on, it captures TLS
+  **plaintext** (prompts/completions) via OpenSSL uprobes — sensitive data. Enable only where
+  capturing that content is acceptable, and secure the NDJSON sink accordingly.
+- **Enforcement (`a3s-observer-enforce` / `a3s-observer-fileguard`).** Opt-in. A bad policy can
+  block legitimate egress / file access; the default is fail-open, and policies should be
+  validated on a non-prod box (`scripts/validate-enforcement.sh`).
+
+## Supply chain
+
+Release images are pushed to GHCR, scanned (Trivy), keyless-signed (cosign / Sigstore), and
+carry SLSA build provenance + an SBOM. Verify a signature:
+
+```bash
+cosign verify ghcr.io/a3s-lab/observer:<tag> \
+  --certificate-identity-regexp 'https://github.com/A3S-Lab/Observer/.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```

a3s-observer-ebpf/src/main.rs

@@ -147,10 +147,10 @@ fn try_tls(ctx: &TracePointContext) -> Result<u32, i64> {
     let buf: *const u8 = unsafe { ctx.read_at(24)? };
     let count: u64 = unsafe { ctx.read_at(32)? };
     let fd: u64 = unsafe { ctx.read_at(16)? };
-    let pid = (unsafe { bpf_get_current_pid_tgid() } >> 32) as u32;
+    let pid = (bpf_get_current_pid_tgid() >> 32) as u32;
     let key = sock_key(pid, fd);
     // Already tracking this LLM socket → this write is request payload; accumulate + done.
-    if let Some(stat) = unsafe { LLM_SOCKS.get_ptr_mut(&key) } {
+    if let Some(stat) = LLM_SOCKS.get_ptr_mut(&key) {
         unsafe {
             (*stat).req_bytes = (*stat).req_bytes.saturating_add(count);
         }
@@ -224,15 +224,15 @@ pub fn ssl_write(ctx: ProbeContext) -> u32 {
 pub fn ssl_read_enter(ctx: ProbeContext) -> u32 {
     let buf = ctx.arg::<u64>(1).unwrap_or(0);
     if buf != 0 {
-        let tid = unsafe { bpf_get_current_pid_tgid() };
+        let tid = bpf_get_current_pid_tgid();
         let _ = SSL_READ_BUF.insert(&tid, &buf, 0);
     }
     0
 }
 
 #[uretprobe]
 pub fn ssl_read_exit(ctx: RetProbeContext) -> u32 {
-    let tid = unsafe { bpf_get_current_pid_tgid() };
+    let tid = bpf_get_current_pid_tgid();
     let ret = ctx.ret::<i32>().unwrap_or(0) as i64; // SSL_read return value = bytes decrypted
     let buf = unsafe { SSL_READ_BUF.get(&tid) }.copied();
     let _ = SSL_READ_BUF.remove(&tid);
@@ -511,7 +511,7 @@ fn on_read_enter(ctx: &TracePointContext) -> u32 {
     let Ok(fd) = (unsafe { ctx.read_at::<u64>(16) }) else {
         return 0;
     };
-    let tgid = unsafe { bpf_get_current_pid_tgid() };
+    let tgid = bpf_get_current_pid_tgid();
     let key = sock_key((tgid >> 32) as u32, fd);
     // Stash only for tracked LLM sockets — keeps this node-wide hot path cheap.
     if unsafe { LLM_SOCKS.get(&key) }.is_some() {
@@ -521,7 +521,7 @@ fn on_read_enter(ctx: &TracePointContext) -> u32 {
 }
 
 fn on_read_exit(ctx: &TracePointContext) -> u32 {
-    let tgid = unsafe { bpf_get_current_pid_tgid() };
+    let tgid = bpf_get_current_pid_tgid();
     let Some(&fd) = (unsafe { READ_FD.get(&tgid) }) else {
         return 0;
     };
@@ -534,7 +534,7 @@ fn on_read_exit(ctx: &TracePointContext) -> u32 {
         return 0;
     }
     let key = sock_key((tgid >> 32) as u32, fd as u64);
-    if let Some(stat) = unsafe { LLM_SOCKS.get_ptr_mut(&key) } {
+    if let Some(stat) = LLM_SOCKS.get_ptr_mut(&key) {
         unsafe {
             (*stat).resp_bytes = (*stat).resp_bytes.saturating_add(ret as u64);
             if (*stat).first_resp_ns == 0 {
@@ -551,7 +551,7 @@ pub fn sock_close(ctx: TracePointContext) -> u32 {
     let Ok(fd) = (unsafe { ctx.read_at::<u64>(16) }) else {
         return 0;
     };
-    let pid = (unsafe { bpf_get_current_pid_tgid() } >> 32) as u32;
+    let pid = (bpf_get_current_pid_tgid() >> 32) as u32;
     let key = sock_key(pid, fd);
     let Some(&stat) = (unsafe { LLM_SOCKS.get(&key) }) else {
         return 0; // not an LLM socket

docs/enforcement.md

@@ -3,6 +3,20 @@
 a3s-observer **observes**. This is the design for *optional* intervention (block / redirect),
 kept strictly separate so the observer core stays passive and safe.
 
+## What's shipped
+
+Two guards are implemented and KVM-validated, each driven by an **external policy file**:
+
+| Guard | Binary | Mechanism | Denies (returns `EPERM`) | Validated |
+|---|---|---|---|---|
+| **Egress** | `a3s-observer-enforce` | eBPF `cgroup/connect4` | `connect()` to policy IPs — cgroup-scoped, fail-open | v0.3.0 |
+| **File** | `a3s-observer-fileguard` | fanotify `FAN_OPEN_PERM` | `open()` of policy-listed files | v0.4.0 |
+
+The file guard uses **fanotify**, not LSM-BPF: `bpf` is not in this kernel's active `lsm=` set
+(LSM-BPF would need a custom boot cmdline), and fanotify is stock-kernel + userspace-driven —
+the same external-policy model. **Exec** blocking (LSM `bprm`) is the remaining item. The
+sections below are the broader design these two were built from.
+
 ## Why separate (first principles)
 
 Observation is passive and read-only — tracepoints → ring buffers **cannot block**.
@@ -64,16 +78,15 @@ Default policy = `AllowAll` (fail-open — never break an agent unless a rule op
 
 Every deny is *also* emitted as an observed event, so enforcement is auditable.
 
-## Staged plan (same shape the observer was built)
+## Staged plan — status
 
-1. Contract + this design + `Policy` / `Verdict` (the seam).
-2. PoC: TC-egress **SNI allowlist** — drop the ClientHello to non-approved providers, driven
-   by a policy map. Validate on a **non-prod box**.
-3. PoC: LSM `file_open` deny for a path policy.
-4. Control API for the out-of-process policy path (the language-agnostic external engine).
-5. Harden: fail-safe semantics, per-cgroup scoping, audit-every-deny.
+1. ✅ Contract + design + `Policy` / `Verdict` seam.
+2. ✅ **Egress** deny (`cgroup/connect4`, by IP/host), cgroup-scoped, fail-open — v0.3.0.
+3. ✅ **File** deny (fanotify `FAN_OPEN_PERM`, by path) — v0.4.0.
+4. ◻ **Exec** deny (LSM `bprm`) — needs `bpf` in the kernel's `lsm=` set (custom-cmdline box).
+5. ◻ Control API for the out-of-process path (today: the policy file; later a socket / gRPC).
 
-> Enforcement must be validated on a **non-prod box** — blocking real syscalls/egress on a
-> shared prod node is unacceptable. The validation is codified in
+> Enforcement is validated on a **non-prod box** — blocking real syscalls/egress on a shared
+> prod node is unacceptable. The egress check is codified in
 > [`scripts/validate-enforcement.sh`](../scripts/validate-enforcement.sh) (egress block →
-> control connects → scoping → fail-open); run it there, then tag v0.3.0.
+> control connects → scoping → fail-open); both shipped guards were KVM-validated this way.