@yidun/agent-guard

v1.0.4

Published

a day ago

Netease Yidun Agent Guard - AI Agent security scanning, risk management and runtime protection

0High
0Medium
0Low

Agent 安全项目 🛡️

Agent 安全最佳实践 - 为 Skill/MCP 插件生态提供企业级静态审计与运行时防护

📖 项目简介

随着 AI Agent 的爆发性增长和风险的确定性增强，Agent 安全市场呈现巨大机遇。本项目旨在：

🎯 运行时安全: 混合Hook架构（TypeScript + Python IPC）实时监控
🔍 供应链安全: 两阶段流水线（Phase 1规则 + Phase 2 LLM）精准审计
🤖 智能防御: 上下文增强检测 + Fail-Secure 策略驱动
☁️ 开源友好: 融合 37,394 行开源代码精华，企业级实现

🎯 v0.1 版本亮点 ⚡

架构升级: 两阶段流水线 + 插件化分析器 + 策略驱动 + 混合Hook架构

🏗️ 核心架构

FR-02: 静态代码安全审计（两阶段流水线）

参考: Cisco Skill Scanner (29,830行) + Agent-Scan (5,278行)

Phase 1: 快速规则扫描 (< 1秒, 非LLM)
- ✅ 20条 YAML 规则库（可扩展到80+）
- ✅ 命令安全分级（SAFE/LOW/MEDIUM/HIGH/CRITICAL）
- ✅ 污点分析（Source → Sink）
- ✅ Toxic Flow 检测（untrusted → private → public）
- ✅ ZIP 安全检查（Zip bomb/路径穿越防护）
Phase 2: LLM 语义分析 (< 3秒, 上下文增强)
- ✅ 四维度威胁检测（RCE/供应链/Prompt注入/数据窃取）
- ✅ Enrichment Context（Phase 1结果 + 文件清单 + 命令分布）
- ✅ 威胁分类映射（对齐4个框架: Cisco AI/MITRE ATLAS/OWASP/NIST）
- ✅ 降级策略（API失败 → 返回Phase 1结果）

FR-03: 运行时行为监控（混合Hook架构）

参考: ClawBands (2,286行 TypeScript) + Agent-Scan 策略引擎

TypeScript Hook 层 (OpenClaw/Cursor 插件)
- ✅ beforeToolCall() 拦截
- ✅ IPC 通信（stdin/stdout JSON Lines）
- ✅ 500ms 超时 + Fail-Secure
Python 策略引擎层
- ✅ 3预设策略（strict/balanced/permissive）
- ✅ CFI 检查（控制流完整性）
- ✅ DFI 追踪（敏感数据外发检测）
- ✅ Intent Aligner（意图对齐）
- ✅ 审计日志（JSON Lines, append-only）

📊 关键指标

Phase 1 扫描速度: < 1秒 (非LLM规则引擎)
Phase 2 完整扫描: < 3秒 (含LLM语义分析)
IPC 通信延迟: < 50ms (TypeScript ↔ Python)
监控总延迟: < 500ms (Hook拦截 + 策略评估)
检出率: ≥ 95% | 误报率: < 5%

🚀 核心特性

✅ 已完成（Sprint 1 - 基础框架）

✅ 项目脚手架: 完整目录结构 + 配置文件
✅ 核心数据模型: 15+ Pydantic 模型，96.72% 测试覆盖率
✅ 配置管理系统: YAML + 环境变量，94% 测试覆盖率
✅ 结构化日志: structlog + 敏感数据自动脱敏
✅ 存储系统: SQLite 威胁情报库 + JSON Lines 审计日志
✅ CLI 框架: 5 个命令 (scan/armor/config/logs/version)
✅ 单元测试: 17/17 测试通过，42% 代码覆盖率

🚧 进行中（Sprint 1 - Week 1）

🚧 测试完善: 补充 logger/storage 单元测试 (目标 80%+)
🚧 代码质量: black/isort/mypy/flake8 检查
🚧 CI/CD 配置: GitHub Actions 自动化测试

⏳ 待开始（Sprint 2 - Week 3-4）

⏳ FR-02 静态审计引擎: SkillLoader + 20条规则 + 两阶段流水线
⏳ LLM 审计: 上下文增强 + 四维度威胁检测
⏳ 报告生成: JSON/HTML/Markdown 多格式输出

