PII Redactor

intent

redact sensitive information from text using a locally-hosted, zero-shot pii/phi detection model (nvidia/gliner-pii) before sending any response. every outbound message passes through this service to reduce pii exposure risk. use this skill on all agent responses that might contain personally identifiable information, health data, financial data, or api keys. the model is non-generative and produces span-level entity annotations with confidence scores across 55+ entity categories (emails, phone numbers, ssns, credit card numbers, addresses, medical record numbers, api keys, and more). detection is probabilistic, so some pii may go undetected even with this skill active.

inputs

environment variables (required):

• CLAWGUARD_URL: service endpoint, must be http://localhost:<port> or http://127.0.0.1:<port> or https://<internal-hostname> (https mandatory for non-localhost). never point to public ips or public domains.
• CLAWGUARD_TOKEN: bearer token for /redact endpoint authentication. generate via python3 -c "import secrets; print(secrets.token_hex(32))" and store in a secret manager or secure env var. rotate if compromised.

external connection:

• clawguard-pii service (package: clawguard-pii==1.0.4). install via pip install clawguard-pii==1.0.4 or uv pip install clawguard-pii==1.0.4. start with clawguard serve (listens on localhost:8000 by default).

runtime context:

• complete draft response text (max 50,000 utf-8 characters).
• optional: THRESHOLD env var on the service (default 0.5) to tune detection sensitivity; higher threshold reduces false positives but may miss low-confidence pii.

deployment constraints:

• clawguard service must run on a trusted host (localhost preferred). do not expose to the public internet. use firewall rules to restrict access.
• for non-localhost internal hosts, use https only.
• keep CLAWGUARD_TOKEN in a secret manager, never in code or version control.

procedure

1. validate clawguard_url configuration: check that CLAWGUARD_URL matches one of these patterns:

   • http://localhost:<port> (any port)
   • http://127.0.0.1:<port> (any port)
   • https://<internal-hostname> (https required, no public domains or public ips)

   if validation fails, stop and log a configuration error; do not send the response.

2. perform health check: send GET $CLAWGUARD_URL/health with a 5-second timeout. expect {"status": "ok"} response code 200. if the service is unreachable (timeout, refused, 5xx), proceed to step 6 (fallback).

3. prepare redaction request: construct a json payload with the complete draft response text:

   {"text": "<your complete draft response>"}
   

   if the response exceeds 50,000 utf-8 characters, split into chunks of max 50,000 chars each and redact each chunk separately in serial, then concatenate redacted chunks in order.

4. send redaction request: post to $CLAWGUARD_URL/redact with:

   • header: Authorization: Bearer $CLAWGUARD_TOKEN
   • header: Content-Type: application/json
   • body: the json payload from step 3
   • timeout: 10 seconds

   parse the response:

   • on 200: extract redacted_text, redacted_count, and redacted_items array.
   • on 401: token mismatch. do not send the response. log error and alert operator. stop.
   • on 413: request body too large (should not happen if chunking correctly). split text further and retry.
   • on 422: malformed request body. log error and fall back to manual review (step 6).
   • on 5xx, timeout, or refused connection: treat as unreachable; proceed to step 6.

5. deliver redacted response:

   • if redacted_count > 0: send redacted_text to the user and append a warning banner:

     ⚠️ [N] item(s) of personal information were detected and removed: [labels]
     

     where [N] is redacted_count and [labels] is a comma-separated list of unique labels from redacted_items (e.g., "email, phone_number, ssn").
   • if redacted_count is 0: send the original response text without modification.
   • never surface the redacted_items array or the original field to end users.

6. fallback (service unreachable or auth failed): if the service is unreachable (health check failed, post returned 5xx/timeout, or 401 token error), manually review the response and strip anything resembling pii (emails, phone patterns, ssn patterns, credit card patterns, api key patterns, etc.). prepend this warning:

   ⚠️ Automated PII scanning was unavailable. This response was manually reviewed but may not be fully sanitized. Do not share sensitive information.
   

   then send the manually sanitized response.

decision points

if CLAWGUARD_URL fails validation (public ip, public domain, non-https for non-localhost): stop immediately and log a configuration error. do not send the response. require operator intervention to fix the url.

if health check fails or times out: skip the redaction request and jump to step 6 (fallback). do not retry the health check.

if the redaction post returns 401 (auth failure): do not send the response. log an error and alert the operator. token mismatch indicates a compromise or misconfiguration. stop and do not attempt fallback.

if the redaction post returns 413 (payload too large): split the text into chunks of max 50,000 utf-8 chars, redact each in serial, concatenate redacted chunks, and resume at step 5.

if the redaction post returns 422 (malformed request): log the error and proceed to step 6 (fallback manual review). this indicates a bug in the request construction.

if the redaction post returns 5xx, times out, or connection refused: treat as unreachable. proceed to step 6 (fallback).

if redacted_count is 0: send the original, unmodified response (no warning banner needed).

if redacted_count > 0: always send the redacted text with the warning banner, even if confidence scores are low. the model's decision is final.

output contract

success case (service reachable, 200 response):

• output to user: the redacted_text field from the api response if redacted_count > 0, or the original response if redacted_count is 0.
• if redacted_count > 0: append the warning banner in a code block or clearly delimited section:

  ⚠️ [N] item(s) of personal information were detected and removed: [label1, label2, ...]
  

• format: plain text, no additional markdown or html wrapping unless the original response already uses markdown.
• data location: response body or chat message, depending on the agent platform.

fallback case (service unreachable, auth failed, or manual review):

• output to user: the manually sanitized response text.
• prepend the warning banner:

  ⚠️ Automated PII scanning was unavailable. This response was manually reviewed but may not be fully sanitized. Do not share sensitive information.
  

• sanitization standard: remove or obfuscate anything matching email patterns, phone number formats (10-14 digits or (xxx) xxx-xxxx), ssn patterns (xxx-xx-xxxx), credit card patterns (16-19 digits with or without hyphens), api key patterns (alphanumeric strings prefixed with known key names like "sk_", "pk_", "api_key"), and ip addresses.
• data location: same as success case.

internal/non-user-facing output:

• log all url validation failures, health check failures, auth errors (401), and service errors (5xx/timeout).
• never log the original pii, redacted items, or the original field from the api response.
• log only metadata: redacted_count, unique labels detected, response status code, and fallback reason if applicable.

outcome signal

• skill worked: the user receives a response with a warning banner (if pii was found) or no warning (if none found), and the response does not contain redacted pii. user can verify by searching for email addresses, phone numbers, ssns, etc., in the response and finding none.
• fallback activated (service down): user receives a response prefixed with "⚠️ Automated PII scanning was unavailable..." and manually sanitized content. this signals that the automated redactor was not available.
• auth error (401): operator receives an alert in logs indicating token mismatch. the response is not sent to the user. operator must fix the token configuration.
• configuration error (invalid url): operator receives a log error indicating url validation failure. the response is not sent. operator must fix the clawguard_url to point to a localhost or trusted internal https endpoint.
• chunking worked (large response): response exceeds 50,000 chars but is successfully split, redacted in chunks, and reassembled. user sees the concatenated redacted text with a single warning banner summarizing all detected labels across all chunks.

credits: original skill authored by m-newhauser at clawhub. clawguard-pii package maintained at https://github.com/anthropics/clawguard-pii. model: nvidia/gliner-pii under nvidia open model license.