金丝雀代理安全触发系统

面向 AI 代理的安全监控与触发检测机制。防范未授权文件访问、危险命令执行及过度活跃行为。在发生严重违规时自动中止运行。蜜罐式触发器可检测窥探行为。

面向 AI 代理的安全监控与触发检测机制。

防范未授权文件访问、危险命令执行及过度活跃行为。在发生严重违规时自动中止运行。蜜罐式触发器可检测窥探行为。

功能说明

Canary 提供三层代理安全保障：

1. 操作监控 — 在执行前检查文件路径与命令
2. 触发文件（Tripwire Files） — 不应被任何代理访问的蜜罐文件
3. 审计日志（Audit Trail） — 完整的操作日志与模式识别能力

核心功能

受保护路径：

• 阻止访问敏感目录（如 /etc/、~/.ssh/ 等）
• 支持自定义受保护路径列表
• 细粒度操作控制（读取、写入、删除）

禁用模式：

• 基于正则表达式的危险命令匹配
• 可识别 rm -rf /、chmod 777、curl | sh 等高危命令
• 可扩展的模式库

速率限制：

• 限制文件操作、网络请求、命令执行频次
• 可配置时间窗口与阈值
• 防止失控代理持续运行

自动中止：

• 在违规次数达到阈值后自动停止代理
• 避免级联故障扩大影响
• 重启需人工审核确认

触发文件：

• 创建不应被访问的蜜罐文件
• 检测对文件的修改、删除或访问行为
• 通过哈希校验保障文件完整性

审计日志：

• 完整记录所有操作行为
• 违规历史记录
• 模式识别（高频违规、重复目标、时间聚集性等）
• 支持导出为 JSON 或 Markdown 格式

快速上手

安装

零依赖！仅需 Python 3.7+ 标准库。

# 复制配置示例
cp config_example.json config.json

# 使用编辑器修改配置，添加需保护的路径
nano config.json

基础用法

from canary import CanaryMonitor

# 初始化监控器
canary = CanaryMonitor('config.json')

# 访问前检查路径安全性
is_safe, reason = canary.check_path('/etc/passwd', 'read')
if not is_safe:
    print(f"已拦截：{reason}")
    exit(1)

# 执行前检查命令安全性
is_safe, reason = canary.check_command('rm -rf /')
if not is_safe:
    print(f"已拦截：{reason}")
    exit(1)

# 获取当前状态
status = canary.get_status()
print(f"违规次数：{status['violation_count']}/{status['halt_threshold']}")

CLI 用法

# 查看当前状态
python3 canary.py status

# 检查某路径是否允许访问
python3 canary.py check-path --path /etc/passwd --operation read

# 检查某命令是否允许执行
python3 canary.py check-command --command "rm -rf /"

# 重置监控状态（清空违规记录）
python3 canary.py reset

触发文件

创建不应被访问的蜜罐文件：

# 创建触发文件
python3 canary_tripwire.py create 
  --path ~/.secrets/fake-api-key.txt 
  --severity critical 
  --description "用于检测凭证窃取行为的蜜罐"

# 列出全部触发文件
python3 canary_tripwire.py list

# 检查是否有触发文件被访问
python3 canary_tripwire.py check

# 查看告警历史（最近 10 条）
python3 canary_tripwire.py alerts --limit 10

# 删除指定触发文件
python3 canary_tripwire.py remove --path ~/.secrets/fake-api-key.txt

Python API

from canary_tripwire import TripwireManager

manager = TripwireManager()

# 创建触发文件
manager.create_tripwire(
    path='~/.aws/fake-credentials',
    severity='critical',
    description='用于检测 AWS 凭证访问行为'
)

# 检查全部触发文件
triggered = manager.check_tripwires()
if triggered:
    print(f"⚠️  共 {len(triggered)} 个触发文件已被触发！")
    for alert in triggered:
        print(f"  - {alert['path']}：{alert['event']}")

审计报告

分析日志并生成安全报告：

# 生成摘要报告
python3 canary_audit.py summary

# 按严重等级查看违规记录
python3 canary_audit.py violations --severity critical

# 查看最近 24 小时事件时间线
python3 canary_audit.py timeline --hours 24

# 检测可疑行为模式
python3 canary_audit.py patterns

# 导出完整报告
python3 canary_audit.py export --output report.json --format json
python3 canary_audit.py export --output report.md --format markdown

Python API

from canary_audit import CanaryAuditor

