feat: v0.5.2 — Python + TypeScript SDKs; policy language is ACL

SDKs (dependency-free; author ACL policy, run the judge, submit events, stream typed decisions,
read metrics):
- sdk/python  (a3s-sentry, asyncio, stdlib only) — 13 tests, 3 integration vs the real binary
- sdk/typescript (@a3s-lab/sentry, Node 18+, built-ins only) — 14 tests, 1 integration
- both contract-tested: an SSRF event round-trips to a block, and an SDK-authored ACL rule fires
  through the daemon's own parser

Policy language renamed HCL -> ACL (the a3s config language), extension .acl. Naming/extension
only: same grammar + same ordered 'rules = [ ... ]' list, so existing policies keep working.
policy/rules.hcl -> policy/rules.acl; HELP/README/manifest/doc-comments updated.

Author: RoyLin

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.5.2] — Python + TypeScript SDKs; the policy language is ACL
+
+### Added
+- **Python SDK** ([`sdk/python`](sdk/python), `a3s-sentry`) and **TypeScript SDK**
+  ([`sdk/typescript`](sdk/typescript), `@a3s-lab/sentry`) — dependency-free clients that author ACL
+  policy in code, supervise the daemon, submit events, stream typed decisions, and read `/metrics` +
+  `/healthz`. Both mirror the same model and are **contract-tested against the real binary**: an SSRF
+  event round-trips to a `block`, and an SDK-authored ACL rule fires through the daemon's own parser.
+  Python: 13 tests (3 integration); TypeScript: 14 tests (1 integration).
+
+### Changed
+- **The policy language is now ACL** (the a3s config language), extension `.acl` —
+  `policy/rules.acl`, `A3S_SENTRY_POLICY=…/rules.acl`. Naming + extension only: the syntax is
+  unchanged (the ordered `rules = [ … ]` list, parsed by the same grammar, preserving first-match-wins
+  order), so existing policies keep working — just point the daemon at a `.acl` file.
+
 ## [0.5.1] — release pipeline, container image, operator runbook
 
 GA items (ii)/(iii)/(iv) — make sentry installable, deployable, and operable. No crate code change;

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-sentry"
-version = "0.5.1"
+version = "0.5.2"
 edition = "2021"
 license = "MIT"
 description = "Tiered (L1 rules / L2 LLM / L3 agent) runtime security control for AI agents, built on a3s-observer."

Cargo.toml

@@ -17,7 +17,7 @@ The three tiers trade cost for depth, so expensive judgment runs only on what ch
 
 | tier | mechanism | latency | runs on |
 |---|---|---|---|