🔜 未来阶段

🔜 FR-03 运行时监控: TypeScript Hook + Python 策略引擎 (Sprint 3)
🔜 风险评估: 语义分析、行为建模、风险评分
🔜 行为拦截: 高危操作实时阻断、决策归因
🔜 数据防护: PII 检测、数据脱敏、泄露防护
🔜 SaaS 平台: 资产管理、风险看板、云端大脑
🔮 自主 AI: 自动扫描、归因、修复、预测性防护

📚 文档导航

🌟 v0.1 核心文档（架构升级）

| 文档 | 说明 | 行数 | 更新日期 | |-----|------|------|---------| | 📊 开源分析 | 三大项目深度分析 | 1,439 | 2026-03-05 | | 🏗️ 设计文档 v0.1 | 混合架构设计（TS+Python） | 1,687+ | 2026-03-05 | | 📋 任务清单 v0.1 | Sprint 2 & 3 详细任务 | 999 | 2026-03-05 | | 🗓️ 实施计划 v0.1 | 12周两阶段流水线计划 | 692 | 2026-03-05 | | 📝 需求文档 v0.1 | FR-02 & FR-03 详细需求 | - | 2026-03-04 |

📖 完整项目文档

| 文档 | 说明 | 适合人群 | |-----|------|---------| | 📋 项目总览 | 项目全貌、进度、团队 | 所有人 | | 📝 需求文档 | 四阶段完整需求 | 产品、业务 | | 🗓️ 实施计划 | 长期时间线和里程碑 | 项目经理 | | 🔧 技术栈 | 架构设计、技术选型 | 架构师、开发 | | 🔒 威胁模型 | 威胁分析、缓解措施 | 安全工程师 |

🔧 辅助文档

🚀 快速开始 - 安装和使用指南
✅ 安装验证 - 验证报告（17/17 测试通过）
📊 脚手架报告 - 基础框架完成情况
📋 任务清单 - 当前任务和进度（实时更新）
🔐 安全决策 - 安全决策日志
🚨 安全事件 - 安全事件追踪
📖 经验教训 - 教训与改进

🏗️ 项目结构

agent-security-project/
├── CLAUDE.md                    # Claude AI 工作流配置（安全优先）
├── README.md                    # 本文件
│
├── docs/                        # 📚 完整项目文档
│   ├── opensource-analysis.md   # ⭐ 三大开源项目分析 (1,439行)
│   ├── design-v0.1.md           # ⭐ 混合架构设计 (1,687+行)
│   ├── tasks-v0.1.md            # ⭐ Sprint 任务清单 (999行)
│   ├── implementation-plan-v0.1.md  # ⭐ 两阶段流水线计划 (692行)
│   ├── requirements-v0.1.md     # FR-02 & FR-03 需求
│   ├── overview.md              # 项目总览
│   ├── requirements.md          # 完整需求（50+ 页）
│   ├── implementation-plan.md   # 长期实施计划
│   ├── tech-stack.md            # 技术栈（架构 + 选型）
│   ├── threat-model.md          # 威胁模型（STRIDE 分析）
│   └── dev-setup.md             # 开发环境配置
│
├── src/agent_security/          # 💻 源代码 (1,431+ 行)
│   ├── core/                    # 核心模块 ✅ 完成
│   │   ├── models.py            # ✅ 数据模型 (291行, 96.72%覆盖率)
│   │   ├── config.py            # ✅ 配置管理 (370行, 94%覆盖率)
│   │   ├── logger.py            # ✅ 日志系统 (200+行, 待测试)
│   │   └── storage.py           # ✅ 存储系统 (320+行, 待测试)
│   ├── scanner/                 # FR-02 静态扫描 🚧 Sprint 2
│   │   ├── loader.py            # ⏳ SkillLoader
│   │   ├── analyzers/           # ⏳ 分析器插件
│   │   ├── orchestrator.py      # ⏳ 两阶段编排器
│   │   └── rules/               # ⏳ YAML规则库
│   ├── armor/                   # FR-03 运行时监控 🚧 Sprint 3
│   │   ├── service.py           # ⏳ Python IPC 服务
│   │   ├── ipc.py               # ⏳ IPC 协议定义
│   │   ├── checkers/            # ⏳ CFI/DFI/Intent 检查器
│   │   └── policy_engine.py     # ⏳ 策略引擎
│   └── cli/                     # CLI 工具 ✅ 完成
│       └── main.py              # ✅ 5个命令 (250+行)
│
├── hooks/                       # TypeScript Hook 层 ⏳ Sprint 3
│   ├── hook-agent.ts            # ⏳ OpenClaw 插件
│   ├── armor-client.ts          # ⏳ IPC 客户端
│   └── package.json             # TypeScript 依赖
│
├── tests/                       # 🧪 测试代码 ✅ 17/17 通过
│   ├── test_core_models.py      # ✅ 10/10 passed
│   ├── test_core_config.py      # ✅ 7/7 passed
│   └── (更多测试待添加)         # 🚧 logger/storage/cli 测试
│
├── security/                    # 🔒 安全管理
│   ├── decisions.md             # 安全决策日志
│   └── incidents.md             # 安全事件追踪
│
├── tasks/                       # 📝 任务管理
│   ├── todo.md                  # ✅ 待办事项（实时更新）
│   └── lessons.md               # 经验教训
│
├── agent-security               # ✅ CLI 快捷脚本
├── pyproject.toml               # Python 依赖管理
├── pytest.ini                   # 测试配置
├── setup.sh                     # ✅ 自动化安装脚本
├── QUICKSTART.md                # ✅ 快速开始指南
├── INSTALLATION_VERIFICATION.md # ✅ 安装验证报告
└── SCAFFOLD_REPORT.md           # ✅ 脚手架完成报告

