Agent Wiz：为 AI Agent 画一张「威胁地图」的开源工具

想象这样一个场景：你的团队基于 LangGraph 构建了一个多 Agent 客服系统，其中一个 Agent 负责调用外部支付 API，另一个 Agent 负责处理用户隐私数据。当系统变得复杂时，你是否能说清楚 Agent 之间的信任边界在哪里？如果攻击者能操控某个 Agent 的提示词（Prompt Injection），整条调用链的风险敞口有多大？

这类问题在传统 Web 安全中已有成熟的威胁建模方法（STRIDE、PASTA 等），但在 AI Agent 领域，传统方法显得力不从心。Agent Wiz（Repello-AI/Agent-Wiz，382星）正是为解决这一空白而生的工具——它从主流 Agent 框架代码中自动提取工作流图谱，并结合 MAESTRO 框架进行自动化威胁评估，生成可读的安全报告。

背景：为什么 AI Agent 需要专门的威胁建模工具？

2024-2025 年，AI Agent 进入了爆发期。AutoGen、CrewAI、LangGraph 等框架让多 Agent 协作系统的开发门槛大幅降低，但随之而来的安全风险也急剧上升。Agent 之间共享上下文、调用外部工具、读写持久化存储——这些能力既是价值的来源，也是攻击面的放大器。

2025 年初，CSA（云安全联盟）发布了 MAESTRO 框架，专门针对 Agentic AI 系统提出了一套威胁建模方法论，覆盖 Mission（使命）、Assets（资产）、Entrypoints（入口点）、Security Controls（安全控制）、Threats（威胁）、Risks（风险）、Operations（运营）七大维度。然而，将 MAESTRO 手工应用到真实代码中，需要安全分析师同时具备 AI 框架知识和威胁建模经验，门槛极高。

Repello AI 团队正是看到了这一缺口，开发了 Agent Wiz。它的核心价值在于：用 AST 静态解析代替人工审计，让 MAESTRO 从框架文档变成自动化流水线。

核心功能：Extract → Visualize → Analyze 三步走

Agent Wiz 提供三个 CLI 子命令，构成完整的分析闭环：

1. agent-wiz extract：从代码中提取 Agent 工作流

使用 AST（抽象语法树）静态解析，扫描指定目录下源代码，识别 Agent 框架特有的结构。以 AutoGen 为例，能提取出 AssistantAgent、UserProxyAgent 实例，以及它们之间的消息传递关系。最终输出一个标准化的 JSON 图谱文件（包含 nodes 和 edges），代表 Agent 网络的拓扑结构。

支持的框架列表相当全面：

• AutoGen（含 AgentChat 子模块）
• CrewAI：支持 crews 配置和 tasks yaml
• LangGraph：StateGraph 结构
• LlamaIndex：Agent 节点
• n8n：JSON 工作流文件
• OpenAI Agents SDK
• Pydantic-AI
• Swarm（OpenAI 实验性框架）
• Google ADK：支持 sub_agents 层级结构

每种框架都有独立的 mapper 模块（如 src/repello_agent_wiz/frameworks/autogen/mapper.py），解析对应框架的 AST 特征，保证提取结果的准确性。

2. agent-wiz visualize：交互式 D3.js 可视化

将 extract 输出的 JSON 图谱转换为 HTML 页面，使用 D3.js 力导向图展示 Agent 节点、工具调用、Agent 间通信链路。--open 参数可直接在默认浏览器打开，适合向非技术人员演示架构。

3. agent-wiz analyze：MAESTRO 威胁评估

这是工具的核心价值所在。读取 extract 生成的 JSON 图谱，结合内置的 MAESTRO 框架文本，通过 OpenAI GPT-4o 生成结构化威胁评估报告。报告涵盖：

