AI智能体安全扫描工具

概述

概述

本技能封装一个可独立运行的 AI 智能体安全扫描工具（v5.9.1，作者：湘移网核）。自动适配本机所有 AI 智能体——内置 50+ 类常见智能体定义，并具备「泛化自动发现」能力：扫描用户主目录下的数据目录，依据启发式标记自动识别并扫描任何未知智能体（无需预置列表）。执行 41 条加密规则（L1 文件层 / L2 行为层 / L3 框架层）+ 14 条传感器规则（L4 运行时 / L5 篡改防护 / L6 供应链）共 55 条规则的全覆盖扫描，输出自包含 HTML 报告与 JSON 告警数据。内置单机 License 认证（机器指纹绑定），仪表盘含实时信任状态面板（三层一致性/增量持久化/快照完整性/规则版本一致性）与健康检查端点（/api/health），客户仅需手动或定时调用即可查看报告与告警。

何时使用

• 用户要求「安全扫描」「扫描智能体」「安全检测」「agent security scan」「多智能体扫描」
• 用户要求「告警报告」「查看安全报告」「查看 HTML 报告」「查看告警」
• 用户要求「定时扫描」「定期安全巡检」「每天扫描一次」
• 用户需要单机认证 / 授权激活相关操作

前置条件：单机认证

工具受单机 License 保护，首次使用前必须激活（绑定当前机器，无需供应商二次介入）：

1. 检查状态：python scripts/skill_entry.py --action status
2. 若 authorized 为 false，执行激活：python scripts/skill_entry.py --action activate --customer "客户名称"
3. 激活后会在技能根目录生成 .license 文件，之后所有扫描均自动通过授权校验

在线报告（v5.4.4 随机端口分配）

扫描完成后，系统会自动提示在线报告地址。安装端使用随机端口分配机制（9000-9999范围），避免不同智能体之间端口冲突：

# 开发端启动（固定8137端口）
python scripts/serve_dashboard.py --port 8137 --env dev

# 安装端启动（自动随机分配端口，持久化到config/dashboard_port.json）
python scripts/serve_dashboard.py --env install

# 手动指定端口
python scripts/serve_dashboard.py --port 9000 --env install

随机端口特性：

• 端口范围：9000-9999（避开系统常用端口）
• 冲突检测：尝试绑定，失败自动重试（最多50次）
• 端口持久化：首次分配后写入 config/dashboard_port.json，下次启动自动复用
• 开发端固定8137，安装端随机分配，互不干扰

适配所有智能体（泛化发现）

本技能不只扫描内置清单，而是自动适配本机安装的任何 AI 智能体，三层发现：

1. 内置定义（50+ 类）：WorkBuddy / MiniMax Code / QoderWork / QCLAW / Claude / Cursor / Continue / Cline / Copilot / Codeium / Windsurf / Dify / Coze / OpenClaw / CODEX / Hermes / Aider / Cody / Tabnine / Gemini CLI / AutoGPT / Manus / OpenManus / OWL / UFO / OpenHands / Devin / MetaGPT / CrewAI / AutoGen / LangChain / 各类 Claw 龙虾系列 等（见 scanner/agent_discovery.py 的 AGENT_DEFINITIONS）。
2. 用户自定义注册表：在 config/custom_agents.json 中以相同结构追加任意智能体（格式见 config/custom_agents.example.json）。未列出的智能体也能精确扫描。
3. 泛化自动发现：扫描用户主目录下所有数据目录，依据强/弱标记（如 MEMORY.md / SOUL.md / AGENTS.md / mcp.json / agents/ / skills/ 目录或 JSON 中的 mcpServers / agent 关键词）自动识别未知智能体并纳入扫描。

客户无需手动维护清单：只要智能体把数据放在 ~/.xxx 这类目录下且含上述标记，就会被自动发现并扫描。

执行流程

1. 手动扫描（对话触发）

当用户要求一次安全扫描时，执行：

python scripts/skill_entry.py --action scan

该命令自动完成：检测授权 → 全机自动发现并扫描所有智能体 → 渲染报告 → 以 JSON 输出报告路径与告警统计。