图例: ✅ 已完成 | 🚧 进行中 | ⏳ 待开始

🎯 开发路线图

v0.1: 静态审计 & 运行时监控（2026.03 - 2026.06）⏳

目标: 建立两阶段流水线 + 混合Hook架构核心能力

架构特性:

✅ 两阶段流水线: Phase 1规则引擎(<1s) + Phase 2 LLM语义(<3s)
✅ 混合Hook架构: TypeScript拦截 + Python策略引擎 (IPC通信)
✅ 上下文增强: Enrichment Context 提升检测准确率
✅ Fail-Secure: 所有错误/超时默认BLOCK

进度 (更新: 2026-03-05):

[x] 需求分析和设计文档（Week 1）✅
[x] 三大开源项目分析（ClawBands/Agent-Scan/Skill Scanner）✅
[x] 架构设计升级（两阶段 + 混合Hook）✅
[x] 核心数据模型（models.py, 96.72%测试覆盖）✅
[x] 配置管理系统（config.py, 94%测试覆盖）✅
[x] 日志系统（logger.py, 结构化日志 + 敏感数据脱敏）✅
[x] 存储系统（storage.py, SQLite + JSON Lines）✅
[x] CLI 框架（main.py, 5个命令）✅
[x] 单元测试（17/17 通过，42%覆盖率）✅
[x] 安装验证（所有导入测试通过）✅
[ ] 测试完善（logger/storage测试，目标80%覆盖率）🚧
[ ] CI/CD配置（GitHub Actions）🚧
[ ] FR-02 静态审计引擎（Week 3-4）⏳
- [ ] Phase 1: SkillLoader + 20条YAML规则 + 分析器
- [ ] Phase 2: Orchestrator + LLMAuditor + 威胁分类
[ ] FR-03 运行时监控（Week 5-6）⏳
- [ ] TypeScript Hook 插件 + Python IPC 服务
- [ ] CFI/DFI/Intent 检查器 + PolicyEngine
[ ] 集成测试与优化（Week 7-8）⏳
[ ] 攻击库建设与验证（Week 9-10）⏳
[ ] 文档完善与发布（Week 11-12）⏳

交付物:

[x] 项目脚手架 ✅
[x] 核心数据模型 v1.0 ✅
[x] 配置管理系统 v1.0 ✅
[x] 日志系统 v1.0 ✅
[x] 存储系统 v1.0（SQLite + JSON Lines）✅
[x] CLI 工具 v1.0（5个命令）✅
[x] 单元测试框架（17个测试，42%覆盖率）✅
[ ] 静态代码安全审计系统 v1.0（两阶段流水线）⏳
[ ] 运行时行为监控系统 v1.0（混合Hook架构）⏳
[ ] 20条 YAML 规则库（可扩展到80+）⏳
[ ] 威胁情报库（SQLite + 4框架分类映射）⏳
[ ] Python API v1.0 ⏳
[ ] TypeScript Hook 插件（OpenClaw/Cursor）⏳
[ ] 技术文档和使用指南 🚧
[ ] 攻击样本库 50+ ⏳

