Response Sanitization

ResponseSanitizationGuard types

The guard is defined in crates/guards/chio-guards/src/response_sanitization/simple.rs. The module splits into submodules under response_sanitization/ (simple.rs, sanitizer.rs, types.rs, overlap.rs, and others), and the top-level response_sanitization.rs re-exports them.

/// Classification level for a detected pattern.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SensitivityLevel {
    // ... one doc comment per variant
    Low,
    Medium,
    High,
}

/// A named pattern that matches sensitive data.
#[derive(Debug, Clone)]
pub struct SensitivePattern {
    // ... one doc comment per field
    pub name: String,
    regex: Regex,
    pub level: SensitivityLevel,
    pub redaction: String,
}

/// Action to take when sensitive data is detected by the simple guard.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SanitizationAction {
    Block,
    Redact,
}

// ... default_patterns()

/// Guard that scans responses for PII/PHI patterns and redacts or blocks them.
pub struct ResponseSanitizationGuard {
    patterns: Vec<SensitivePattern>,
    min_level: SensitivityLevel,
    action: SanitizationAction,
}

Default patterns

Quoted from default_patterns() at response_sanitization/simple.rs:44. The seven specs live in a [(&str, &str, SensitivityLevel, &str); 7] array and compile in a loop through compile_required_pattern. On any compile failure the function returns the single catch-all pattern: name redaction_unavailable_fail_closed, regex [\s\S]+, level High, redaction [REDACTED].

let specs: [(&str, &str, SensitivityLevel, &str); 7] = [
    (
        r"\b\d{3}-\d{2}-\d{4}\b",
        "SSN",
        SensitivityLevel::High,
        "[SSN REDACTED]",
    ),
    (
        r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b",
        "email",
        SensitivityLevel::Medium,
        "[EMAIL REDACTED]",
    ),
    (
        r"\b(?:\(\d{3}\)\s*|\d{3}[-.])\d{3}[-.]?\d{4}\b",
        "phone",
        SensitivityLevel::Low,
        "[PHONE REDACTED]",
    ),
    (
        r"\b(?:\d{4}[-\s]?){3}\d{4}\b",
        "credit-card",
        SensitivityLevel::High,
        "[CARD REDACTED]",
    ),
    (
        r"\b(?:\d{2}/\d{2}/\d{4}|\d{4}-\d{2}-\d{2})\b",
        "date-of-birth",
        SensitivityLevel::Low,
        "[DATE REDACTED]",
    ),
    (
        r"\bMRN[:\s#]*\d{6,12}\b",
        "MRN",
        SensitivityLevel::High,
        "[MRN REDACTED]",
    ),
    (
        r"\b[A-Z]\d{2}(?:\.\d{1,4})?\b",
        "ICD-10",
        SensitivityLevel::Medium,
        "[ICD REDACTED]",
    ),
];

The redact path, ResponseSanitizationGuard::redact at response_sanitization/simple.rs:177, runs the patterns in declaration order with Regex::replace_all per pattern. Patterns below min_level are skipped through level_ord (Low=0, Medium=1, High=2). The Guard impl at response_sanitization/simple.rs:235-249 returns Ok(GuardDecision::deny(Vec::new())) on a finding and Ok(GuardDecision::allow()) otherwise. The MRN, DOB, ICD-10, and US-phone detectors of this simple API are outside the full sanitizer's default catalog.

OutputSanitizer configuration

The sanitizer lives in response_sanitization/sanitizer.rs, with configuration types in types.rs and detectors in detectors.rs. It is a stateless engine configured by OutputSanitizerConfig, plus a token vault for the Tokenize strategy. Hosts can call it directly; it has no Guard impl, and its kernel integration is the post-invocation SanitizerHook.

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct OutputSanitizerConfig {
    pub categories: CategoryConfig,
    pub redaction_strategies: HashMap<SensitiveCategory, RedactionStrategy>,
    pub entropy: EntropyConfig,
    pub allowlist: AllowlistConfig,
    pub denylist: DenylistConfig,
    pub max_input_bytes: usize,
    pub include_findings: bool,
}

Defaults:

• categories.secrets, categories.pii, categories.internal: true
• redaction_strategies[Secret]: Mask; redaction_strategies[Pii]: Partial; redaction_strategies[Internal]: TypeLabel
• entropy.enabled: true; entropy.threshold: 4.5 bits per character; entropy.min_token_len: 16
• max_input_bytes: 1_000_000; include_findings: true

Detector catalog

From compiled_patterns(). Each detector carries a stable ID, a category, a confidence, and a recommended redaction strategy. Detectors with validators run the regex first and then the validator on the matched text: the Luhn check rejects all-same-digit sequences and any number outside 13 to 19 digits, and the SSN validators reject area 0, 666, and 900 to 999, and a zero group or zero serial.

Redaction strategies