• Mission：系统安全目标是否明确
• Assets：Agent、工具、数据流中的关键资产
• Entrypoints：外部输入点（如用户 Prompt、API 调用）
• Security Controls：已有的安全措施
• Threats：具体威胁场景（如 Prompt Injection、数据泄露、工具滥用）
• Risks：基于影响和可能性评估风险等级
• Operations：运行时安全考量

威胁分析完全依赖 GPT-4o 的推理能力，因此 OpenAI API Key 是硬性依赖。同时也意味着分析质量受模型版本影响，结果需要人工复核。

技术架构解析

代码结构

源码位于 src/repello_agent_wiz/，采用清晰的模块化分层：

src/repello_agent_wiz/
├── cli.py                        # CLI 入口（argparse）
├── config.py                     # API Key 配置
├── analyzers/
│   ├── threat_modelling.py       # MAESTRO 分析逻辑（调用 OpenAI）
│   ├── maestro.txt               # MAESTRO 框架文本（内置）
│   └── sys_prompt.txt            # GPT 分析提示词模板
├── frameworks/
│   ├── autogen/mapper.py         # AutoGen AST 解析器
│   ├── crewai/mapper.py          # CrewAI 解析器
│   ├── langgraph/mapper.py       # LangGraph 解析器
│   ├── llama_index/mapper.py
│   ├── agent_chat/mapper.py
│   ├── google_adk/mapper.py
│   ├── n8n/mapper.py
│   ├── openai_agents/mapper.py
│   ├── pydantic/mapper.py
│   └── swarm/mapper.py
├── templates/
│   ├── index.html                # D3.js 可视化模板
│   └── assets/*.svg              # 节点图标（agent、tool、memory等）
└── visualizers/
    └── visualizer.py             # HTML 生成器

依赖管理

纯 Python 包，仅有三个直接依赖：openai（威胁分析）、python-dotenv（配置管理）、pyyaml（n8n 解析）。最小化依赖面，降低与目标项目环境的冲突风险。Python 版本要求 >= 3.10。

打包方式

使用标准 setuptools，包入口点定义为 agent-wiz 命令：

[project.scripts]
agent-wiz = "repello_agent_wiz.cli:main"

争议与局限性

1. OpenAI 强依赖：整个威胁分析环节重度依赖 GPT-4o，不支持本地模型（如 Ollama）。这在企业内网环境或数据隐私敏感场景下是硬伤。Roadmap 中提及的 STRIDE、PASTA 等更多框架仍在开发中。

2. AST 解析的局限性：目前仅支持白名单内的框架，自定义或小众框架无法识别。此外，AST 静态分析无法覆盖运行时行为（如条件分支导致的动态 Agent 组合），分析结果存在盲区。

3. 报告质量依赖模型推理：GPT-4o 生成的威胁报告在格式上标准，但在具体场景的深度上参差不齐，需要有经验的安全分析师做二次验证。

4. 无 Docker 支持：纯 CLI 工具，无容器化部署能力，在隔离环境中运行需要自行配置 Python 环境。

部署与上手

安装只需一行命令：

pip install repello-agent-wiz

使用前需配置 OpenAI API Key（.env 方式更推荐）：

cp .env.sample .env
# 编辑 .env，填入 OPENAI_API_KEY=sk-...

完整分析流程约 10-15 分钟（取决于代码规模和 API 响应速度）。

行业意义与趋势

Agent Wiz 代表着 AI 安全工具链的一个新兴方向：将传统网络安全方法论（威胁建模）与 AI Agent 特性结合的自动化工具。随着 MAESTRO、CSA 的推动，这类工具的需求会持续增长。

从 GitHub 增长曲线看（382星，2025 年新项目），该领域目前仍处于早期，竞品少，生态价值高。对于安全研究者和 AI 开发团队而言，Agent Wiz 是目前为数不多能将代码级 Agent 架构转换为安全可操作洞察的工具，值得关注。

项目主页：https://repello.ai/ | PyPI：pip install repello-agent-wiz