里程碑: | 时间 | 里程碑 | 状态 | |-----|--------|------| | 3.05 | 架构升级完成 | ✅ 已完成 | | 3.05 | 脚手架搭建完成 | ✅ 已完成 | | 3.05 | 核心模块完成 | ✅ 已完成 | | 3.05 | 安装验证通过 | ✅ 已完成 | | 3.28 | M1: 基础框架完成（85%） | 🟢 进行中 | | 4.11 | M2: FR-02 两阶段流水线完成 | ⚪ 待开始 | | 4.25 | M3: FR-03 混合Hook架构完成 | ⚪ 待开始 | | 5.09 | M4: 集成测试通过 | ⚪ 待开始 | | 5.23 | M5: 攻击库建设完成 | ⚪ 待开始 | | 6.06 | M6: v0.1 正式发布 | ⚪ 待开始 |

v0.2: 多源采集 & 资产关联（2026年Q3）📅

目标: 扩展检测范围和威胁情报能力

[ ] 多源插件采集(ClawHub、Smithery)
[ ] 内部资产关联分析
[ ] 自动化告警与响应
[ ] Web UI 管理界面

第一阶段：基础建设（2026年Q1-Q2）

目标: 建立安全基础能力

[x] 完成项目规划和文档
[ ] 静态代码安全审计 (v0.1)
[ ] 运行时行为监控 (v0.1)
[ ] 攻击库（50+ 样本）
[ ] Agent 安全红队建设

交付: 审计系统 v1.0、监控系统 v1.0、攻击库

第二阶段：决策防御（2026年5月-9月）📅

目标: 实现智能拦截和防护

[ ] 风险评估系统（语义分析、评分模型）
[ ] 高危行为拦截（实时阻断）
[ ] 数据安全防护（PII 检测、脱敏）
[ ] 安全沙箱（隔离执行）
[ ] 多框架适配（3+ 框架）

交付: 风险评估 v1.0、拦截系统 v1.0、数据防护 v1.0

第三阶段：平台化管理（2026年10月-12月）📅

目标: 建立 SaaS 平台

[ ] SaaS 风险看板（多租户、实时告警）
[ ] Agent 资产管理（自动发现、配置扫描）
[ ] 云端大脑（AI 决策、策略管控）
[ ] 行为图谱（威胁情报）

交付: SaaS 平台上线、云端大脑 v1.0

第四阶段：自主安全 AI（2027年+）📅

目标: AI 治 AI

[ ] 自主安全 Agent（自动扫描、归因、修复）
[ ] 预测性防护（威胁预测）
[ ] 自我进化（持续学习）

目标: 人工干预降低 90%

🛠️ 技术栈

v0.1 核心架构

"两阶段流水线 + 混合Hook" 架构

graph TB
    subgraph "FR-02: 静态审计"
        A[Skill Package] --> B[SkillLoader<br/>ZIP安全检查]
        B --> C[Phase 1: 规则引擎<br/>StaticAnalyzer + PipelineAnalyzer<br/>< 1秒]
        C --> D[Enrichment Context<br/>文件清单+命令分布+Findings]
        D --> E[Phase 2: LLM语义<br/>LLMAuditor + 上下文增强<br/>< 3秒]
        E --> F[ThreatTagger<br/>4框架分类映射]
        F --> G[Report<br/>JSON/Markdown/HTML]
    end

    subgraph "FR-03: 运行时监控"
        H[Agent Tool Call] --> I[TypeScript Hook<br/>beforeToolCall]
        I --> J[IPC: stdin/stdout<br/>JSON Lines<br/>< 50ms]
        J --> K[Python PolicyEngine<br/>CFI+DFI+Intent<br/>< 100ms]
        K --> L{Decision}
        L -->|ALLOW| M[Execute]
        L -->|BLOCK| N[Deny]
        L -->|WARN| O[Log + Execute]
        K --> P[AuditLog<br/>JSON Lines]
    end

主要技术

后端 (Python 3.10+)

