OpenClaw Security PII Audit

Multi-region async PII detection for OpenClaw sessions. Scans user input, prompts, context, and knowledge base content for sensitive personal data across CN,...

Security Scan

The skill's code, instructions, and resource access match its stated purpose (local PII detection and NDJSON audit logging) and do not request unrelated credentials or perform network exfiltration.

Purpose & Capability

Name/description (PII audit across multiple regions) matches the included detectors, sampling/cache logic, NDJSON logging, and cleanup scripts. The detectors implement PHONE/EMAIL/PERSON_NAME/ADDRESS/PASSPORT/BANK_CARD/NATIONAL_ID/SOCIAL_ACCOUNT as advertised; regional rules and checksums in references/patterns.md align with detector code.

Instruction Scope

SKILL.md instructs the agent to submit content (input/prompt/context/knowledge_base) to the audit_worker, prefer file-based background scans, and never block the main response. That scope is consistent with a PII-audit skill, but it inherently requires the caller to decide what conversation/context/KB content to feed the script. If the agent or caller supplies content from other skills, those other skills' data may be scanned and written to local audit logs (masked and hashed). The README and code explicitly warn about not passing PII on the command line and recommend using --file + --delete-after-read.

Install Mechanism

This is instruction + bundled Python scripts (no install spec). The code is pure Python stdlib (no external download or packages) and writes only to a local audit directory. No installers, remote downloads, or extracted archives are present.

Credentials

The skill does not require credentials or environment variables. It optionally respects OPENCLAW_AUDIT_DIR to override output location (documented). There are no requests for unrelated secrets or access to other services.

Persistence & Privilege

always:false and user-invocable:true (normal). The skill writes local NDJSON logs and a local scan cache (.scan-cache.json) within its audit directory; this is appropriate for a local audit tool. It does not modify other skills' configs or request system-wide privileges.

Assessment

This skill appears to do what it says: local PII scanning with per-source sampling, masked previews, and NDJSON audit files. Before installing, consider: (1) where the audit directory will be (set OPENCLAW_AUDIT_DIR if you need a specific location and ensure write permissions), (2) audit files and the cache contain hashes and masked previews — treat the audit directory as sensitive and apply your retention/policy controls, (3) the skill relies on callers to choose which content to scan; avoid feeding it secrets you do not want written even in masked form, and (4) review retention/cleanup configuration (default 7 days) to ensure it meets your compliance needs. No network exfiltration, secret-env requests, or surprising install steps were found in the bundle.

OpenClaw Security - PII Audit Skill

Multi-region async PII detection engine for OpenClaw sessions. Detects 8 categories of sensitive personal data across 10 country/region jurisdictions and logs audit events locally as NDJSON.

中文速览（PII 审计）

基本信息

• 技能名称：openclaw-security
• 能力：多区域异步 PII 检测，支持后台审计与本地合规留痕

检测范围

• 8 类标签：PHONE / EMAIL / PERSON_NAME / ADDRESS / PASSPORT / BANK_CARD / NATIONAL_ID / SOCIAL_ACCOUNT
• 10 区域：CN / US / AU / SG / MY / TH / ID / DE / UK / FR（支持 +CC 国际手机号）
• 来源类型：input / prompt / context / knowledge_base

关键规则

• 风险分级：high（证件/银行卡或组合信息），low（单一弱标识）
• 智能采样：input 100%（5m），prompt 20%（24h），context 20%（1h），knowledge_base 100%（24h）
• 调用方无需自行判断是否跳过扫描；如需强制扫描，使用 --no-cache
• 后台扫描禁止 --text，请使用 --file + --delete-after-read
• 输入上限 32,768 字符，超限截断并记录 truncated: true
• 审计结果本地 NDJSON 落盘，默认保留 7 天，可 cleanup.py --dry-run 先演练

Quick Start

Scan via file (recommended for background / automated scans):

python scripts/audit_worker.py --session-id SESSION_001 --source-type input --file content.txt

Scan via file + auto-delete (secure temp-file workflow):

python scripts/audit_worker.py --session-id SESSION_001 --source-type input --file tmp_scan.txt --delete-after-read

Scan via stdin:

echo "张三的手机号是13812345678" | python scripts/audit_worker.py --session-id SESSION_001 --source-type input

Quick manual test (WARNING: content visible in process list):

python scripts/audit_worker.py --session-id S001 --source-type input --text "short test" --json

Source Types

