CCPA Guardrail

CCPA 合规护栏 (ccpa-guard) v1.0.0。在 AI 应用输入/输出链路中实时检测 CCPA/CPRA 语境下的个人信息，按风险分级脱敏或阻断，供 Agent 主动调用。 Use when: 需要在 Agent 处理用户输入或返回结果前，实时拦截/脱敏加州消费者个人信息；防止 SSN、信用卡、加州驾照、精确地理位置、生物识别数据、商业信息等流入大模型或被输出泄露；为 AI 应用加装符合 CCPA/CPRA 的运行时护栏。核心能力： - 🛡️ 实时检测 SSN、信用卡（Luhn）、美国电话、银行路由号、加州驾照/身份证、美国护照号、IPv4/MAC、邮箱等

Wei Wu@wwumit

Install

openclaw skills install @wwumit/ccpa-guard

🛡️ CCPA Guardrail —— CCPA 合规护栏 v1.0.0

概述

ccpa-guard 是面向 AI 应用的运行时合规护栏。它在 Agent 处理用户输入、或向用户返回输出之前，实时检测其中的个人信息，并按风险等级执行脱敏或阻断。

与"事后审计"类工具（如合规自查、文件扫描）不同，护栏解决的是事中问题：每一次调用能不能放行、要不要脱敏、是否必须阻断。二者互补，共同覆盖 AI 应用"事前自查 + 事中防护"的合规链路。

为什么是本地护栏

护栏是低延迟、高频的运行时组件，且处理的正是最敏感的数据。因此 ccpa-guard 坚持纯本地运行：检测在本机完成，敏感数据不出机器，无任何网络请求，无 eval / exec / 动态 import。这既满足运行时性能，本身也是最强的 CCPA 隐私友好特性。

快速开始

bash

# 检测并脱敏（默认动作 mask）
python3 scripts/guard.py --text "My SSN is 123-45-6789"

# 从标准输入读取（适合管道 / Agent 调用）
echo "My phone is 415-555-0123" | python3 scripts/guard.py --stdin

# 高危阻断模式：命中 high 级敏感信息则拦截，不放行
python3 scripts/guard.py --text "SSN 123-45-6789" --action block

# 结构化 JSON 输出（Agent 消费）
python3 scripts/guard.py --text "email user@example.com" --action detect --format json

# 列出可用规则包
python3 scripts/guard.py --list-profiles

Agent 调用约定

护栏设计为 Agent 主动调用的检测工具，典型接法有两处：

入口护栏（用户输入 → 模型）：把用户输入交给护栏，mask 后再送入大模型，防止个人信息流入外部模型或日志。

出口护栏（模型输出 → 用户）：把模型输出交给护栏，mask 或 block 后再返回用户，防止生成结果泄露个人信息。

护栏返回结构化裁决（--format json），关键字段：

字段	含义
`decision`	`pass` / `masked` / `blocked` / `inspect_only`
`risk_level`	本次最高风险等级 `high/medium/low/none`
`finding_count`	命中条数（已去重）
`findings[]`	每条命中的类别、等级、位置与脱敏预览（不含原文明文）
`output`	处理后的文本；`blocked` 时为 `null`

注意：findings 中仅提供脱敏预览（preview），不回传敏感原文，避免护栏结果本身成为新的泄露面。

三种动作

动作	行为	适用
`detect`	仅检测并报告，不改动文本	审计、观察、灰度
`mask`	脱敏后放行（默认）	大多数输入/输出防护
`block`	命中达阈值则阻断，否则脱敏	高敏场景、强合规要求

阻断阈值由 --block-on 控制（high / medium / low），默认 high：默认脱敏放行、仅高危阻断，兼顾可用性与安全。

检测范围（ccpa v1.0.0）

结构性模式（个人信息）：

US Social Security Number (SSN) — 全脱敏
美国电话号 (NANPA 格式)
加州驾照号码（1字母 + 7数字）
加州身份证号码（9位数字）
美国护照号码（9位数字）
美国银行路由号码（9位数字）
信用卡号（Luhn 校验）
Email 地址
IPv4 地址
MAC 地址

关键词线索（CPRA 敏感个人信息 — Cal. Civ. Code § 1798.140(v)(2)）：

受保护分类：种族、民族、残疾、医疗状况
精确地理位置：GPS 坐标、地理定位
生物识别信息：指纹、人脸识别、生物数据
商业信息：购买历史、交易记录、信用评分
互联网活动：浏览历史、搜索历史
就业与教育：雇佣记录、教育记录

规则与内核分离

检测内核（scripts/guard.py）不含任何行业规则；规则集中在 scripts/rules/ 下的规则包。ccpa 版使用自包含的 ccpa 规则包，覆盖 US/加州个人数据格式与 CCPA/CPRA 敏感个人信息类别。内核逻辑在所有版本间完全复用。

安全与约束

纯本地运行，无任何网络请求、遥测或回调
无 eval / exec / 动态 import；规则通过显式映射加载，便于审计
不写入用户指定之外的文件；不修改自身代码
检测结果不回传敏感原文，仅提供脱敏预览
全部为可读 Python，无混淆、无二进制依赖

⚠️ 法律声明

免责条款

使用本 ccpa-guard 护栏前请仔细阅读以下条款：

非法律建议：本工具提供的检测、脱敏与拦截结果仅供参考， 不构成法律建议或合规证明，不具备法律效力。
无绝对保证：个人信息形态多样，基于正则与关键词的检测 无法保证 100% 识别，可能存在漏报或误报。用户不应将其作为唯一或最终的合规保障手段。
按原样提供：本工具按"原样"（AS IS）提供，不作任何明示或暗示的保证，包括适销性、特定用途适用性或检测完整性。
责任限制：在法律允许的最大范围内，开发者对使用或无法使用本工具产生的任何损失不承担责任。
用户责任：用户对其 AI 应用的合规性负全责，重大合规决策应咨询专业法律顾问，并结合组织制度、技术措施综合落实。
数据安全：本工具本地运行，处理数据留在用户设备上；用户应自行负责数据的备份与安全。

知识产权

本工具基于 MIT 许可证开源。所引用的法律法规原文（CCPA / CPRA）属政府公开信息，版权归原制定机关，用户应以官方发布版本为准。

使用限制

✅ 允许：作为 AI 应用运行时防护的辅助手段、脱敏预处理、合规体系的一环
❌ 禁止：作为法律证据或合规证明提交监管部门、替代专业法律咨询、用于规避法律义务、移除本声明后分发

管辖法律

本声明受中华人民共和国法律管辖。因本工具引发的争议，应先友好协商；协商不成的，提交开发者所在地有管辖权的法院解决。

CCPA 合规护栏系列 · CCPA版　为 AI 应用装上实时合规护栏