feat(guardrails): PII detection and redaction (mask/block) for request and response bodies

crates/aisix-admin/src/openapi.rs

@@ -3679,6 +3679,7 @@ fn add_variant_titles(doc: &mut Value) {
                 "Azure AI Content Safety Prompt Shield",
                 "Azure AI Content Safety Text Moderation",
                 "Aliyun Text Moderation",
+                "PII Detection & Redaction",
             ],
         ),
         (
@@ -3803,6 +3804,10 @@ fn add_missing_property_descriptions(doc: &mut Value) {
             "/components/schemas/Guardrail/oneOf/4/properties/kind",
             "Guardrail provider type. Use `aliyun_text_moderation` for Aliyun text moderation.",
         ),
+        (
+            "/components/schemas/Guardrail/oneOf/5/properties/kind",
+            "Guardrail provider type. Use `pii` for in-process sensitive-data detection and redaction.",
+        ),
         (
             "/components/schemas/KeywordPattern/oneOf/0/properties/kind",
             "Pattern type. Use `literal` to match the value as plain text.",

crates/aisix-core/src/models/guardrail.rs

@@ -325,6 +325,87 @@ fn default_aliyun_risk_level_threshold() -> String {
     "high".to_owned()
 }
 
+/// One built-in detector selection for `kind: "pii"`. The `type` names a
+/// detector compiled into the DP (`aisix-guardrails::pii::BUILTIN_DETECTORS`);
+/// `action` optionally overrides the guardrail-level `default_action` for
+/// this detector only.
+#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct PiiDetectorConfig {
+    /// Built-in detector id: `email`, `china_mobile`, `china_id_card`,
+    /// `bank_card`, `us_ssn`, `ip_address`, `api_key`, `jwt`, `private_key`.
+    #[serde(rename = "type")]
+    #[schemars(length(min = 1))]
+    pub detector_type: String,
+    /// Per-detector action override: `mask` or `block`. Falls back to the
+    /// guardrail's `default_action` when omitted.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub action: Option<String>,
+}
+
+/// One operator-supplied regex detector for `kind: "pii"`.
+#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct PiiCustomPattern {
+    /// Detector name surfaced in the mask token (`[<NAME>_REDACTED]`),
+    /// telemetry counts, and block reasons. Never the matched value.
+    #[schemars(length(min = 1, max = 64))]
+    pub name: String,
+    /// Regular expression the DP compiles at chain build. Invalid patterns
+    /// are logged and the row is skipped (same contract as keyword rules).
+    #[schemars(length(min = 1))]
+    pub regex: String,
+    /// Per-pattern action override: `mask` or `block`. Falls back to the
+    /// guardrail's `default_action` when omitted.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub action: Option<String>,
+}
+
+/// Config block for `kind: "pii"`. In-process sensitive-data detection and
+/// redaction (#932): built-in detectors + custom regex patterns, each with a
+/// `mask` (redact-and-continue) or `block` action, applied to request and/or
+/// response text per the row's `hook_point`.
+///
+/// `mask` rewrites each matched span to `[<DETECTOR>_REDACTED]` and lets the
+/// request/response continue; `block` rejects with the standard 422
+/// content-filter envelope. Matched values never appear in logs, telemetry,
+/// or error envelopes — only detector names and match counts do.
+#[derive(Debug, Clone, Serialize, Deserialize, schemars::JsonSchema, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct PiiConfig {
+    /// Built-in detectors to enable. Unknown detector ids are rejected at
+    /// build time (row skipped + warn), so a typo can't silently disarm
+    /// the policy.
+    #[serde(default)]
+    pub detectors: Vec<PiiDetectorConfig>,
+    /// Operator-supplied regex detectors, evaluated after the built-ins.
+    #[serde(default)]
+    pub custom_patterns: Vec<PiiCustomPattern>,
+    /// Action for detectors that don't set their own: `mask` (default) or
+    /// `block`.
+    #[serde(default = "default_pii_action")]
+    pub default_action: String,
+
+    // --- streaming-output controls (consumed by aisix-proxy) ---
+    // Masking a streamed response requires the whole response to be held
+    // back (the mask spans chunk boundaries), so kind=pii always uses the
+    // buffer_full policy on the output hook. These knobs mirror the ACS/
+    // Aliyun buffer_full parameters.
+    /// Max bytes buffered for a streamed response before `on_buffer_exceeded` applies.
+    #[serde(default = "default_acs_max_buffer_bytes")]
+    #[schemars(range(min = 1))]
+    pub max_buffer_bytes: u64,
+    /// Buffer-overflow policy. Use `fail_open` to release output unscanned
+    /// (and unmasked) when the buffer cap is hit; the default `fail_closed`
+    /// blocks the response instead.
+    #[serde(default = "default_acs_on_buffer_exceeded")]
+    pub on_buffer_exceeded: String,
+}
+
+fn default_pii_action() -> String {
+    "mask".to_owned()
+}
+
 fn default_aliyun_window_size() -> u32 {
     2_000
 }