• input — User input text
• prompt — System or user prompts
• context — Conversation context
• knowledge_base — Knowledge base content

Detection Labels

PHONE, EMAIL, PERSON_NAME, ADDRESS, PASSPORT, BANK_CARD, NATIONAL_ID, SOCIAL_ACCOUNT

Supported Regions

CN, US, AU, SG, MY, TH, ID, DE, UK, FR (+ INTL via +CC phone prefix)

Risk Levels

• high: NATIONAL_ID / PASSPORT / BANK_CARD detected, or combination of PERSON_NAME + contact info + ADDRESS
• low: Single weak identifier (EMAIL, SOCIAL_ACCOUNT, PHONE alone)

Smart Sampling

The audit worker includes built-in smart sampling to efficiently handle large contexts:

• User input (input): 100% scan rate, 5-min cache TTL — every user message is scanned, but identical repeats within 5 minutes are skipped.
• System prompts (prompt): 20% scan rate, 24-hour cache TTL — prompts rarely change; first scan is cached for 24 hours.
• Conversation context (context): 20% scan rate, 1-hour cache TTL — context overlaps heavily; only sample 1 in 5 submissions.
• Knowledge base (knowledge_base): 100% first-scan rate, 24-hour cache TTL — static content is fully scanned once, then deduped for 24 hours.

Bypass sampling for manual / forced scans:

python scripts/audit_worker.py --session-id S001 --source-type context --text "text" --no-cache

Async Audit Workflow

When auditing session content as a background task:

1. Respond to user first — never block the main response for audit.
2. Feed all content types — the script internally decides whether to actually scan based on sampling config and cache. The Agent does not need to decide when to skip.
3. Use temp-file + --delete-after-read — NEVER pass content via --text in background scans. Write content to a temp file, pass --file, and let the script auto-delete it.
4. Run audit in background:

# Step 1: Write content to temp file (no PII in command-line args)
$tmpFile = [System.IO.Path]::GetTempFileName()
[System.IO.File]::WriteAllText($tmpFile, $userInput, [System.Text.Encoding]::UTF8)

# Step 2: Background scan — script reads and deletes the temp file
Start-Process -NoNewWindow -FilePath python -ArgumentList "scripts/audit_worker.py --session-id $sid --source-type input --file $tmpFile --delete-after-read"

# Same pattern for other source types:
$tmpPrompt = [System.IO.Path]::GetTempFileName()
[System.IO.File]::WriteAllText($tmpPrompt, $systemPrompt, [System.Text.Encoding]::UTF8)
Start-Process -NoNewWindow -FilePath python -ArgumentList "scripts/audit_worker.py --session-id $sid --source-type prompt --file $tmpPrompt --delete-after-read"

5. Review results: openclaw-security-audit/YYYY-MM-DD/events.ndjson
6. All outcomes (detected, clean, skipped) are logged for complete audit trail.

Retention

Default: 7 days. Cleanup:

python scripts/cleanup.py --days 7

Dry run first:

python scripts/cleanup.py --days 7 --dry-run

Input Size Limit

Maximum input: 32,768 characters (32K). Content exceeding this limit is truncated to the first 32K characters. The audit record carries truncated: true and original input_chars count.

Audit Record Schema

Every scan invocation writes an NDJSON record — including clean and skipped outcomes.

Each NDJSON line contains:

• event_id — UUID
• session_id — Caller-provided session ID (required)
• source_type — One of: input, prompt, context, knowledge_base
• status — detected, clean, or skipped
• labels — Array of detected PII types (detected only)
• regions — Array of matched regions/country codes (detected only)
• risk_level — high or low (detected only)
• matched_count — Number of PII matches
• matches — Array of {label, confidence, masked_preview, region} (detected only)
• content_hash — SHA256 prefix for dedup (no raw content stored)
• input_chars — Original input size in characters
• truncated — Whether input was truncated to 32K
• created_at — ISO 8601 UTC timestamp

Safety Rules

• NEVER store raw sensitive values — only masked previews + content hash
• NEVER pass content via --text in background scans — use --file + --delete-after-read
• Audit logs are local-only, never transmitted externally
• All file I/O uses UTF-8 encoding explicitly, with file locking for concurrent safety
• No external dependencies — stdlib only
• Input capped at 32K characters to prevent resource exhaustion

Configuration

Environment variable override for audit output directory:

$env:OPENCLAW_AUDIT_DIR = "C:\path\to\custom\audit\dir"

See references/patterns.md for detection pattern details.