框架: FastAPI, Typer (CLI), Rich (输出美化)
数据: Pydantic v2 (数据模型), SQLite/aiosqlite (威胁情报库)
异步: asyncio, aiofiles, httpx
LLM: Anthropic SDK (Claude Sonnet 4.5)
日志: structlog (结构化日志)
配置: PyYAML (配置管理)
模板: Jinja2 (报告生成)

前端 Hook 层 (TypeScript)

运行时: Node.js 20+
类型: TypeScript 5.0+
测试: Jest 29+
工具: uuid (requestId 生成)

开发工具

包管理: Poetry (Python), npm (TypeScript)
测试: pytest, pytest-cov, pytest-asyncio
代码质量: black, isort, flake8, mypy
CI/CD: GitHub Actions

参考开源项目

Cisco Skill Scanner - 两阶段流水线 (29,830行)
Agent-Scan - Toxic Flow检测 (5,278行)
ClawBands - Hook机制 (2,286行)

详见技术栈文档

🔐 安全优先

本项目遵循安全优先的开发理念：

✅ 每个代码变更必须通过安全审查
✅ 使用 STRIDE 威胁建模
✅ 纵深防御（7层防护）
✅ 完整审计日志（不可篡改）
✅ 定期红蓝对抗演练
✅ 符合 OWASP、等保 2.0、GDPR

详见威胁模型文档

📊 关键指标

技术指标

行为捕获率: 100%
攻击检测率: > 95%
拦截准确率: > 95%
误报率: < 5%
系统可用性: > 99.9%

业务指标

第一阶段: 攻击样本 ≥ 50、Skill 审计 TOP 100
第三阶段: 注册用户 > 100、资产管理 > 1,000

👥 团队

核心成员

@墨闲(张本梁): 技术负责人、安全研究
@流风(李鹤仙): 资深技术、安全研究
@黄翔: 高级技术、安全研究

🤝 贡献指南

开始贡献

阅读项目总览
查看任务清单
阅读 CLAUDE.md 了解工作流
认领任务并开始开发

开发规范

遵循安全编码规范
代码审查覆盖率 100%
单元测试覆盖率 > 80%
所有 PR 必须通过安全检查

📖 参考资料

🌟 核心参考开源项目（37,394行代码）

| 项目 | 代码量 | 核心贡献 | 借鉴点 | |-----|-------|---------|--------| | Cisco Skill Scanner | 29,830行 Python | 两阶段流水线架构 | ⭐⭐⭐⭐⭐ Phase 1规则+Phase 2 LLM, 插件化分析器, 80+YAML规则, Enrichment Context | | Agent-Scan (Snyk) | 5,278行 Python | Toxic Flow检测 | ⭐⭐⭐⭐ 工具标签系统, 数据流追踪, MCP协议适配 | | ClawBands | 2,286行 TypeScript | Hook机制设计 | ⭐⭐⭐⭐ OpenClaw插件, CFI/DFI概念, 决策日志 |

创新:

✅ Cisco的两阶段流水线 + Agent-Scan的Toxic Flow
✅ ClawBands的TS Hook + 自研Python策略引擎 (IPC通信)
✅ 80+ YAML规则库 + 上下文增强LLM
✅ 4框架威胁分类映射（Cisco AI/MITRE ATLAS/OWASP/NIST）

其他开源项目

clawsec - Skills 架构参考
agentdojo - 安全测试框架
doomarena - 对抗测试
OpenSandbox - 沙箱参考
ps-fuzz - 攻击库参考

安全标准与框架

OWASP Top 10 for LLMs - LLM应用安全
MITRE ATLAS - AI/ML威胁框架
Cisco AI Defense Framework - AI防御框架
NIST AI RMF - AI风险管理

📞 联系我们

项目负责人: @墨闲(张本梁)

📜 许可证

[待定]

🚀 快速开始

环境要求

Python 3.10+ (已测试: 3.14.3)
Git
(可选) Node.js 20+ (TypeScript Hook 层开发，Sprint 3)

快速安装

方式 1: 自动化安装（推荐）

# 克隆仓库
git clone <repository-url>
cd agent-security-project

# 运行自动化安装脚本（会尝试安装 Poetry）
./setup.sh

方式 2: 手动安装（已验证）

# 1. 克隆仓库
git clone <repository-url>
cd agent-security-project

# 2. 安装 Python 依赖（使用 pip）
pip3 install --user anthropic pydantic pydantic-settings pyyaml structlog \
  typer rich jinja2 aiofiles aiosqlite httpx python-frontmatter