随后：

1. 解析 JSON 输出的 report_html 与 report_json 字段
2. 使用 present_files 展示 HTML 报告（自动打开预览面板）
3. 口头简述：扫描智能体数、总告警数、高危 / 中危 / 低危分布

若输出 "need_activate": true，先引导用户按「前置条件」激活，再重新扫描。

检测维度（10大安全面）

本工具覆盖以下10个安全检测维度（对齐腾讯云鼎+微步SafeSkill+OWASP LLM Top 10检测框架）：

六层扫描架构

• L1 文件层：正则匹配+AST分析+脱敏（49条规则，含MCP投毒/技能安全/框架异常/组件漏洞）
• L2 行为层：会话轨迹+命令序列+数据流+行为分析（14条传感器规则+目标偏移/浮光行为/行为异常/记忆污染）
• L3 框架层：MCP注入+工具链+跨会话关联+多智能体级联/信任滥用
• L4 运行时传感器：进程注入+内存+容器逃逸
• L5 篡改防护传感器：文件完整性+签名校验
• L6 供应链传感器：SBOM+CVE匹配+依赖来源

新增规则清单（v5.4.3，依据IMA知识库v3.1规范书）

类别简称规范：简体中文2-5字（MCP投毒/技能安全/框架异常/组件漏洞/目标偏移/行为异常/记忆污染/多智能体/信任滥用）

三种扫描模式（v5.4.3 融合架构）

系统采用7阶段×3模式矩阵，支持从首次安装到长期运维的全生命周期扫描：

7个扫描阶段：终端发现→智能体发现→配置审计→文件扫描→动态扫描→日志扫描→报告生成

增量指纹引擎：文件指纹=(mtime_ns, size)纳秒级比对，增/删/改三态识别，未变更文件复用存量告警。

命令：

python main.py --mode phased-scan --phased-mode full         # 安装全面扫描
python main.py --mode phased-scan --phased-mode quick         # 短期扫描
python main.py --mode phased-scan --phased-mode incremental   # 长期扫描

2. 定时扫描（automation 触发）

当用户要求定期 / 定时扫描时，创建一个 recurring 自动化任务：

• 任务提示词（prompt）：运行 agent-security-scanner 技能，执行全机自动安全扫描（auto 模式），扫描完成后展示生成的 HTML 报告并简要说明告警情况。
• 调度频率按用户需求设定（如每天 09:00、每小时等）
• 每次运行重新扫描并覆盖当日报告，历史报告以日期命名保留，不会无限增长

3. 查看报告与告警

• HTML 报告：reports/AI智能体安全报告_YYYY-MM-DD.html，含智能体覆盖面板、图表、告警明细、修复指导书，通过 present_files 打开预览
• JSON 数据：reports/AI智能体安全报告_YYYY-MM-DD.json，完整告警结构化数据，可用于导出 / 二次分析
• 告警统计：scan 输出的 total_alerts / high / medium / low 字段
• 信任状态面板（v5.9.0 新增）：仪表盘首页实时展示四维度数据可信度——三层一致性（scan输出/JSON/SQLite三方对账）、增量持久化覆盖（per-agent入库进度百分比）、快照完整性（file_snapshot.json文件数）、规则版本一致性（全agent规则版本统一性）。后端API /api/dashboard/trust，前端 renderTrustStatus() 渲染，总体状态徽章支持 healthy/warning/critical/unknown 四态。

脚本与资源参考

• scripts/skill_entry.py — 统一调用入口，支持 scan / activate / machine-id / status 四种 action，输出 JSON
• main.py — 原始 CLI 入口（auto / discover / manual / scheduled / versions / rollback / diff / activate / machine-id）
• scanner/ — 扫描引擎、规则管理器、去重模块、报告渲染器、单机认证、智能体发现
• rules/ — 41 条加密规则库（.enc）+ 14 条传感器规则（共 55 条）
• SKILL.md（本文件）— 激活、手动、定时、报告解读与常见问题详解
• references/安装指导手册.md — 安装步骤、依赖、首次扫描、常见问题
• references/产品说明书.md — 产品概述、检测能力、报告输出、安全认证
• curl http://127.0.0.1:8137/api/health — 安装侧健康检查（v5.9.1 新增），返回 DB 连接状态、告警数量、License 状态、诊断提示
• targets/sample_target/ — 测试目标