-| **L1** | deterministic regex rule engine (HCL-configurable) | µs | every event |
+| **L1** | deterministic regex rule engine (ACL-configurable) | µs | every event |
 | **L2** | a fast LLM classifier (OpenAI-compatible endpoint) | ~100s ms | events L1 escalates |
 | **L3** | a deep [a3s-code](https://github.com/AI45Lab/Code) agent with security skills | seconds–minutes | events L2 escalates |
 
@@ -103,8 +103,8 @@ before exiting. (No signal-handling dependency.)
 
 Ships a conservative built-in rule set (privesc, reverse shells, pipe-to-shell, disk overwrite,
 credential-file access, secret/injection markers in I/O, cloud-metadata SSRF). Only the unambiguous
-cases `block`; the rest `escalate` to L2/L3 rather than guess. Extend or override with an HCL policy
-(`A3S_SENTRY_POLICY=policy/rules.hcl`):
+cases `block`; the rest `escalate` to L2/L3 rather than guess. Extend or override with an ACL policy
+(`A3S_SENTRY_POLICY=policy/rules.acl`):
 
 ```hcl
 rules = [
@@ -113,22 +113,22 @@ rules = [
 ]
 ```
 
-First match wins; no match = allow. See [`policy/rules.hcl`](policy/rules.hcl).
+First match wins; no match = allow. See [`policy/rules.acl`](policy/rules.acl).
 
 ## Dynamic policy & embedding
 
 **Hot-reload.** The policy file is watched — rewrite it from any program (a controller, your config
 system, an operator) and the rules update **live within ~2s, no restart**. A parse error keeps the
 current rules, so a bad edit never disarms the engine. This is the language-agnostic way to drive
-sentry dynamically: your logic, in any language, rewrites the HCL.
+sentry dynamically: your logic, in any language, rewrites the ACL.
 
 **Embed it.** sentry is a library — build the pipeline in-process and apply config changes at runtime:
 
 ```rust
 use a3s_sentry::{LiveRules, LlmJudge, Pipeline, Severity};
 use std::{sync::Arc, time::Duration};
 
-let rules = Arc::new(LiveRules::new(Some("rules.hcl".into()))?);   // hot-reloadable
+let rules = Arc::new(LiveRules::new(Some("rules.acl".into()))?);   // hot-reloadable
 let pipeline = Pipeline::new(rules.clone())                        // L1
     .with_l2(Arc::new(LlmJudge::new("http://llm:18051/v1", "glm", None, Duration::from_secs(10))))
     .speculate_above(Some(Severity::High))   // run L2 + L3 in parallel on high-risk
@@ -141,6 +141,42 @@ rules.reload()?;   // force-apply config changes now (e.g. on a signal / admin A
 Every tier is a `Judge` trait impl, so you can swap L1/L2/L3 for your own (a different model, an
 in-house ruleset) and keep the escalation machinery.
 
+## SDKs (Python · TypeScript)
+
+Drive sentry from your own code — author ACL policy, run the judge, submit events, stream typed
+decisions, read metrics — instead of wiring stdin/stdout by hand. Both are dependency-free and mirror
+the same model; each is contract-tested against the real binary (an SSRF event round-trips to a
+`block`, and an SDK-authored ACL rule fires through the daemon's own parser).
+
+- **Python** — [`sdk/python`](sdk/python) (`pip install a3s-sentry`), async:
+
+  ```python
+  from a3s_sentry import Sentry, SentryConfig, Event, Policy, Rule, Verdict, Severity, Action
+
+  Policy([Rule("no-netcat", "ToolExec", r"(?i)\b(ncat|netcat)\b",
+               Verdict.BLOCK, Severity.MEDIUM, "netcat", Action.DENY_EXEC)]).write("rules.acl")
+
+  async with Sentry(SentryConfig(policy="rules.acl", egress_deny="egress.txt")) as s:
+      await s.submit(Event.egress(1, "169.254.169.254", 80))      # cloud-metadata SSRF
+      async for audit in s.decisions():
+          print(audit.decision.verdict, audit.subject); break
+  ```
+
+- **TypeScript** — [`sdk/typescript`](sdk/typescript) (`@a3s-lab/sentry`), Node 18+:
+
+  ```ts
+  import { Sentry, Policy, Event } from "@a3s-lab/sentry";
+
+  new Policy([{ name: "no-netcat", on: "ToolExec", match: "(?i)\\b(ncat|netcat)\\b",
+                verdict: "block", severity: "medium", reason: "netcat", action: "deny-exec" }])
+    .write("rules.acl");
+
+  const s = new Sentry({ policy: "rules.acl", egressDeny: "egress.txt" });
+  await s.start();
+  await s.submit(Event.egress(1, "169.254.169.254", 80));
+  for await (const audit of s.decisions()) { console.log(audit.decision.verdict, audit.subject); break; }
+  ```
+
 ## Speculative parallelism
 
 By default the tiers run serially (L2, then L3 only if L2 escalates). Set `A3S_SENTRY_SPECULATE=high`
@@ -176,7 +212,7 @@ SSH client… key material can be transmitted outbound after being loaded into m
 
 | var | effect |
 |---|---|
-| `A3S_SENTRY_POLICY` | extra L1 rules (HCL); built-ins always apply; **hot-reloaded** (~2s) |
+| `A3S_SENTRY_POLICY` | extra L1 rules (ACL); built-ins always apply; **hot-reloaded** (~2s) |
 | `A3S_SENTRY_LLM_URL` | enable L2; OpenAI-compatible chat base URL (`…/v1`) |
 | `A3S_SENTRY_LLM_MODEL` / `_KEY` | L2 model name / bearer token |
 | `A3S_SENTRY_AGENT_BIN` | enable L3; the agent command (e.g. `scripts/l3-agent.mjs`) |

README.md

@@ -28,7 +28,7 @@ spec:
         - name: deny # deny-files: sentry writes, the guards read (one node-local scratch dir)
           emptyDir: {}
         - name: policy
-          configMap: { name: a3s-sentry-policy } # rules.hcl — hot-reloaded if you update it
+          configMap: { name: a3s-sentry-policy } # rules.acl — hot-reloaded if you update it
         - name: cgroup
           hostPath: { path: /sys/fs/cgroup }
       containers:
@@ -44,7 +44,7 @@ spec:
           args:
             - >
               A3S_OBSERVER_JSON=1 A3S_OBSERVER_SSL=1 a3s-observer-collector |
-              A3S_SENTRY_POLICY=/etc/sentry/rules.hcl
+              A3S_SENTRY_POLICY=/etc/sentry/rules.acl
               A3S_SENTRY_EGRESS_DENY=/deny/egress.txt
               A3S_SENTRY_FILE_DENY=/deny/file.txt A3S_SENTRY_EXEC_DENY=/deny/exec.txt
               A3S_SENTRY_LLM_URL="$LLM_URL" A3S_SENTRY_LLM_KEY="$LLM_KEY"

deploy/daemonset.yaml

@@ -1,8 +1,8 @@
-# a3s-sentry — L1 site policy (HCL).
+# a3s-sentry — L1 site policy (ACL).
 #
 # These rules are evaluated BEFORE the built-in defaults, so an earlier match here overrides a
 # built-in rule. First match wins; no match = allow. Rules are compiled at daemon startup (a bad
-# regex fails the load loudly). Point the daemon at this file with A3S_SENTRY_POLICY=policy/rules.hcl.
+# regex fails the load loudly). Point the daemon at this file with A3S_SENTRY_POLICY=policy/rules.acl.
 #
 # Each rule:
 #   name     identifier (shows up in the audit reason)

policy/rules.hcl policy/rules.aclpolicy/rules.hcl renamed to policy/rules.acl

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

sdk/python/.gitignore

@@ -0,0 +1,72 @@
+# a3s-sentry — Python SDK
+
+Author [a3s-sentry](../../) policy in code, run the judge, stream typed decisions, and read its
+metrics. Pure standard library — no dependencies. Async (`asyncio`).
+
+```bash
+pip install a3s-sentry        # or: pip install -e sdk/python
+```
+
+## Author policy (ACL, hot-reloaded)
+
+Rules are an ordered list (first match wins). `Policy.write` writes the ACL file atomically, so
+sentry's ~2s hot-reload never sees a half-written policy — rewrite it any time to update rules live.
+
+```python
+from a3s_sentry import Policy, Rule, Verdict, Severity, Action
+
+Policy([
+    Rule("no-netcat", on="ToolExec", match=r"(?i)\b(ncat|netcat)\b",
+         verdict=Verdict.BLOCK, severity=Severity.MEDIUM, reason="netcat", action=Action.DENY_EXEC),
+    Rule("admin-egress", on="Egress", match=r"^10\.0\.99\.",
+         verdict=Verdict.ESCALATE, severity=Severity.MEDIUM, reason="admin subnet"),
+]).write("rules.acl")
+```
+
+## Run sentry, submit events, stream decisions
+
+Sentry emits an audit line only for blocks / escalations / flagged events — plain benign allows are
+counted, not printed — so `decisions()` yields exactly the noteworthy ones.
+
+```python
+import asyncio
+from a3s_sentry import Sentry, SentryConfig, Event, Verdict
+
+async def main():
+    cfg = SentryConfig(policy="rules.acl", egress_deny="egress-deny.txt",
+                       llm_url="http://llm:18051/v1")  # L2 optional
+    async with Sentry(cfg) as s:
+        await s.submit(Event.egress(pid=1, peer="169.254.169.254", port=80))  # cloud-metadata SSRF
+        async for audit in s.decisions():
+            d = audit.decision
+            print(d.verdict, audit.subject, "->", d.action and (d.action.kind, d.action.target))
+            if d.verdict is Verdict.BLOCK:
+                break
+
+asyncio.run(main())
+```
+
+Event builders: `tool_exec`, `egress`, `file_access`, `dns`, `ssl_content`, `security_action`.
+
+## Read metrics
+
+```python
+from a3s_sentry import MetricsClient
+
+m = MetricsClient("127.0.0.1:9100")        # SentryConfig(metrics_addr="127.0.0.1:9100")
+assert m.health()
+snap = m.metrics()
+# alarm on these two — both mean a block did not take effect:
+print(snap.overload_degraded, snap.enforce_failed)
+```
+
+## Test
+
+```bash
+cd sdk/python
+cargo build --manifest-path ../../Cargo.toml      # build the sentry binary for the integration tests
+python -m unittest discover -s tests -t .
+```
+
+The integration tests run the real `sentry` binary (from `target/debug`, or `A3S_SENTRY_BIN`) and are
+skipped if it isn't present.

sdk/python/README.md

@@ -0,0 +1,27 @@
+"""Python SDK for a3s-sentry — author ACL policy, run the judge, stream typed decisions, read metrics."""
+
+from .events import Event, Identity
+from .metrics import MetricsClient, MetricsSnapshot, parse_metrics
+from .policy import Policy, Rule
+from .process import Sentry, SentryConfig
+from .types import Action, Audit, Decision, EnforceAction, Severity, Verdict
+
+__all__ = [
+    "Verdict",
+    "Severity",
+    "Action",
+    "EnforceAction",
+    "Decision",
+    "Audit",
+    "Rule",
+    "Policy",
+    "Event",
+    "Identity",
+    "Sentry",
+    "SentryConfig",
+    "MetricsClient",
+    "MetricsSnapshot",
+    "parse_metrics",
+]
+
+__version__ = "0.1.0"

sdk/python/a3s_sentry/__init__.py

@@ -0,0 +1,84 @@
+"""Build the observer-shaped events you submit to sentry for judging.
+
+Normally a3s-observer produces these from kernel signals; the builders here let any program feed
+sentry its own events (a custom pipeline, a test, a different telemetry source).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class Identity:
+    agent: Optional[str] = None
+    task: Optional[str] = None
+    session: Optional[str] = None
+
+    def to_json(self) -> dict:
+        return {
+            k: v
+            for k, v in (("agent", self.agent), ("task", self.task), ("session", self.session))
+            if v is not None
+        }
+
+
+@dataclass
+class Event:
+    """An event envelope. Use the builders (:meth:`tool_exec`, …), not the constructor directly."""
+
+    kind: str
+    fields: dict
+    identity: Optional[Identity] = None
+    provider: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        out: dict = {"event": {self.kind: self.fields}}
+        if self.identity is not None:
+            ident = self.identity.to_json()
+            if ident:
+                out["identity"] = ident
+        if self.provider is not None:
+            out["provider"] = self.provider
+        return out
+
+    def to_line(self) -> str:
+        return json.dumps(self.to_dict(), separators=(",", ":"))
+
+    @staticmethod
+    def tool_exec(
+        pid: int, argv: List[str], *, identity: Optional[Identity] = None, provider: Optional[str] = None
+    ) -> "Event":
+        return Event("ToolExec", {"pid": pid, "argv": list(argv)}, identity, provider)
+
+    @staticmethod
+    def egress(
+        pid: int, peer: str, port: int = 0, *, identity: Optional[Identity] = None, provider: Optional[str] = None
+    ) -> "Event":
+        return Event("Egress", {"pid": pid, "peer": peer, "port": port}, identity, provider)
+
+    @staticmethod
+    def file_access(
+        pid: int, path: str, write: bool = False, *, identity: Optional[Identity] = None, provider: Optional[str] = None
+    ) -> "Event":
+        return Event("FileAccess", {"pid": pid, "path": path, "write": write}, identity, provider)
+
+    @staticmethod
+    def dns(
+        pid: int, query: str, *, identity: Optional[Identity] = None, provider: Optional[str] = None
+    ) -> "Event":
+        return Event("Dns", {"pid": pid, "query": query}, identity, provider)
+
+    @staticmethod
+    def ssl_content(
+        pid: int, content: str, is_read: bool = False, *, identity: Optional[Identity] = None, provider: Optional[str] = None
+    ) -> "Event":
+        return Event("SslContent", {"pid": pid, "is_read": is_read, "content": content}, identity, provider)
+
+    @staticmethod
+    def security_action(
+        pid: int, kind: str, detail: int = 0, *, identity: Optional[Identity] = None, provider: Optional[str] = None
+    ) -> "Event":
+        return Event("SecurityAction", {"pid": pid, "kind": kind, "detail": detail}, identity, provider)