release: v0.2.5 — --version/--help, committed smoke test, enforcement design + Policy contract

RoyLin · RoyLin · commit ad9e0e074996 · 2026-06-23T17:20:24.000+08:00
- collector --version / --help
- scripts/smoke.sh: committed e2e smoke (builds, unit-tests, loads probes, drives an LLM
  call, asserts an event) — validated on KVM (5 tests, --version, probes+events).
- enforcement extension design (docs/enforcement.md) + Policy/Verdict contract (src/policy.rs,
  the external-implementable seam; AllowAll fail-open default + sample egress-allowlist; tested).
  eBPF mechanism is phase 2.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 All notable changes to a3s-observer will be documented in this file.
 
+## [0.2.5] — operator polish + enforcement design
+
+### Added
+
+- `--version` / `--help` flags on the collector.
+- `scripts/smoke.sh` — committed end-to-end smoke test (builds, unit-tests, loads the probes,
+  drives an LLM call, asserts an event flowed) so the manual validation is reproducible.
+- **Enforcement extension — design + contract** (opt-in *intervention*, kept separate from
+  the observe-only core): `docs/enforcement.md` (architecture) + a `Policy`/`Verdict` seam
+  (`src/policy.rs`) that an **external** policy implements — in-process (`impl Policy`) or
+  out-of-process (a controller driving in-kernel policy maps via a control API). Default
+  `AllowAll` (fail-open). The eBPF mechanism (LSM `file_open`/`bprm` deny, TC egress drop) is
+  phase 2 and must be validated on a non-prod box. Note: encrypted TLS payload can be
+  dropped/RST/redirected but not modified.
+
 ## [0.2.4] — clean shutdown (k8s lifecycle)
 
 ### Changed
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "a3s-observer"
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 license = "MIT"
 description = "General-purpose, language-agnostic eBPF observability for AI agents (LLM calls, tools, files, network egress)."
diff --git a/a3s-observer-collector/Cargo.toml b/a3s-observer-collector/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "a3s-observer-collector"
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 license = "MIT"
 description = "a3s-observer collector: loads the eBPF probes and exports enriched events."