注意事项

安全声明

• 零网络依赖：全部检测逻辑本机执行，不上传任何用户数据。AI研判为可选功能，需用户自行配置API KEY，默认禁用，不包含任何预置API KEY。发布包内 config/ai_config.json 仅为空占位模板（无真实端点/密钥）；配置优先级：环境变量（AGENT_SEC_AI_URL / AGENT_SEC_AI_KEY / AGENT_SEC_AI_MODEL）> 本地配置文件。
• 规则加密透明度声明：规则库采用AES-256-GCM加密，保护知识产权。加密机制不影响可审计性——公开规则目录（不含具体正则模式）可通过 --list-rules 查看，包括55条检测规则（41条L1-L3加密规则+14条L4-L6传感器规则）的ID/名称/类别/严重级/OWASP映射/CWE编号。加密不是为了隐藏恶意逻辑，而是防止规则被篡改或盗用。规则内容可通过作者邮箱申请审计。
• 越狱测试场景说明：本工具包含22个越狱测试场景（jailbreak/scenarios.py），用于验证L1-L3安全检测规则的覆盖度。所有场景的攻击提示词已脱敏处理，具体命令/路径/凭证名均替换为 [PLACEHOLDER] 占位符，不可直接用于攻击。场景仅保留结构特征（角色劫持/编码混淆/权限越界等模式）供规则匹配验证。
• 进程操作披露：扫描完成后默认不执行任何进程操作。仅在交互式终端下，经用户显式确认（y/N 提示）后启动本地报告仪表盘；启动命令以参数数组形式执行（无 shell 拼接）。本工具不会自动结束任何用户进程；若报告端口被占用，仅提示用户手动处理。
• 无云元数据访问：代码中不包含任何云实例元数据端点（169.254.x.x）引用。测试样本中的IP地址均为占位符。
• 扫描范围声明：仅扫描用户主目录下已安装AI智能体的数据目录，不访问系统敏感目录（/etc、/root、C:Windows等）。扫描结果仅生成本地HTML/JSON报告和SQLite数据库，均存储在本地，不外传。发布包不含任何预置数据库或历史扫描数据。
• LLM网络功能声明：AI研判功能（llm_client.py）为可选模块，默认禁用（无endpoint配置时不启用）。启用时仅发送告警摘要（规则ID+匹配字段+严重级），不发送完整文件内容。用户可配置任何兼容OpenAI API的端点，数据传输由用户控制（环境变量或本地配置文件两种方式，后者对KEY做本地混淆存储，不包含在发布包中）。

安装侧问题诊断（v5.9.1 新增）

安装后在仪表盘看到"无数据"或信任面板显示"⚠️ 加载失败"时，按以下流程排查：

# 1. 健康检查（一键诊断）
curl http://127.0.0.1:8137/api/health
# 关注: db_connected / alerts_count / license_valid / hint

# 2. 若 alerts_count=0：执行首次扫描
python scripts/skill_entry.py --action scan

# 3. 若 license_valid=false：激活授权
python scripts/skill_entry.py --action activate --customer "客户名称"

# 4. 若 db_connected=false：检查DB路径
ls config/alert_store.db
# 若不存在则需先执行扫描生成数据库

常见原因速查表：

• 测试样本声明：发布包不包含targets/目录（测试样本仅用于开发环境规则验证，不随发布包分发）。
• URL引用声明：代码中引用的18个外部URL均为安全工具/标准的官方文档链接（如OWASP/CWE/Semgrep/Snyk等），不含恶意URL，不用于远程通信。

第三方安全认证报告

本工具已通过三家权威安全机构的检测认证，报告随包分发（references/security_reports/ 目录），可供用户直接查阅：

