agentflocks 深信服 XDR Use
First
操作模式 API V.S Browser
何时使用 API（默认）
- 默认模式，默认使用 API
- API 覆盖大部分运营场景（告警、事件、资产、漏洞、响应、白名单）
何时使用浏览器（CDP 直连）
- API 没有覆盖目标能力（如系统运维页面/节点状态/CPU内存磁盘趋势没有 API）
- 需要查看页面详情、交互式筛选、图表数据
- 页面需要人工登录、验证码、多因子认证
- 用户要求使用浏览器，或已在浏览器操作过程中
请求确认
- 默认走 API 模式；仅当 API 调用失败（如 401/403/连接失败）或目标能力不在 API 覆盖范围内时，再提示用户："XDR API 不可用，请检查配置或切换到浏览器模式"。
- 用户明确要求使用浏览器时，直接进入浏览器模式。
确定模式后：
- API 模式 → 阅读 API 模式使用指南
- 浏览器模式 → 阅读浏览器模式使用指南
API 模式使用指南
工具速查
| 工具 | 能力 | 适用场景 |
|---|---|---|
sangfor_xdr_alerts |
告警列表查询 / 处置状态修改 / 举证信息 | 安全事件分诊、告警运营 |
sangfor_xdr_incidents |
事件列表查询 / 处置状态修改 / 举证信息 / 关联实体 | 事件响应、攻击故事线分析 |
sangfor_xdr_vulns |
基线合规 / 漏洞列表 / 弱密码列表 / 修复状态 | 漏洞管理、合规检查 |
sangfor_xdr_assets |
资产列表 / IP段树 / 资产分类 / 接入设备 / 部门树 | 资产盘点、攻击面管理 |
sangfor_xdr_responses |
查询已隔离主机 / 解除隔离 | 事件遏制、恢复 |
sangfor_xdr_whitelists |
白名单 CRUD + 启用/禁用切换 | 抑制已知合规告警 |
路由规则
| 用户意图 | 推荐工具 | 常用 action |
|---|---|---|
| 查告警、告警列表、分诊 | sangfor_xdr_alerts |
list |
| 修改告警处置状态 | sangfor_xdr_alerts |
update_status |
| 查告警当前处置状态 | sangfor_xdr_alerts |
status_list |
| 查告警举证信息 | sangfor_xdr_alerts |
get_proof |
| 查事件、安全事件 | sangfor_xdr_incidents |
list |
| 修改事件处置状态 | sangfor_xdr_incidents |
update_status |
| 查事件关联实体（主机/IP/文件/进程/DNS） | sangfor_xdr_incidents |
get_entities |
| 查事件举证信息 | sangfor_xdr_incidents |
get_proof |
| 查漏洞/基线合规 | sangfor_xdr_vulns |
baseline / vuln_list |
| 查弱密码 | sangfor_xdr_vulns |
vuln_list(data_type="weakpwd") |
| 修改漏洞修复状态 | sangfor_xdr_vulns |
update_status |
| 查数据源设备 | sangfor_xdr_vulns |
source_device |
| 查资产列表 | sangfor_xdr_assets |
list |
| 查 IP 段树结构 | sangfor_xdr_assets |
ip_segment_tree |
| 查资产分类/类型 | sangfor_xdr_assets |
asset_class |
| 查接入设备 | sangfor_xdr_assets |
device_list |
| 查部门组织树 | sangfor_xdr_assets |
department_tree |
| 删除资产 | sangfor_xdr_assets |
delete |
| 查已隔离主机 | sangfor_xdr_responses |
isolate_list |
| 解除主机隔离 | sangfor_xdr_responses |
unisolate |
| 查/增/改/删白名单 | sangfor_xdr_whitelists |
list / create / update / delete |
| 切换白名单启用状态 | sangfor_xdr_whitelists |
toggle_status |
| 系统运维、节点状态、CPU/内存/磁盘/IO趋势 | CDP 脚本 | 见浏览器模式 |
时间参数说明
- 时间字段支持 Unix 秒级时间戳或 ISO8601 字符串（如
"2024-01-01T00:00:00"） - 默认时间范围：最近 24 小时
- 需精确时间范围时，先用
uv run python计算时间戳再传参
关键返回字段
告警（list）
uuId：告警唯一IDname：告警名称riskLevel：风险等级（0=严重 1=高危 2=中危 3=低危 4=信息）severity：严重性分值(0-100)srcIp / dstIp：源/目的IPdealStatus：处置状态attackState：攻击状态（0=尝试 1=失败 2=成功 3=失陷）hostIp：受影响主机IPfirstTimestamp / lastTimestamp：首/末发现时间riskTag：风险标签数组
事件（list）
uuId：事件唯一IDname：事件名称riskLevel：风险等级alertIds：关联告警ID列表dataSource：数据来源（EDR/NDR）hostIp：受影响主机dealStatus：处置状态detectionStatus：检测状态（0=事中，1=事后）attackStory：攻击故事线(JSON)rootCauseAnalysis：根因分析(JSON)
高风险操作
| 工具 | action | 风险 | 说明 |
|---|---|---|---|
sangfor_xdr_responses |
unisolate |
需确认 | 解除主机隔离，恢复网络通信 |
sangfor_xdr_whitelists |
create/update/delete |
需确认 | 修改白名单规则，可能导致告警漏报 |
sangfor_xdr_assets |
delete |
需确认 | 删除资产记录 |
sangfor_xdr_vulns |
update_status |
需确认 | 修改漏洞修复状态 |
常见错误与回退
- API 返回 401/403 → 会话已失效，告知用户"XDR 会话已过期，请在浏览器中重新登录 XDR 后再试"
- 查询结果为空 → 确认时间范围和筛选条件
- 写操作（处置/删除）→ 必须先获用户明确授权
浏览器模式使用指南
⚠️ 进入浏览器模式前，必须询问用户 XDR URL（如
https://xdr.example.com/）。
请阅读以下文档获取完整流程：
- references/cdp-workflow.md
CDP 模式适用场景
- 系统运维页面（
#/apex-business/settings/run/state）：节点状态、CPU/内存/磁盘/IO 趋势、数据接入指标 - 页面详情、交互式筛选
- API 不可用的场景
可用工具脚本
| 脚本路径 | 功能 | 必需参数 |
|---|---|---|
references/fetch_xdr_system_state.py |
系统运行状态抓取 | --url {XDR_URL} |
脚本位于 skill 目录的 references/ 下，无硬编码 URL 或敏感信息。
执行示例
脚本位于 <flocks-plugins-root>/skills/sangfor-xdr-use/references/fetch_xdr_system_state.py，请按当前平台选择对应命令。
Windows（PowerShell）
powershell -Command "& '<FLOCKS_VENV>\Scripts\python.exe' '<FLOCKS_PLUGINS>\skills\sangfor-xdr-use\references\fetch_xdr_system_state.py' --url '{XDR_URL}'"
macOS / Linux（bash / zsh）
"<FLOCKS_VENV>/bin/python" "<FLOCKS_PLUGINS>/skills/sangfor-xdr-use/references/fetch_xdr_system_state.py" --url "{XDR_URL}"
占位符说明
| 占位符 | Windows 典型值 | macOS/Linux 典型值 |
|---|---|---|
<FLOCKS_VENV> |
D:\Flocks Project\flocks\.venv |
~/Flocks/flocks/.venv（取决于实际安装位置） |
<FLOCKS_PLUGINS> |
%USERPROFILE%\.flocks\plugins |
~/.flocks/plugins |
必须使用 Flocks 虚拟环境（
.venv）执行；系统 Python 可能缺少依赖。
API 与 CDP 功能对照
| 能力 | API 工具 | CDP 浏览器 | 说明 |
|---|---|---|---|
| 告警列表查询 | ✅ sangfor_xdr_alerts |
❌ | |
| 告警处置状态修改 | ✅ sangfor_xdr_alerts |
❌ | |
| 事件列表查询 | ✅ sangfor_xdr_incidents |
❌ | |
| 事件关联实体查询 | ✅ sangfor_xdr_incidents |
❌ | |
| 脆弱性/漏洞管理 | ✅ sangfor_xdr_vulns |
❌ | |
| 资产盘点 | ✅ sangfor_xdr_assets |
❌ | |
| 主机隔离/解除 | ✅ sangfor_xdr_responses |
❌ | |
| 白名单管理 | ✅ sangfor_xdr_whitelists |
❌ | |
| 系统运维状态 | ❌ | ✅ fetch_xdr_system_state.py |
需提供 --url {XDR_URL} |
关键坑点（必须避免）
| 坑 | 原因 | 解法 |
|---|---|---|
flocks browser -c js(...) 返回空文本 |
daemon session 指向错误的 tab | 用 Python socket 直连 daemon，通过 Runtime.evaluate 在正确 context 执行 |
flocks browser -c new_tab() 后后续命令无响应 |
tab 切换导致 session 错位 | 用 switch_tab(targetId) 明确切到 XDR tab |
| 多行代码转义失败 | PowerShell 引号嵌套 | 使用 fetch_xdr_system_state.py 脚本，无需手动转义 |
scroll() 导致 TimeoutError |
CDP mouse event 阻塞 | 避免在 XDR 页面使用 scroll，改用 captureBeyondViewport: true |
| XDR 页面数据为空或加载中 | 页面需等待渲染 | 导航后等待 3-5 秒再抓取 |
巡检数据输出格式
详见 references/xdr-inspection-template.md。