# 3. 安装测试依赖
pip3 install --user pytest pytest-cov pytest-asyncio pytest-mock

# 4. 验证安装
PYTHONPATH=src python3 -c "import agent_security; print(f'✅ Version: {agent_security.__version__}')"

# 5. 运行测试
PYTHONPATH=src python3 -m pytest tests/ -v

# 6. 使用 CLI
./agent-security --help

配置环境

# 1. 设置 API Key（必需，用于 LLM 审计）
export ANTHROPIC_API_KEY="your-api-key-here"

# 添加到 ~/.zshrc 或 ~/.bashrc 使其永久生效
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

# 2. 初始化配置（可选）
./agent-security config --init

# 3. 查看配置
./agent-security config --show

使用示例

查看版本和帮助

# 查看版本
./agent-security version
# 输出: Agent Security Project v0.1.0

# 查看帮助
./agent-security --help

# 查看子命令帮助
./agent-security scan --help

扫描 Skill 包（Sprint 2 功能，当前为占位符）

# 扫描 ZIP 包
./agent-security scan /path/to/skill.zip --output report.html

# 使用不同策略
./agent-security scan /path/to/skill --policy strict

启动运行时监控（Sprint 3 功能）

# 启动 AgentArmor 服务
./agent-security armor --mode ipc --policy strict

查看审计日志

# 查看最后 100 条日志
./agent-security logs --last 100

# 按事件类型过滤
./agent-security logs --filter BLOCK

开发模式

# 运行测试
PYTHONPATH=src python3 -m pytest tests/ -v

# 查看覆盖率
PYTHONPATH=src python3 -m pytest tests/ --cov --cov-report=html
open htmlcov/index.html

# 代码格式化（需要安装开发工具）
pip3 install black isort mypy flake8
black src/ tests/
isort src/ tests/

# 类型检查
mypy src/

# 代码检查
flake8 src/ tests/

构建可执行文件

前置条件

# 安装 PyInstaller
pip install pyinstaller

# 确保依赖已安装（特别是 python-frontmatter）
pip install python-frontmatter

构建单文件可执行程序

# 从项目根目录运行
pyinstaller agent-security.spec --clean -y

# 输出位置
dist/agent-security  # 单文件，约 26MB

测试可执行文件

# 查看版本
./dist/agent-security --version

# 扫描技能包
./dist/agent-security scan ./test_skills/safe/simple-formatter

# 生成 JSON 报告
./dist/agent-security scan ./test_skills/malicious/exfiltrator --format json --output report.json

# 查看帮助
./dist/agent-security --help
./dist/agent-security scan --help

注意事项

Python 包导入使用绝对导入（比如导入 src/xxx.py 写成 import xxx）或者当前目录导入（比如 import .xxx），否则打包后的二进制后端可能找不到模块

单文件 vs 目录模式
- 当前配置为单文件模式（onefile），启动时会解压到临时目录
- 如需更快的启动速度，可修改 spec 文件为目录模式
新增模块
- PyInstaller 会自动分析静态导入，新增 Python 模块无需修改 spec 文件
- 仅在添加新的数据文件目录（YAML/JSON/MD）时需要更新 data_files
依赖包冲突
- 确保安装的是 python-frontmatter 而非 frontmatter
- 两者 import 名称相同但 API 不同

构建 npm 包 (`@yidun/agent-guard`)

将项目打包为 npm 包，用户 npm install -g 后通过 agent-guard 命令一键启动。

构建步骤

# 1. 安装 Node.js 构建依赖
npm install

# 2. 构建 Python 后端二进制（PyInstaller）
pyinstaller agent-security.spec --clean -y

# 3. 一键构建 npm 包（前端 → 插件 → 后端 → 资产）
npm run build

# 4. 打包为 .tgz
npm pack

npm run build 依次执行：

build:frontend — Rollup 打包 React SPA（混淆），产出 frontend/
build:plugin — Rollup 合并 ClawTrace 三合一（混淆），产出 plugin/
build:backend — 复制/合并后端二进制到 backend/（支持 lipo universal）
build:copy — 设置权限

清理构建产物：npm run clean

macOS Universal 二进制

# arm64 机器构建后重命名
pyinstaller agent-security.spec --clean -y && mv dist/agent-security dist/agent-security-darwin-arm64