auditor = CanaryAuditor('canary.log')

# 生成摘要报告
summary = auditor.generate_summary_report()
print(f"总违规次数：{summary['total_violations']}")

# 获取严重等级为 critical 的违规记录
critical = auditor.get_violations_by_severity('critical')

# 检测行为模式
patterns = auditor.detect_patterns()
if patterns['rapid_violations']:
    print("⚠️  检测到高频违规序列！")

# 导出报告
auditor.export_report('safety-report.md', format='markdown')

配置说明

全部配置项详见 config_example.json。

关键配置项

{
  "protected_paths": [
    "/etc/",
    "~/.ssh/",
    "~/critical-data/"
  ],
  "forbidden_patterns": [
    "rm\s+-rf\s+/",
    "chmod\s+777",
    "curl.*\|\s*sh"
  ],
  "halt_threshold": 5,
  "rate_limits": {
    "file_operations": {"limit": 100, "window": 60},
    "command_executions": {"limit": 20, "window": 60}
  }
}

集成示例

与代理运行时集成

from canary import CanaryMonitor

canary = CanaryMonitor('config.json')

def safe_file_read(path):
    """使用 Canary 检查后读取文件。"""
    is_safe, reason = canary.check_path(path, 'read')
    if not is_safe:
        raise PermissionError(reason)
    
    with open(path, 'r') as f:
        return f.read()

def safe_command(cmd):
    """使用 Canary 检查后执行命令。"""
    is_safe, reason = canary.check_command(cmd)
    if not is_safe:
        raise PermissionError(reason)
    
    import subprocess
    cmd_list = cmd.split() if isinstance(cmd, str) else cmd
    return subprocess.run(cmd_list, capture_output=True)

部署前检查

# 部署代理前，验证 Canary 配置是否就绪
from canary import CanaryMonitor

canary = CanaryMonitor('config.json')

# 验证受保护路径是否已配置
status = canary.get_status()
if status['protected_paths_count'] == 0:
    print("⚠️  未配置任何受保护路径！")
    exit(1)

# 测试触发文件检测能力
from canary_tripwire import TripwireManager
manager = TripwireManager()

# 创建测试触发文件
manager.create_tripwire('/tmp/canary-test.txt', severity='high')

# 验证其存在性
triggered = manager.check_tripwires()
if not any(t['path'] == '/tmp/canary-test.txt' for t in triggered):
    print("✅ 触发文件系统运行正常")

# 清理测试文件
manager.remove_tripwire('/tmp/canary-test.txt', delete_file=True)

典型应用场景

1. 自主代理安全防护

将 Canary 与自主代理协同部署，以防止：

• 误删系统关键文件
• 凭据泄露
• 失控命令持续执行

2. 多代理系统

为每个代理分配独立的 Canary 实例，并配置差异化规则：

• 研究型代理：限制网络访问权限
• 编码型代理：禁止生产环境部署操作
• 运维型代理：授予完全访问权限，但启用严格审计

3. 开发与测试阶段

在代理开发过程中使用 Canary：

• 早期捕获危险行为模式
• 验证速率限制策略效果
• 确保各项安全机制按预期工作

4. 生产环境监控

在生产环境中运行 Canary：

• 实时违规告警
• 满足合规性要求的审计日志
• 异常行为模式识别

架构图

┌─────────────────┐
│   Your Agent    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────────┐
│ CanaryMonitor   │◄────►│  config.py       │
│ (canary.py)     │      │  (your rules)    │
└────────┬────────┘      └──────────────────┘
         │
         ├─────► canary.log (action log)
         │
         ▼
┌─────────────────┐      ┌──────────────────┐
│ TripwireManager │◄────►│ .canary_tripwires│
│ (tripwire.py)   │      │ (honeypot files) │
└────────┬────────┘      └──────────────────┘
         │
         └─────► alerts.log
         
         
┌─────────────────┐
│ CanaryAuditor   │───► reports (JSON/MD)
│ (audit.py)      │
└─────────────────┘

最佳实践

初始策略宜保守

从严格规则起步，后续根据需要逐步放宽：

protected_paths = [
    '/',  # 初期保护整个文件系统
]

halt_threshold = 3  # 设置较低阈值，便于尽早发现问题

战略性部署触发文件

将触发文件置于敏感位置：

• 伪造的凭据文件
• 空的 “secrets” 目录
• 诱饵式配置文件

定期审阅日志