diff --git a/a3s-observer-collector/src/main.rs b/a3s-observer-collector/src/main.rs
@@ -23,6 +23,23 @@ use std::time::Duration;
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
+    match std::env::args().nth(1).as_deref() {
+        Some("--version" | "-V") => {
+            println!("a3s-observer-collector {}", env!("CARGO_PKG_VERSION"));
+            return Ok(());
+        }
+        Some("--help" | "-h") => {
+            println!(
+                "a3s-observer-collector {} — language-agnostic eBPF observability for AI agents\n\n\
+                 Run as root / CAP_BPF+CAP_PERFMON (Linux). Configure via env:\n  \
+                 A3S_OBSERVER_JSON=1    emit NDJSON (default: human-readable log)\n  \
+                 A3S_OBSERVER_FILES=1   also capture file writes (high-volume; off by default)",
+                env!("CARGO_PKG_VERSION")
+            );
+            return Ok(());
+        }
+        _ => {}
+    }
     tracing_subscriber::fmt::init();
 
     let mut ebpf = Ebpf::load(aya::include_bytes_aligned!(concat!(
diff --git a/a3s-observer-common/Cargo.toml b/a3s-observer-common/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "a3s-observer-common"
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 license = "MIT"
 description = "Shared no_std types crossing the eBPF <-> userspace boundary for a3s-observer."
diff --git a/a3s-observer-ebpf/Cargo.toml b/a3s-observer-ebpf/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "a3s-observer-ebpf"
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 license = "MIT"
 publish = false
diff --git a/docs/enforcement.md b/docs/enforcement.md
@@ -0,0 +1,75 @@
+# Enforcement (design) — opt-in, externally-implemented intervention
+
+a3s-observer **observes**. This is the design for *optional* intervention (block / redirect),
+kept strictly separate so the observer core stays passive and safe.
+
+## Why separate (first principles)
+
+Observation is passive and read-only — tracepoints → ring buffers **cannot block**.
+Enforcement is security-critical: a bug blocks legitimate traffic or breaks the agent, and it
+needs fail-open/closed semantics + a policy engine. Per "minimal core + external extensions",
+enforcement is an **opt-in extension**, never baked into the observer's blast radius.
+
+## Mechanism (what the core extension would provide)
+
+eBPF *can* enforce — but via different hooks than the observer's tracepoints:
+
+| Intervention | eBPF hook | Effect |
+|---|---|---|
+| Block file open/write | **LSM-BPF** `lsm/file_open`, `lsm/path_*` | return `-EPERM` |
+| Block exec | **LSM-BPF** `lsm/bprm_check_security` | return `-EPERM` |
+| Block / redirect egress | **TC** egress or **cgroup/connect4** | drop / RST / redirect by SNI or peer |
+| Drop at the NIC | **XDP** | drop before the stack |
+
+Honest caveat: you can **drop / RST / redirect** a connection, but you **cannot modify
+encrypted (TLS) payload** — it's encrypted. Only plaintext (pre-TLS / non-TLS) is rewritable
+via TC, which is rarely useful. LSM hooks need `CONFIG_BPF_LSM` (kernel ≥ 5.7).
+
+## External policy (the pluggable part)
+
+eBPF can't do a userspace round-trip per syscall (too slow to block inline). So the split is:
+
+```
+external policy  ──writes──▶  BPF policy maps  ──inline lookup──▶  enforcement eBPF
+(allow/deny rules)            (keyed by cgroup / SNI / path)        (LSM / TC) → allow | deny
+```
+
+The **policy lives outside the core** — two ways to implement it, both first-class:
+
+1. **In-process** — a Rust `Policy` trait impl (mirrors `IdentityResolver` / `Exporter`):
+   ```rust
+   pub enum Verdict { Allow, Deny }
+   pub trait Policy: Send + Sync {
+       fn egress(&self, id: &Identity, sni: Option<&str>, peer: IpAddr) -> Verdict;
+       fn file_write(&self, id: &Identity, path: &str) -> Verdict;
+       fn exec(&self, id: &Identity, argv: &[String]) -> Verdict;
+   }
+   ```
+   The enforcer compiles verdicts into policy-map entries the eBPF reads inline.
+
+2. **Out-of-process (fully external / language-agnostic)** — a separate controller consumes
+   the observer's existing event stream (NDJSON / OTel) and pushes verdicts through a
+   **control API** (CLI / unix-socket / gRPC that updates the policy maps). The policy engine
+   (OPA/Rego, a service, your own code in any language) lives entirely outside the binary; the
+   core only enforces what the maps say. **This is the "外部实现" path.**
+
+Default policy = `AllowAll` (fail-open — never break an agent unless a rule opts in).
+
+## Fail-safe
+
+- **fail-open** (default): unknown → allow. Observability-first; never break the agent.
+- **fail-closed**: unknown → deny (e.g., an egress allowlist). Security-first; opt-in per rule.
+
+Every deny is *also* emitted as an observed event, so enforcement is auditable.
+
+## Staged plan (same shape the observer was built)
+
+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.
+
+> Enforcement must be validated on a **non-prod box** — blocking real syscalls/egress on a
+> shared prod node is unacceptable.
diff --git a/scripts/smoke.sh b/scripts/smoke.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# End-to-end smoke test for a3s-observer. Run on a Linux box with root (CAP_BPF) + the eBPF
+# toolchain (nightly + rust-src + bpf-linker). Builds, loads the probes, drives one LLM call,
+# and checks an event flows. Exits non-zero on failure. CI can't run this (needs a real
+# kernel + root); it makes the manual validation reproducible.
+#
+#   sudo ./scripts/smoke.sh
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# rustup installs to ~/.cargo/bin; make this work in a non-login shell too.
+command -v cargo >/dev/null || { [ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"; }
+
+echo "== lib + parser unit tests =="
+cargo test -p a3s-observer -p a3s-observer-common
+
+echo "== build collector (compiles the eBPF crate) =="
+cargo build --release -p a3s-observer-collector
+bin=target/release/a3s-observer-collector
+
+echo "== --version =="
+"$bin" --version
+
+echo "== run + drive one LLM call (need root) =="
+log=$(mktemp)
+RUST_LOG=info A3S_OBSERVER_JSON=1 timeout -s INT 8 "$bin" >"$log" 2>&1 &
+pid=$!
+sleep 3
+curl -s -o /dev/null --max-time 4 https://api.anthropic.com/ 2>/dev/null || true
+wait "$pid" 2>/dev/null || true
+
+echo "== checks =="
+grep -q "probes attached" "$log" || { echo "FAIL: probes did not attach"; cat "$log"; rm -f "$log"; exit 1; }
+grep -aq '"event"' "$log" || { echo "FAIL: no events captured"; rm -f "$log"; exit 1; }
+echo "PASS: probes attached and events flowed"
+rm -f "$log"
diff --git a/src/lib.rs b/src/lib.rs
@@ -14,9 +14,11 @@
 //! the collector that loads them in `a3s-observer-collector`.
 
 pub mod model;
+pub mod policy;
 pub mod traits;
 
 pub use model::{AgentEvent, EnrichedEvent};
+pub use policy::{AllowAll, Policy, Verdict};
 pub use traits::{
     read_ppid, Exporter, Identity, IdentityResolver, JsonExporter, KubeResolver, LogExporter,
     ProcResolver, Provider, ServiceClassifier, SniClassifier,
diff --git a/src/policy.rs b/src/policy.rs
@@ -0,0 +1,78 @@
+//! Contract for the **opt-in enforcement extension** (intervention) — see
+//! `docs/enforcement.md`. The observer core never enforces; this is the seam an *external*
+//! policy plugs into.
+//!
+//! An external policy can be implemented two ways, both producing the same [`Verdict`]s:
+//! - **in-process** — a Rust `impl Policy` (like [`IdentityResolver`](crate::IdentityResolver));
+//! - **out-of-process / language-agnostic** — a separate controller that consumes the event
+//!   stream and drives the enforcement eBPF's policy maps through a control API.
+//!
+//! The verdicts here are compiled into in-kernel policy maps that the (separate, phase-2)
+//! enforcement eBPF (LSM / TC) reads inline — eBPF can't do a userspace round-trip per
+//! syscall. Default is fail-open ([`AllowAll`]): never block unless a policy opts in.
+
+use crate::traits::Identity;
+use std::net::IpAddr;
+
+/// A decision for an action before it happens.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Verdict {
+    Allow,
+    Deny,
+}
+
+/// External enforcement policy. All methods default to [`Verdict::Allow`] (fail-open), so an
+/// implementer overrides only the actions it wants to gate.
+pub trait Policy: Send + Sync {
+    /// May this agent open a connection to `sni` / `peer`? (TC egress / cgroup-connect.)
+    fn egress(&self, _id: &Identity, _sni: Option<&str>, _peer: IpAddr) -> Verdict {
+        Verdict::Allow
+    }
+    /// May this agent open `path` for writing? (LSM `file_open`.)
+    fn file_write(&self, _id: &Identity, _path: &str) -> Verdict {
+        Verdict::Allow
+    }
+    /// May this agent exec `argv`? (LSM `bprm_check_security`.)
+    fn exec(&self, _id: &Identity, _argv: &[String]) -> Verdict {
+        Verdict::Allow
+    }
+}
+
+/// The shipped default — never blocks. Enforcement is strictly opt-in.
+pub struct AllowAll;
+impl Policy for AllowAll {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // A sample external policy: an egress allowlist (fail-closed for egress only).
+    struct ProviderAllowlist(&'static [&'static str]);
+    impl Policy for ProviderAllowlist {
+        fn egress(&self, _id: &Identity, sni: Option<&str>, _peer: IpAddr) -> Verdict {
+            match sni {
+                Some(h) if self.0.iter().any(|a| h.ends_with(a)) => Verdict::Allow,
+                _ => Verdict::Deny,
+            }
+        }
+    }
+
+    #[test]
+    fn allow_all_never_blocks() {
+        let id = Identity::default();
+        let ip = IpAddr::from([0, 0, 0, 0]);
+        assert_eq!(AllowAll.egress(&id, Some("evil.com"), ip), Verdict::Allow);
+        assert_eq!(AllowAll.file_write(&id, "/etc/passwd"), Verdict::Allow);
+    }
+
+    #[test]
+    fn external_allowlist_gates_egress_only() {
+        let p = ProviderAllowlist(&["anthropic.com", "openai.com"]);
+        let id = Identity::default();
+        let ip = IpAddr::from([0, 0, 0, 0]);
+        assert_eq!(p.egress(&id, Some("api.anthropic.com"), ip), Verdict::Allow);
+        assert_eq!(p.egress(&id, Some("evil.example.com"), ip), Verdict::Deny);
+        // non-egress actions still default to allow
+        assert_eq!(p.file_write(&id, "/tmp/x"), Verdict::Allow);
+    }
+}