# x64 机器构建后重命名
pyinstaller agent-security.spec --clean -y && mv dist/agent-security dist/agent-security-darwin-x64

# build:backend 自动 lipo 合并
npm run build:backend

npm 包使用

# 安装（postinstall 自动部署 ClawTrace 到 OpenClaw）
npm install -g @yidun/agent-guard

# 后台启动（自动打开浏览器）
agent-guard

# 自定义端口
agent-guard -p 3001 -f 3231

# 停止
agent-guard stop

# 插件管理
agent-guard plugin --force

npm 包结构

@yidun/agent-guard/
├── bin/agent-guard.mjs                # CLI 入口
├── server/static-server.mjs           # Express 静态服务器 + API 代理
├── frontend/                          # React SPA（Rollup 打包 + 混淆）
├── plugin/                            # ClawTrace 插件（三合一，混淆）
└── backend/agent-security             # PyInstaller macOS 二进制

详细构建说明和命令参考见 QUICKSTART.md

📈 当前状态

版本: v0.1.0 最后更新: 2026-03-05 Sprint 1 完成度: 85%

代码统计

| 指标 | 数值 | |-----|------| | 总代码行数 | 1,431+ | | 单元测试 | 17/17 通过 | | 代码覆盖率 | 42.04% | | 核心模型覆盖率 | 96.72% | | 配置系统覆盖率 | 94.00% |

已实现功能

✅ 核心数据模型（15+ Pydantic 模型）
✅ 配置管理系统（YAML + 环境变量）
✅ 结构化日志（敏感数据自动脱敏）
✅ 存储系统（SQLite + JSON Lines）
✅ CLI 框架（5个命令）
✅ 单元测试框架

下一步计划

📌 本周 (Sprint 1 Week 1):

补充 logger/storage 单元测试
配置 CI/CD (GitHub Actions)
代码质量检查

📌 下周 (Sprint 1 Week 2):

测试框架完善
达到 80% 代码覆盖率

📌 Sprint 2 (Week 3-4):

FR-02 静态审计引擎
两阶段流水线实现

开始探索: 从快速开始指南开始，或阅读开源项目分析了解架构设计

最后更新: 2026-03-05 | Sprint: 1 | 进度: 基础框架 85%

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Agent 安全项目 🛡️

📖 项目简介

🎯 v0.1 版本亮点 ⚡

🏗️ 核心架构

FR-02: 静态代码安全审计（两阶段流水线）

FR-03: 运行时行为监控（混合Hook架构）

📊 关键指标

🚀 核心特性

✅ 已完成（Sprint 1 - 基础框架）

🚧 进行中（Sprint 1 - Week 1）

⏳ 待开始（Sprint 2 - Week 3-4）

🔜 未来阶段

📚 文档导航

🌟 v0.1 核心文档（架构升级）

📖 完整项目文档

🔧 辅助文档

🏗️ 项目结构

🎯 开发路线图

v0.1: 静态审计 & 运行时监控（2026.03 - 2026.06）⏳

v0.2: 多源采集 & 资产关联（2026年Q3）📅

第一阶段：基础建设（2026年Q1-Q2）

第二阶段：决策防御（2026年5月-9月）📅

第三阶段：平台化管理（2026年10月-12月）📅

第四阶段：自主安全 AI（2027年+）📅

🛠️ 技术栈

v0.1 核心架构

主要技术

🔐 安全优先

📊 关键指标

技术指标

业务指标

👥 团队

核心成员

🤝 贡献指南

开始贡献

开发规范

📖 参考资料

🌟 核心参考开源项目（37,394行代码）

其他开源项目

安全标准与框架

📞 联系我们

📜 许可证

🚀 快速开始

环境要求

快速安装

方式 1: 自动化安装（推荐）

方式 2: 手动安装（已验证）

配置环境

使用示例

查看版本和帮助

扫描 Skill 包（Sprint 2 功能，当前为占位符）

启动运行时监控（Sprint 3 功能）

查看审计日志

开发模式

构建可执行文件

前置条件

构建单文件可执行程序

测试可执行文件

注意事项

构建 npm 包 (@yidun/agent-guard)

构建步骤

macOS Universal 二进制

npm 包使用

npm 包结构

📈 当前状态

代码统计

已实现功能

下一步计划

构建 npm 包 (`@yidun/agent-guard`)