fix: address pii filter review follow-ups

Signed-off-by: lucarlig <luca.carlig@ibm.com>

Author: lucarlig

plugins/pii_filter/README.md

@@ -25,7 +25,7 @@ A plugin for detecting and masking Personally Identifiable Information (PII) in
 ### Masking Strategies
 - **REDACT** - Complete replacement with `[REDACTED]` or custom text
 - **PARTIAL** - Show partial info (e.g., `***-**-1234` for SSN, `j***e@example.com` for email)
-- **HASH** - Replace with hash value for consistency
+- **HASH** - Replace with a deterministic SHA-256-derived placeholder such as `[HASH:8f434346648f6b96]`
 - **TOKENIZE** - Replace with unique token for reversibility
 - **REMOVE** - Complete removal of PII
 
@@ -212,7 +212,7 @@ To prevent Regular Expression Denial of Service (ReDoS) attacks, custom patterns
 - **Maximum alternations (`|`):** 16
 - **Maximum quantifiers (`*`, `+`, `?`, `{}`):** 24
 
-These limits ensure that custom patterns cannot create pathological regex behavior that could consume excessive CPU resources. Patterns exceeding these limits will be rejected during configuration validation.
+Custom patterns are expected to be written by trusted operators in plugin configuration, not supplied by end users at request time. The Rust detector uses the `regex` crate's linear-time matching engine, and these limits add extra guardrails for maintainability and compilation cost. Patterns exceeding these limits will be rejected during configuration validation.
 
 Test the custom pattern:
 ```python

plugins_rust/pii_filter/README.md

@@ -152,23 +152,30 @@ This section describes the current Rust detector behavior so users know what is
 **Covers**
 - User-defined regex patterns for organization-specific identifiers
 - Explicit per-pattern masking strategies
-- Guardrails that reject patterns that are too long or too complex
+- Guardrails that reject patterns that are too long or too complex for maintainable admin-authored configuration
 
 **Does not cover**
 - Unlimited regex expressiveness
 - Automatic tuning of custom patterns for precision or recall
 - Protection against poor pattern choices that are syntactically valid but semantically too broad
 
+Custom patterns are intended for trusted operators editing plugin configuration, not untrusted end-user input. The Rust implementation relies on the [`regex`](https://docs.rs/regex/latest/regex/) crate, which avoids catastrophic backtracking during matching, and then applies additional length and complexity limits to keep custom expressions readable and cheap to compile.
+
 ## Secret Detection
 
 The Rust plugin also detects AWS keys and generic API-key style assignments, but secret formats tend to be environment-specific and evolve quickly. Treat those detectors as best-effort safeguards rather than exhaustive secret scanning, and use dedicated secret-scanning tooling if you need stronger guarantees.
 
 ## Security Notes
 
 - Whitelist patterns are compiled case-insensitively.
-- Custom patterns must stay within basic length and complexity limits.
+- Custom patterns must stay within basic length and complexity limits and are meant for trusted admin-authored configuration.
 - Very large strings and oversized nested collections are rejected instead of being scanned indefinitely.
 
+## Masking Notes
+
+- `HASH` masking emits the first 16 hexadecimal characters of the SHA-256 digest, for example `[HASH:8f434346648f6b96]`.
+- Earlier releases emitted 8 hexadecimal characters. Update downstream parsers if they assumed the shorter fixed-width placeholder.
+
 ## Testing
 
 ```bash

plugins_rust/pii_filter/src/masking.rs

@@ -79,9 +79,12 @@ fn validate_detection_ranges(
             }
 
             if !text.is_char_boundary(detection.start) || !text.is_char_boundary(detection.end) {
-                return Err(
-                    "Invalid detection range: offsets must align to UTF-8 boundaries".to_string(),
-                );
+                return Err(format!(
+                    "Invalid detection range: offsets {}..{} must align to UTF-8 boundaries (text len: {})",
+                    detection.start,
+                    detection.end,
+                    text.len()
+                ));
             }
 
             ranges.push((detection.start, detection.end));
@@ -327,4 +330,24 @@ mod tests {
         let err = mask_pii(text, &detections, &config).unwrap_err();
         assert!(err.contains("Overlapping detection ranges"));
     }
+
+    #[test]
+    fn test_mask_pii_reports_utf8_boundary_offsets() {
+        let config = PIIConfig::default();
+        let text = "Joé";
+        let mut detections = HashMap::new();
+        detections.insert(
+            PIIType::Custom,
+            vec![Detection {
+                value: "o".to_string(),
+                start: 3,
+                end: 3,
+                mask_strategy: MaskingStrategy::Redact,
+            }],
+        );
+
+        let err = mask_pii(text, &detections, &config).unwrap_err();
+        assert!(err.contains("offsets 3..3"));
+        assert!(err.contains(&format!("text len: {}", text.len())));
+    }
 }

plugins_rust/pii_filter/src/patterns.rs

@@ -321,6 +321,12 @@ pub fn compile_patterns(config: &PIIConfig) -> Result<CompiledPatterns, String>
     })
 }
 
+/// Validate admin-authored custom patterns before compilation.
+///
+/// These patterns come from trusted plugin configuration rather than end-user input.
+/// The Rust `regex` crate uses a linear-time engine without catastrophic backtracking,
+/// so these limits are lightweight guardrails for readability, compile cost, and
+/// obvious mistakes instead of a full regex sandbox.
 fn validate_custom_pattern(pattern: &str) -> Result<(), String> {
     const MAX_CUSTOM_PATTERN_LEN: usize = 256;
     const MAX_ALTERNATIONS: usize = 16;

tests/unit/mcpgateway/plugins/plugins/pii_filter/test_pii_filter.py

@@ -913,11 +913,15 @@ def test_large_batch_detection(self):
 
         # Generate 10,000 lines of text with PII
         lines = []
-        for i in range(10000):
-            area = (i % 799) + 100
-            if area == 666:
-                area = 667
-            lines.append(f"User {i}: SSN {area:03d}-45-6789, Email user{i}@example.com")
+        area = 100
+        while len(lines) < 10000:
+            if area != 666:
+                i = len(lines)
+                lines.append(f"User {i}: SSN {area:03d}-45-6789, Email user{i}@example.com")
+
+            area += 1
+            if area >= 900:
+                area = 100
         text = "\n".join(lines)
 
         start = time.time()