SafeSkill 检测结论（v5.4.0，2026-07-14）：意图一致性90%（通过80%阈值）。代码功能完整，与声明意图一致：扫描完全在本地执行，不上传用户数据，可选AI增强模块默认关闭。未发现隐藏的网络外传、远程代码执行、持久化机制或恶意混淆。

腾讯威胁情报中心结论（v5.4.0）：评级"安全"。20个文件全部通过检测，未发现恶意行为。该技能为AI智能体安全扫描工具，通过读取本地文件、执行系统命令扫描主机智能体安全风险，生成报告并支持定时任务。

• 规则库、脱敏正则、版本索引均为加密存储（.enc），运行时内存解密，不落盘
• 全机扫描约 20 秒，覆盖本机所有已安装 AI 智能体（内置 50+ 类 + 泛化自动发现未知智能体，演示机实测 12 个）
• 去重优化后单次全机告警约 603 条起步（12 agent，受每规则上限 cap 约束不会爆炸；规则去重 41→41、算法去重前数千条，综合降幅 94%）
• 报告按日期命名，重复运行覆盖当天报告，磁盘占用稳定

版本历史

v6.2.1 (2026-08-10)

• 重构：攻击链引擎从「单告警 IOC 打标」升级为「按智能体/SKILL 维度串联多阶段告警」。新增 scanner/attack_chain_builder.py，按 (agent_name, skill_name) 聚类 → kill-chain 7 阶段归类 → ≥2 阶段才构成链。真实数据：603 条告警 → 36 条攻击链（含 472 条告警），每条链清晰归属于一个智能体+SKILL，阶段间有因果先后
• 修复 B1/B3/B4：scan_engine.py 的 ransom_matches 写入路径——字段名 _ransom_hits→_attack_chain_hits（原永远写空）、INSERT 从 6 列补全到 9 列（原 agent_name/skill_name 全丢）。实测 agent_name 填充率从 18% → 100%
• 修复 B2：ransom_matches/ransom_whitelist/attack_chains/attack_chain_alerts 四表 DDL 收归 AlertStore._init_db（原散落在 scan_engine + serve_dashboard 两处，schema 漂移）
• 修复 B5：离线导出依赖旧 RANSOM_CHAIN 常量 → 扩展 OfflineExport.generate 接受 attack_chains_data 参数，注入 OFFLINE_ATTACK_CHAINS
• 新增 DB 层：AlertStore 新增 save_ransom_matches/save_attack_chains/query_attack_chains 三方法；扫描层 _persist_scan_result 新增第 5 步 attack_chains 入库（独立 try/except，不阻断主流程）
• 新增仪表盘 API：/api/attack-chains/v2（按链返回，含多阶段+组成告警）+ /api/attack-chains/v2/stages（kill-chain 阶段定义）；保留旧 /api/attack-chains 兼容
• 零回归：旧 match_alerts/ATTACK_CHAINS/RANSOM_CHAIN 符号全保留，旧 API 不改行为，召回率不变

v5.9.1 (2026-07-31)

• 新增：/api/health 健康检查端点（DB 连接/告警数/License/快照/诊断提示）
• 加固：renderTrustStatus() 错误暴露到 UI（不再静默吞错）；setTrustCard() 空数据显示"无数据"
• 新增：安装侧问题诊断流程（健康检查→DB 验证→License→快照→仪表盘）
• 修复：安装包排除规则新增 reports/ 目录（防历史数据泄露）+ config/scan_history.json
• 文档：新增参考资源 references/安装指导手册.md、references/产品说明书.md、references/CHANGELOG_v5.9.0.md

v5.9.0 (2026-07-31)

• 新增：仪表盘信任状态面板（P0-9），四维度实时展示数据可信度
• 修复：前端 apiBase() 未定义导致面板无数据（三次排查终定位）
• 升级：版本号 5.8.1 → 5.9.0（4处同步）
• 清理：11 个过时文档/示例文件删除
• 新增：scripts/build_package.py 安装包构建脚本（8层级清洗规范）
• 同步：data-architecture-fix-guide 架构 SKILL 版本对齐