• Mask: replaces the match with the constant ****.
• Fingerprint: replaces it with [FP:…] holding the first 8 bytes of its SHA-256 as 16 hex characters, so the same value correlates across calls without exposure.
• Drop: replaces it with empty text. A JSON string field that consists entirely of the match becomes null.
• Tokenize: replaces it with [TOKEN:…], an opaque ID whose mapping is recorded in a shared TokenVault for reversible workflows.
• Partial: keeps the first 2 and last 2 characters with *** between them; strings of 4 characters or fewer become all asterisks.
• TypeLabel: replaces it with a typed label, [REDACTED:email] for a secret or PII data type and [REDACTED:internal] for internal data.
• Keep: leaves the output unchanged and records the finding.

Entropy detector

EntropyConfig at response_sanitization/types.rs:104, with its defaults:

pub struct EntropyConfig {
    pub enabled: bool,
    pub threshold: f64,
    pub min_token_len: usize,
}

impl Default for EntropyConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            threshold: 4.5,
            min_token_len: 16,
        }
    }
}

The entropy loop in response_sanitization/sanitizer.rs (lines 286-312) skips tokens shorter than min_token_len with if token.len() < self.config.entropy.min_token_len and tokens whose Shannon entropy is below self.config.entropy.threshold. Each remaining token becomes a finding with category Secret and confidence 0.6. Candidate tokens are base64-shaped:

fn is_candidate_secret_token(token: &str) -> bool {
    token.bytes().all(|b|
        b.is_ascii_alphanumeric()
        || matches!(b, b'+' | b'/' | b'=' | b'-' | b'_'))
}

Allowlist and denylist

• AllowlistConfig { exact, patterns }: known-safe values that stay unredacted, such as test fixtures and sample tokens. Both lists are checked.
• DenylistConfig { exact, patterns }: values that are always redacted, whatever the category or detector.
• A pattern that fails to compile raises OutputSanitizerConfigError::InvalidPattern with the list name, "allowlist" or "denylist".

Overlap resolution

resolve_overlaps at response_sanitization/overlap.rs:58 merges findings whose byte ranges overlap and keeps the highest-ranked strategy among them; strategy_rank is at line 10. A higher number wins within an overlapping group:

fn strategy_rank(s: &RedactionStrategy) -> u8 {
    match s {
        RedactionStrategy::Keep => 0,
        RedactionStrategy::Partial => 1,
        RedactionStrategy::TypeLabel => 2,
        RedactionStrategy::Fingerprint => 3,
        RedactionStrategy::Tokenize => 4,
        RedactionStrategy::Mask => 5,
        RedactionStrategy::Drop => 6,
    }
}

The merge sorts spans by start ascending, then by end descending, so the longest match at a start position comes first. It folds each span into the previous one when they overlap: the merged end becomes last.0.end.max(current.0.end), and the strategy changes only when strategy_rank(current) > strategy_rank(last). Rank applies even when the findings have different extents.

spans.sort_by(|a, b| {
    a.0.start
        .cmp(&b.0.start)
        .then_with(|| b.0.end.cmp(&a.0.end))
});

let mut merged: Vec<ResolvedSpan> = Vec::new();
for current in spans {
    if let Some(last) = merged.last_mut() {
        if current.0.start < last.0.end {
            let new_end = last.0.end.max(current.0.end);
            last.0.end = new_end;
            if strategy_rank(&current.1) > strategy_rank(&last.1) {
                last.1 = current.1;
                last.2 = current.2;
                last.3 = current.3;
                last.4 = current.4;
            }
            continue;
        }
    }
    merged.push(current);
}

Detector recommendations of Drop, Fingerprint, or Tokenize replace the category default before the merge runs (redaction_strategy_for_finding, overlap.rs:24-42), so a finding a detector flags as Drop is dropped even where its category default is Mask.

ContentReviewGuard configuration

Defined in crates/guards/chio-guards/src/content_review.rs.

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ContentReviewRules {
    pub detect_pii: bool,
    pub detect_profanity: bool,
    pub banned_words: Vec<String>,
    pub extra_patterns: Vec<String>,
    pub max_scan_bytes: usize,
}

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ContentReviewConfig {
    pub enabled: bool,
    pub default_rules: ContentReviewRules,
    pub per_service: HashMap<String, ContentReviewRules>,
}

ContentReviewGuard defaults

• enabled, default_rules.detect_pii, default_rules.detect_profanity: true
• default_rules.banned_words, default_rules.extra_patterns, per_service: empty
• default_rules.max_scan_bytes: 65536 (64 KiB)

Pattern safety limits

From CompiledRules::compile. A pattern that fails a check raises ContentReviewError::UnsafePattern or ContentReviewError::InvalidPattern at policy load.

• At most 64 extra_patterns per rule set.
• At most 512 characters per pattern.
• A complexity score of at most 96, a heuristic over alternation, quantifier, and group counts.
• Regex builder limits EXTRA_PATTERN_REGEX_SIZE_LIMIT = 1 << 20 and EXTRA_PATTERN_DFA_SIZE_LIMIT = 1 << 20.

ContentReviewGuard failure behavior

• An invalid extra-pattern regex raises ContentReviewError::InvalidPattern.
• A pattern over the safety limits raises ContentReviewError::UnsafePattern.
• A service with no per_service entry uses default_rules.
• Actions other than ExternalApiCall pass with Verdict::Allow.