---
name: pii-guard
description: "Personally identifiable information (PII) leak prevention for EverClaw. Scans outbound content against configurable PII patterns before git push, email, social media, ClawHub publishing, GitHub interactions, or any external data transmission. Provides git pre-push hooks, CLI scanning tools, and hard-block enforcement with user override capability. Use when checking content for PII before external actions, adding new protected patterns, configuring git pre-push hooks, or auditing data leak prevention."
---

# PII Guard — Personal Data Leak Prevention

## Purpose
Prevents personal identifiable information (PII) from being sent to external services. This skill MUST be checked before any outbound action that transmits data externally.

## When This Fires
**Mandatory check before:**
- `git push` (any repo)
- Sending emails
- Posting to social media (X/Twitter, Moltbook, etc.)
- Publishing to ClawHub
- Creating/updating GitHub issues, PRs, discussions, or comments
- Any `message` action to external channels with file attachments
- Any `web_fetch` POST or form submission
- Any `exec` command that sends data externally (curl POST, scp, rsync, etc.)

## How It Works

### 1. Pattern File
All protected patterns live in the workspace:
```
~/.openclaw/workspace/.pii-patterns.json
```
This file is **NEVER committed** — it contains the very data it protects.

### 2. Scanning
The scanner checks content against all patterns in these categories:
- `names` — Protected personal names
- `emails` — Protected email addresses
- `phones` — Protected phone numbers (all formats)
- `wallets` — Protected blockchain addresses
- `organizations` — Protected org/church/school names
- `people` — Protected associate/contact names
- `websites` — Protected personal domains
- `keywords` — Any other protected strings

### 3. Behavior: HARD BLOCK
When PII is detected:
1. **STOP** — Do not proceed with the external action
2. **REPORT** — Tell the user exactly what was found and where
3. **WAIT** — Only proceed if the user explicitly confirms after reviewing

Error format:
```
🚫 PII GUARD: Blocked — personal data detected

Found in: <filename or content description>
Match: "<the matched pattern>"
Category: <names|emails|phones|etc>

Action blocked: <what was about to happen>
To proceed: Remove the PII or explicitly confirm override.
```

### 4. Git Pre-Push Hook
A global git hook is installed at:
```
~/.openclaw/workspace/scripts/git-hooks/pre-push
```
Configured via: `git config --global core.hooksPath ~/.openclaw/workspace/scripts/git-hooks`

This runs automatically on every `git push` across ALL repos on this machine.
- Scans the diff being pushed (not just HEAD)
- Blocks push if PII detected
- Can be bypassed with `git push --no-verify` (use with extreme caution)

### 5. Agent Integration
The agent should call `pii_scan` before external actions:

```bash
# Scan a file
~/.openclaw/workspace/scripts/pii-scan.sh <file_or_directory>

# Scan stdin
echo "some content" | ~/.openclaw/workspace/scripts/pii-scan.sh -

# Scan a string
~/.openclaw/workspace/scripts/pii-scan.sh --text "check this string"
```

Exit codes:
- `0` — Clean, no PII found
- `1` — PII detected (blocked)
- `2` — Error (patterns file missing, etc.)

## Adding New Patterns
Edit `~/.openclaw/workspace/.pii-patterns.json` and add entries to the appropriate category array. Changes take effect immediately — no restart needed.

## Security Notes
- `.pii-patterns.json` must NEVER be committed to any repo
- The patterns file itself contains PII — treat it as sensitive
- The hook and scan scripts are safe to publish (they contain no PII)
- When in doubt, scan first