wts408/soar-playbook-builder
GitHub: wts408/soar-playbook-builder
一款 Splunk SOAR 自定义应用，支持通过自然语言或模板生成、预览、验证 playbook 并一键导入平台运行。
Stars: 0 | Forks: 0
# SOAR Playbook 构建器
[](LICENSE)
[](soar_playbook_builder/soar_playbook_builder.json)
[](docs/PLAYBOOK_BUILDER_GUIDE.md)
[](CHANGELOG.md)
**使用自然语言描述 SOAR playbook，预览 block 流程和 Python 代码，进行验证，并导入到 Visual Playbook Editor。**
这是一款用于生产环境的 Splunk SOAR 自定义 app，而非演示设备。每次安装都会包含示例用例（9001–9005）以及支持 mock 的开发模式，以便您在自己的实例上测试 **构建 → 导入 → 运行** 流程。
**仓库地址：** [github.com/wts408/soar-playbook-builder](https://github.com/wts408/soar-playbook-builder)
## 概览
*安装后请替换为实时截图：SOAR → your asset → **Open sidecar** → 截取 Build 标签页。*
## 前置条件
### 在您的构建机器上（打包 `.tgz`）
| 要求 | 说明 |
|-------------|--------|
| **bash**, **tar**, **git** | macOS 或 Linux（RHEL/Ubuntu 均可） |
| **Node.js 20+** 和 **npm** | 构建 React sidecar (`sidecar-ui/`) |
| **Python 3.9+** | 实用工具脚本和可选的 E2E 验证 |
可选（仅用于 E2E / 验证）：
```
pip install -r requirements.txt # httpx for scripts/e2e_validate.py
```
### 在 Splunk SOAR 上（运行时）
| 要求 | 说明 |
|-------------|--------|
| **Splunk SOAR 8.5+** | 参见 app manifest 中的 `min_phantom_version` |
| **Python 3.13** | 用于导入 playbook 的 SOAR 平台 Python |
| **兼容 RHEL 的操作系统** | 标准 SOAR 设备或自管理主机 |
| **Asset + permissions** | 具备 playbook 编辑/导入权限的 Analyst 角色 |
**模式 A（默认）：** 模板、scaffolds、验证、导入 — **无需 MCP 或 API key。**
**模式 B（可选）：** 通过外部 MCP agent bridge 进行自然语言聊天 — 请参阅 [配置](#configuration) 和 [docs/MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md)。
## 快速开始
只需三个命令即可构建可安装的 app：
```
git clone https://github.com/wts408/soar-playbook-builder.git
cd soar-playbook-builder
./package_app.sh
```
在 SOAR 上安装：
1. **SOAR → Apps → Install App** → 选择 `dist/soar_playbook_builder.tgz`
2. **Configure → Asset Configuration** → 创建一个 asset（例如 `playbook_builder`）
3. 运行操作 **Test connectivity**（模式 B）或打开 sidecar URL：
```
SOAR_URL=https://your-soar:8443 SOAR_USER=admin SOAR_PASS='***' ASSET=playbook_builder \
./scripts/print_sidecar_url.sh
```
**在没有 SOAR 的情况下试用**（mock UI）：
```
cd sidecar-ui && npm install && npm run dev
# → http://localhost:5173 (#/build · #/run · #/help)
```
## 配置
复制模板并为您的环境填入相应的值：
| 文件 | 用途 |
|------|---------|
| [**config.example.yaml**](config.example.yaml) | SOAR asset 字段（`mcp_bridge_url`、`asset_defaults` 等） |
| [scripts/env.e2e.example](scripts/env.e2e.example) | 针对线上 SOAR 进行 E2E 验证 |
| [sidecar-ui/.env.example](sidecar-ui/.env.example) | 针对线上 SOAR 进行本地 Vite 开发 |
**最小化模式 A asset：** 将 `mcp_bridge_url` 留空；根据需要设置 `ai_instructions`；在 `asset_defaults` 中映射 integrations（在 SOAR UI 中为 JSON 字符串）。
**模式 B：** 将 `mcp_bridge_url` 指向您的 bridge（例如 `http://host:8003/agent`）。LLM key 存放在 **bridge host** 上，而不在此 repo 中。
完整设置：[docs/PLAYBOOK_BUILDER_GUIDE.md](docs/PLAYBOOK_BUILDER_GUIDE.md)
## 部署模式
| 模式 | Bridge | 最适用场景 |
|------|--------|----------|
| **A — 本地化** | 无 | Air-gapped、模板、验证、导入 |
| **B — Bridge + LLM** | MCP host | 开放式自然语言聊天 — [ON_PREM_LLM.md](docs/ON_PREM_LLM.md) |
Sidecar base URL: `https:///rest/handler///`
## 文档
| 指南 | 内容 |
|-------|----------|
| [PLAYBOOK_BUILDER_GUIDE.md](docs/PLAYBOOK_BUILDER_GUIDE.md) | 安装、配置、操作、故障排除 |
| [FAILED_LOGINS_QUICK_START.md](docs/FAILED_LOGINS_QUICK_START.md) | 约 15 分钟内实现 Failed Logins → Okta |
| [RUN_TAB_DEMO.md](docs/RUN_TAB_DEMO.md) | 示例用例 9001–9005 冒烟测试 |
| [FRESH_INSTALL_AND_MIGRATION.md](docs/FRESH_INSTALL_AND_MIGRATION.md) | 重新部署到新的 SOAR（约 15 分钟） |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 模式 A 与 B 对比、组件说明 |
| [MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md) | 模式 B HTTP 流程 |
| [AIR_GAPPED_OPERATIONS.md](docs/AIR_GAPPED_OPERATIONS.md) | 离线模式 — 无 LLM/MCP |
| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 症状索引 |
| [GITHUB_PUBLISHING.md](docs/GITHUB_PUBLISHING.md) | 发布与标签 |
更多指南：[docs/](docs/) · [CHANGELOG.md](CHANGELOG.md)
## REST 路由
| 路由 | 描述 |
|-------|-------------|
| `chat` | Sidecar UI + builder API |
| `widget` | VPE 轮询 widget |
| `poll_playbook` | Playbook 变更指纹 |
| `proxy_chat` | MCP 代理（模式 B） |
## 发布
```
./package_app.sh
git tag v2.26.0
git push origin v2.26.0
```
GitHub Actions 会将 `dist/soar_playbook_builder.tgz` 附加到 Release 中。打标签前的验证：[docs/E2E_VALIDATION.md](docs/E2E_VALIDATION.md)
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) — fork 仓库，创建分支，运行测试，然后提交 PR。
## 许可证
[MIT License](LICENSE) — 在内部发布前，请自定义 `publisher` 和品牌信息。本产品不属于 Splunk 产品；请参见 [ATTRIBUTION.md](ATTRIBUTION.md)。
标签：Python, React, SOAR, SOC Prime, Syscalls, 开发工具, 无后门, 自动化剧本