OpenClaw Security

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 requirements are consistent with a local, multi-region PII-audit tool; it does not request unrelated credentials or install remote components, but it does write/read local temp files and audit logs so you should review disk/retention and invocation practices before enabling it.

Purpose & Capability

Name/description (PII detection for OpenClaw sessions) matches the included code: detectors for phone/email/national id/passport/bank card/name/address/social accounts, smart-sampling, cache, NDJSON audit sink. No unrelated credentials, binaries, or external services are requested.

Instruction Scope

SKILL.md tells the agent to run local Python scripts, write session content to temp files, and start background processes. Those instructions stay within the stated purpose (local scanning and logging). Note: the workflow intentionally uses temp files and explicit --file + --delete-after-read to avoid CLI exposure; the agent (or host) will need filesystem access and the caller supplies a session_id that will be recorded in audit records.

Install Mechanism

No install spec is provided and the project claims zero external dependencies (pure stdlib). The skill ships Python source files — nothing is downloaded or executed from remote URLs during normal use.

Credentials

No required environment variables or secrets are declared. Optional env var (OPENCLAW_AUDIT_DIR) can change storage location; nothing in the code requests cloud credentials or unrelated tokens.

Persistence & Privilege

always:false and no special platform privileges are requested. The skill writes audit logs and a file-backed cache under its own audit directory and uses file locks for concurrency. Because it may be invoked autonomously (platform default), consider whether you are comfortable with background scanning writing local audit records and cache files.

Assessment

This skill appears to be what it says: a local, multi-region PII scanner implemented in pure Python that logs masked results to NDJSON. Before installing, consider: (1) audit storage location — OPENCLAW_AUDIT_DIR defaults to a subdirectory of the repo; change it if you want logs elsewhere and confirm retention (default 7 days) meets your policy, (2) disk traces — background scans write/read temp files and a cache (.scan-cache.json) so ensure the host filesystem and backups are acceptable, (3) process-list leakage — avoid using --text in background runs as the SKILL.md warns, (4) session_id sensitivity — the session_id you pass is recorded and could link logs to users, (5) review file_lock.py and cleanup.py to confirm deletion and pruning behavior meets your expectations, and (6) verify the source/repo/trustworthiness since registry metadata shows Source: unknown even though README references a GitHub URL. If you want stronger guarantees, run the scripts in a sandbox, exercise --dry-run cleanup, and inspect that no raw PII is written (only masked previews and a truncated content-hash are stored).

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.