@@ -380,6 +461,10 @@ pub enum GuardrailKind {
     /// `TextModerationPlus` action on `green-cip.<region>.aliyuncs.com`, on
     /// input and/or output, including streaming output.
     AliyunTextModeration(AliyunTextModerationConfig),
+    /// In-process sensitive-data detection + redaction (#932): built-in
+    /// detectors + custom regex, per-detector `mask`/`block` actions, on
+    /// input and/or output, including streaming output. Always available.
+    Pii(PiiConfig),
 }
 
 impl GuardrailKind {
@@ -394,6 +479,7 @@ impl GuardrailKind {
                 "azure_content_safety_text_moderation"
             }
             GuardrailKind::AliyunTextModeration(_) => "aliyun_text_moderation",
+            GuardrailKind::Pii(_) => "pii",
         }
     }
 }
@@ -903,6 +989,61 @@ mod tests {
         }
     }
 
+    #[test]
+    fn pii_kind_parses_with_defaults() {
+        // cp-api omits unset fields (omitempty); the DP must apply the
+        // documented defaults so a minimal row still works.
+        let v = json!({
+            "name": "mask-pii",
+            "kind": "pii",
+            "detectors": [
+                { "type": "email" },
+                { "type": "china_id_card", "action": "block" }
+            ]
+        });
+        let g: Guardrail = serde_json::from_value(v).unwrap();
+        match g.config {
+            GuardrailKind::Pii(ref c) => {
+                assert_eq!(c.detectors.len(), 2);
+                assert_eq!(c.detectors[0].detector_type, "email");
+                assert_eq!(c.detectors[0].action, None);
+                assert_eq!(c.detectors[1].action.as_deref(), Some("block"));
+                assert!(c.custom_patterns.is_empty());
+                assert_eq!(c.default_action, "mask");
+                assert_eq!(c.max_buffer_bytes, 262_144);
+                assert_eq!(c.on_buffer_exceeded, "fail_closed");
+            }
+            _ => panic!("expected Pii variant"),
+        }
+    }
+
+    #[test]
+    fn pii_kind_round_trips_custom_patterns_and_overrides() {
+        let v = json!({
+            "name": "mask-pii",
+            "kind": "pii",
+            "default_action": "block",
+            "custom_patterns": [
+                { "name": "employee_id", "regex": "\\bEMP-\\d{6}\\b", "action": "mask" }
+            ],
+            "max_buffer_bytes": 1024,
+            "on_buffer_exceeded": "fail_open"
+        });
+        let g: Guardrail = serde_json::from_value(v).unwrap();
+        match g.config {
+            GuardrailKind::Pii(ref c) => {
+                assert!(c.detectors.is_empty());
+                assert_eq!(c.custom_patterns.len(), 1);
+                assert_eq!(c.custom_patterns[0].name, "employee_id");
+                assert_eq!(c.custom_patterns[0].action.as_deref(), Some("mask"));
+                assert_eq!(c.default_action, "block");
+                assert_eq!(c.max_buffer_bytes, 1024);
+                assert_eq!(c.on_buffer_exceeded, "fail_open");
+            }
+            _ => panic!("expected Pii variant"),
+        }
+    }
+
     #[test]
     fn resource_trait_uses_name_and_guardrails_kind() {
         let mut g: Guardrail = serde_json::from_value(json!({

crates/aisix-core/src/models/mod.rs

@@ -39,7 +39,8 @@ pub use guardrail::{
     AliyunTextModerationConfig, AppliedGuardrail, AzureContentSafetyConfig,
     AzureContentSafetyTextModerationConfig, BedrockAWSCredentials, BedrockConfig,
     BedrockLatencyMode, Guardrail, GuardrailAttachment, GuardrailHookPoint, GuardrailKind,
-    GuardrailScopeType, KeywordConfig, KeywordPattern,
+    GuardrailScopeType, KeywordConfig, KeywordPattern, PiiConfig, PiiCustomPattern,
+    PiiDetectorConfig,
 };
 pub use mcp_server::{McpAuthType, McpServer, McpTransport};
 pub use model::{

crates/aisix-guardrails/src/build.rs

@@ -24,7 +24,8 @@ use async_trait::async_trait;
 
 use crate::index::{GuardrailIndex, RequestContext, ScopeKind};
 use crate::keyword::{KeywordBlocklist, KeywordRule};
-use crate::{Guardrail, GuardrailChain, GuardrailVerdict, StreamOutputPolicy};
+use crate::pii::{builtin_rule, PiiAction, PiiGuardrail, PiiRule};
+use crate::{Guardrail, GuardrailChain, GuardrailVerdict, Redaction, StreamOutputPolicy};
 
 /// A snapshot table's guardrail entries in deterministic chain order:
 /// `created_at` ascending (RFC3339 strings in a fixed offset compare
@@ -211,6 +212,58 @@ fn build_one_inner(
             };
             Ok(Some(Arc::new(blocklist)))
         }
+        GuardrailKind::Pii(cfg) => {
+            if cfg.detectors.is_empty() && cfg.custom_patterns.is_empty() {
+                return Ok(None);
+            }
+            let default_action =
+                PiiAction::parse(&cfg.default_action).ok_or_else(|| BuildError::InvalidValue {
+                    field: "default_action",
+                    value: cfg.default_action.clone(),
+                })?;
+            let mut rules: Vec<PiiRule> =
+                Vec::with_capacity(cfg.detectors.len() + cfg.custom_patterns.len());
+            for d in &cfg.detectors {
+                let action = match d.action.as_deref() {
+                    None => default_action,
+                    Some(s) => PiiAction::parse(s).ok_or_else(|| BuildError::InvalidValue {
+                        field: "detectors[].action",
+                        value: s.to_owned(),
+                    })?,
+                };
+                let rule = builtin_rule(&d.detector_type, action).ok_or_else(|| {
+                    BuildError::InvalidValue {
+                        field: "detectors[].type",
+                        value: d.detector_type.clone(),
+                    }
+                })?;
+                rules.push(rule);
+            }
+            for p in &cfg.custom_patterns {
+                let action = match p.action.as_deref() {
+                    None => default_action,
+                    Some(s) => PiiAction::parse(s).ok_or_else(|| BuildError::InvalidValue {
+                        field: "custom_patterns[].action",
+                        value: s.to_owned(),
+                    })?,
+                };
+                let rule = PiiRule::new(p.name.clone(), &p.regex, action, None).map_err(|e| {
+                    BuildError::InvalidRegex {
+                        pattern: p.regex.clone(),
+                        source: e,
+                    }
+                })?;
+                rules.push(rule);
+            }
+            let on_exceeded_fail_open = cfg.on_buffer_exceeded == "fail_open";
+            let g = PiiGuardrail::new(
+                rules,
+                row.hook_point,
+                usize::try_from(cfg.max_buffer_bytes).unwrap_or(usize::MAX),
+                on_exceeded_fail_open,
+            );
+            Ok(Some(Arc::new(g)))
+        }
         #[cfg(feature = "bedrock")]
         GuardrailKind::Bedrock(cfg) => {
             // Phase 2: build the AWS-SDK-backed dispatcher. cp-api
@@ -299,6 +352,11 @@ enum BuildError {
         pattern: String,
         source: regex::Error,
     },
+    /// An enum-ish config field carrying a value the DP doesn't know
+    /// (unknown built-in detector id, unrecognised action). The row is
+    /// skipped + warned rather than silently running a weaker policy.
+    #[error("invalid {field} value {value:?}")]
+    InvalidValue { field: &'static str, value: String },
     /// A guardrail kind whose runtime dispatch was compiled out via
     /// feature flags (e.g. a pruned build that excluded `--features bedrock`
     /// or `--features azure-content-safety`). The chain treats the row as
@@ -331,6 +389,19 @@ struct MonitorGuardrail {
 }
 
 impl MonitorGuardrail {
+    /// Log the mask counts a monitor-mode redacting guardrail WOULD have
+    /// applied. Counts carry detector names only, never matched values.
+    fn observe_redaction(&self, hook: &'static str, r: Option<Redaction>) {
+        if let Some(r) = r {
+            tracing::info!(
+                guardrail_name = %self.row_name,
+                hook,
+                counts = ?r.counts,
+                "guardrail in monitor mode observed maskable spans; not redacting (enforcement_mode=monitor)",
+            );
+        }
+    }
+
     fn observe(&self, hook: &'static str, verdict: GuardrailVerdict) -> GuardrailVerdict {
         match verdict {
             GuardrailVerdict::Block { reason, .. } => {
@@ -372,6 +443,28 @@ impl Guardrail for MonitorGuardrail {
     fn runs_on_output(&self) -> bool {
         self.inner.runs_on_output()
     }
+
+    // Monitor mode observes without modifying: redaction is suppressed the
+    // same way Block verdicts are downgraded. The would-be mask counts are
+    // logged so operators can stage a redaction rule and audit its impact
+    // before enforcing it.
+    fn redacts_input(&self) -> bool {
+        false
+    }
+
+    fn redacts_output(&self) -> bool {
+        false
+    }
+
+    fn redact_input_text(&self, text: &str) -> Option<Redaction> {
+        self.observe_redaction("input", self.inner.redact_input_text(text));
+        None
+    }
+
+    fn redact_output_text(&self, text: &str) -> Option<Redaction> {
+        self.observe_redaction("output", self.inner.redact_output_text(text));
+        None
+    }
 }
 
 /// `mandatory: true` decorator. A remote guardrail that can't reach its
@@ -440,6 +533,24 @@ impl Guardrail for MandatoryGuardrail {
     fn runs_on_output(&self) -> bool {
         self.inner.runs_on_output()
     }
+
+    // Mandatory only rewrites the failure (Bypass) verdict; redaction
+    // passes straight through to the inner guardrail.
+    fn redacts_input(&self) -> bool {
+        self.inner.redacts_input()
+    }
+
+    fn redacts_output(&self) -> bool {
+        self.inner.redacts_output()
+    }
+
+    fn redact_input_text(&self, text: &str) -> Option<Redaction> {
+        self.inner.redact_input_text(text)
+    }
+
+    fn redact_output_text(&self, text: &str) -> Option<Redaction> {
+        self.inner.redact_output_text(text)
+    }
 }
 
 /// Adapter that wraps a snapshot handle and rebuilds the runtime
@@ -538,6 +649,22 @@ impl Guardrail for LiveGuardrailChain {
     fn runs_on_output(&self) -> bool {
         self.current().runs_on_output()
     }
+
+    fn redacts_input(&self) -> bool {
+        self.current().redacts_input()
+    }
+
+    fn redacts_output(&self) -> bool {
+        self.current().redacts_output()
+    }
+
+    fn redact_input_text(&self, text: &str) -> Option<Redaction> {
+        self.current().redact_input_text(text)
+    }
+
+    fn redact_output_text(&self, text: &str) -> Option<Redaction> {
+        self.current().redact_output_text(text)
+    }
 }
 
 // ---------------------------------------------------------------------------