# 每日审计
python3 canary_audit.py summary

# 每周深度分析
python3 canary_audit.py patterns
python3 canary_audit.py export --output weekly-report.md --format markdown

验证配置有效性

# 验证 Canary 是否能正确拦截预期行为
canary = CanaryMonitor('config.json')

# 以下调用均应返回 False
assert not canary.check_path('/etc/passwd', 'delete')[0]
assert not canary.check_command('rm -rf /')[0]
assert not canary.check_command('chmod 777 /tmp')[0]

print("✅ Canary 配置验证通过")

限制条件

详细信息请参阅 LIMITATIONS.md。

主要约束：

• 模式匹配基于正则表达式（非语义分析）
• 无内置告警机制（仅输出日志）
• 触发文件可检测访问行为，但无法判断访问意图
• 速率限制作用于单次会话（服务重启后不保留状态）

许可证

MIT License — 详见 LICENSE

作者： Shadow Rose

为何需要此工具

AI 代理可在极短时间内造成严重破坏：

• 一条错误命令即可删除关键文件
• 失控循环可能耗尽系统资源
• 遭入侵的代理可能窃取敏感凭据

Canary 提供纵深防御能力：

• 预防性： 在危险操作发生前即予以拦截
• 检测性： 触发文件可捕获窥探类行为
• 取证性： 提供完整审计日志，支撑事后分析

轻量、零依赖、开箱即用的自主代理安全方案。

⚠️ 安全提示 — 配置文件

配置从 JSON 文件加载。该方式安全可靠，不涉及代码执行。

• 加载前会对配置路径的存在性与大小进行校验（上限 1MB）
• 必须为 .json 文件 — 若传入非 JSON 路径，CanaryMonitor 将抛出 ValueError
• 建议将配置纳入版本控制管理，并视其为安全策略的一部分

⚠️ 安全提示 — 触发文件部署

• 路径完全解析 — ~ 及相对路径在创建与查找前均通过 Path.expanduser().resolve() 展开。'~/.aws/fake-credentials' 将实际置于您的主目录下，而非字面意义的 ~ 路径。
• 仅使用诱饵路径 — 切勿将触发文件指向真实且含敏感数据的文件。触发文件本质是蜜罐，应视为诱饵而非防护手段。
• create_tripwire 不覆盖已有文件 — 该方法会检查目标路径是否存在文件，若存在则拒绝执行。请为触发文件预留专用空路径。
• 先在沙箱中测试 — 部署前请确认日志、触发文件及注册表文件的实际生成位置；在隔离环境中验证受保护路径与自动中止行为是否符合预期。
• 保护日志与告警目录 — 设置合适的文件系统权限，确保告警日志不可被全局读取。Canary 输出明文日志，请据此限制访问权限。
• Canary 仅在被显式调用时生效 — 其非操作系统级强制机制。生产部署时，应结合容器、文件系统权限及 auditd 等多重防护措施。

⚠️ 免责声明

本软件按“现状”提供，不附带任何形式的明示或暗示担保。

使用风险由您自行承担。

• 作者不对因本软件的使用或误用所导致的任何损害、损失或后果承担责任，包括但不限于经济损失、数据丢失、安全漏洞、业务中断或任何间接/衍生损害。
• 本软件不构成财务、法律、交易或专业建议。
• 用户须自行评估本软件是否适用于其具体用例、运行环境及风险承受能力。
• 不保证本软件在准确性、可靠性、完整性或特定用途适用性方面的表现。
• 作者不对第三方在获取本软件后进行的修改、分发或再利用行为负责。

下载、安装或使用本软件，即表示您已阅读并接受本免责声明，且同意完全自行承担使用风险。

安全免责申明：本软件提供的是补充性安全措施，不能替代专业的安全审计、渗透测试或合规框架。没有任何软件能够确保对所有威胁实现完全防护。在受监管行业（如医疗、金融、法律）中使用的用户，应咨询合格的安全专家，并独立验证其是否符合相关法规（GDPR、HIPAA、SOC2 等）要求。

支持与链接

基于 OpenClaw 构建 — 感谢您让这一切成为可能。

🛠️ 需要定制化服务？ 定制 OpenClaw 代理与技能，起价 $500。只要您能描述需求，我就能为您构建 → 在 Fiverr 上雇佣我

📦 安装提示： ClawHub 上的 slug canary 已被占用。
请使用如下命令安装本技能：clawhub install canary-sr