agentflocks 深信服 EDR Use
核心功能
实现边界：sangfor_edr_http_login.py 负责 HTTP 登录、认证探测、
auth-state.json Cookie 及 Secret Manager token bundle；
sangfor_edr_dashboard_api.py 负责仪表盘 API 请求，只读取 HTTP 登录模块
验证过的同一套 Cookie/token，不从其他状态源拼接凭据。
sangfor_edr_threat_assets_api.py 负责威胁资产分析 API 请求，同样只读取
HTTP 登录模块验证过的同一套 Cookie/token。
sangfor_edr_asset_inventory_api.py 负责资产清点页面 API 请求，同样只读取
HTTP 登录模块验证过的同一套 Cookie/token。
sangfor_edr_advanced_threat_api.py 负责高级威胁告警模式和事件模式 API 请求，
同样只读取 HTTP 登录模块验证过的同一套 Cookie/token。
- 管理同一次登录产生的 Cookie 与
login_token。 - 默认使用 HTTP 登录，开始前必须向用户索取并保存 EDR 地址、用户名和密码。
- 仅当用户明确选择“打开页面后手动登录”时，才可不索取账密并直接使用 browser/CDP。
- HTTP 登录连续 3 次失败后，按“browser/CDP 自动化登录（仍需账密）→保留页面供用户手动登录（不需账密）”顺序降级。
- 每次登录或数据采集前探测现有认证，认证有效则跳过登录，失效则重新登录并更新存储。
- 通过 API 采集首页终端概况、受影响终端、漏洞、勒索防护、实时病毒、Top 5 终端和设备资源使用率。
- 通过 API 采集威胁资产分析的风险汇总、资产分组和威胁终端事件列表，支持风险级别、资产分组、终端状态、隔离状态和分页筛选。
- 通过 API 采集资产清点页面的资产分类统计。
- 通过 API 采集高级威胁的告警模式和事件模式列表，支持多选筛选、时间范围和自动分页。
输入与输出
认证工具
调用 sangfor_edr_auth：
status_auth_state：返回认证文件、凭据和认证探测状态，不返回敏感值。ensure_auth_state、refresh_auth_state、http_login：执行“探测后按需 HTTP 登录”；HTTP 连续 3 次失败时按降级策略进入 browser/CDP，再失败则转为手动登录。browser_login：用户明确选择自动化登录时，执行“探测后按需 browser/CDP 登录”；该路径需要账密，除非用户明确要求打开页面后自行手动登录。validate_auth_state：仅验证浏览器 state。complete_manual_login：保存用户在已打开浏览器中完成的登录。
成功输出包含 status、valid、login_skipped 和非敏感探测结果；失败输出包含稳定的 reason 与恢复建议。
仪表盘工具
调用 sangfor_edr_dashboard，可输入：
sections：可选采集项；省略时采集全部仪表盘数据。days：统计时间范围，允许 1–90 天。base_url、auth_state_path：可选运行时覆盖。
输出包含 data、errors、sections、days 和本次认证是复用还是重登；不得输出 Cookie、密码或 login_token。
威胁资产分析工具
调用 sangfor_edr_threat_assets，可输入：
sections：risk_summary、zones、agent_events，省略时采集全部数据。days：威胁终端事件时间范围，允许 1–90 天。info：用户在搜索框输入的终端名称、IP 地址或资产使用人关键词，原样放入list_agent_event.filter.info。risk_level、host_type、zone_name、agent_state、isolate_agent：威胁资产筛选条件；用户使用中文条件时由 Skill 转换为接口枚举值。page、limit、paginate：事件列表分页配置；limit仅允许 10、20、50、100、500，默认自动采集至total_items。base_url、auth_state_path：可选运行时覆盖。
输出包含风险汇总、资产分组、事件列表、分页信息和接口错误；不得输出 Cookie、密码或 login_token。
资产清点工具
调用 sangfor_edr_asset_inventory，可输入：
scene_type：资产清点范围，默认server_and_pc。base_url、auth_state_path：可选运行时覆盖。
输出包含原始资产分类响应、带中英文标签的 readable_data 和接口错误；不得输出 Cookie、密码或 login_token。
分类字段映射由采集模块维护；Replace 按页面显示映射为“真替真用”，英文保留原始字段名 Replace。
高级威胁工具
调用 sangfor_edr_advanced_threat，可输入：
sections：warning_logs、incidents；省略时采集两种模式。threat_levels：威胁等级单值或多值。disposal_states、event_disposal_states、agent_types、detect_sources、event_types：事件模式多选条件。wl_switch：已例外告警单选；0=隐藏，1=显示。days：默认最近 7 天；或成对提供begin_time、end_time。page_no、page_limit、paginate：分页配置，默认自动采集全部。base_url、auth_state_path：可选运行时覆盖。
输出包含 data/raw_data、readable_data、分页元数据和分项 errors；不得输出 Cookie、密码或 login_token。
关键配置
base_url：从用户提供的 EDR 地址提取 scheme、host 和 port；不得使用固定示例地址。username、password：从设备配置或 Secret Manager 读取。auth_state_path：Cookie state 文件位置。auto_ocr_code、max_captcha_retry：HTTP/browser 登录验证码配置。- selector 和页面路径配置仅用于 browser/CDP 登录。
EDR 交互协议
- 从 Secret Manager 与
auth-state.json加载成套认证，并校验 base URL 和 Cookie 指纹。 - 使用 Cookie 与
login_token调用威胁终端概览接口get_agent_overview：- HTTP 200、无登录页重定向、响应成功且包含终端概览数据：认证有效，跳过登录。
- Cookie 缺失或不匹配、401/403、重定向、非 200、响应无终端概览数据：认证失效。
- 默认重新登录流程：访问登录页，获取 RSA 公钥和验证码，提交
dlogin，调用launch_login.php，再 GET/ui；HTTP 登录连续 3 次失败后进入 browser/CDP 自动化登录，自动化登录仍需账密，自动化登录失败后保留页面供用户手动登录。 - 登录成功后将 Cookie 写入
auth-state.json，将login_token写入 Secret Manager，并更新配对指纹。 - 仪表盘 API 只能使用通过上述探测的同一套 Cookie/token；禁止从不同 state 或 Secret 拼接。
- 威胁资产分析 API 使用以下接口：
POST /launch.php?s={login_token}&opr=list_risk_agent_total_count：风险级别和隔离终端汇总。POST /launch.php?s={login_token}&opr=list_zones：资产分组列表，payload 使用data.local=true。POST /launch.php?s={login_token}&opr=list_agent_event：威胁终端事件列表，payload 使用filter.info（终端名称/IP/资产使用人关键词）、其他筛选条件、day_sum、page和limit；分页采集直到返回的total_items收集完成。- 三个接口均使用当前登录会话的 Cookie、动态
query_id和同一login_token。
- 威胁资产筛选枚举映射：
risk_level：空值=全部，0=低风险，1=中风险，2=高风险。host_type：0=PC 终端，1=服务器终端；用户说“PC/服务器”时转换为对应数字，不能把中文直接放入 payload。agent_state：-1=全部终端状态，0=在线，1=离线，2=已禁用，3=未授权，4=已卸载，6=已降级。limit：只能使用10/20/50/100/500。zone_name：先调用list_zones，按返回的zone_name或full_zone_name精确匹配，再将对应的设备专属zone_id放入list_agent_event.filter.zone_id；不能使用固定 zone ID，也不能把中文分组名直接作为zone_id。
- 资产清点 API 使用
POST /api/edrgoweb/v1/asset/inventory/classify?s={login_token}，payload 为{"sceneType":"server_and_pc"}；复用当前登录会话的 Cookie 和同一login_token，接口返回code != 0时视为失败。 - 高级威胁 API 使用：
POST /api/edrgoweb/v1/advthreats/querywarninglogs?_method=get&s={login_token}：告警模式列表，只发送已确认的threatLevel、wlSwitch筛选。POST /api/edrgoweb/v1/advthreats/queryincidentinfo?_method=get&s={login_token}：事件模式列表，发送威胁等级、处置状态、实时防护、终端类型、检测来源、事件标签、时间范围和已例外告警筛选。uuid是动态请求关联标识，不是设备 ID；uid默认使用当前登录用户名，tid默认0。
- 高级威胁筛选映射：
threatLevel：5=严重、4=高危、3=中危、2=低危、1=信息。disposalState：0=待处置、2=已处置、3=已忽略。eventDisposalState：0=暂不支持、1=未处置、2=自动处置中、3=已自动处置。agentType：0=PC、1=服务器。detectSource：1=IOC引擎、2=IOA引擎、3=SIP联动、6=MS引擎、8=AF联动；响应中的未知值保留原值并标记“未知”。eventType：1=钓鱼攻击、2=Web入侵、3=恶意病毒、0=其他。- 除时间范围和
wlSwitch外，上述业务筛选均支持多选。
错误处理
- 缺少地址或账密：返回缺失字段，向用户索取后保存到配置或 Secret Manager。
- 验证码或 HTTP 登录失败：最多进行 3 次独立 HTTP 登录尝试；仍失败则切换 browser/CDP 自动化登录，切换时仍需账密。
- browser/CDP 自动化登录失败或用户明确选择打开页面后手动登录：保留浏览器供用户完成登录，不再索取账密，再调用
complete_manual_login。 - 认证探测失败：禁止继续业务 API；先执行 HTTP 重登并再次探测，连续 3 次 HTTP 仍失败则按 browser/CDP 自动化登录→手动登录降级。
- 仪表盘部分接口失败：保留成功数据，在
errors中按采集项返回失败原因。 - 资产清点接口失败：在
errors中返回接口失败原因，不输出敏感认证信息。 - 高级威胁单个模式失败：保留另一个模式的成功数据，并在
errors中按模式返回脱敏原因。 - Cookie、密码和
login_token不得回显、记录日志或混入业务输出。
执行约束
- 运行本 Skill 提供的 Python 脚本时，必须使用 Flocks 虚拟环境；禁止使用系统 Python。
- 不得假设 Flocks 项目、插件或虚拟环境的绝对路径；代码必须通过当前运行时加载的模块、
Path.home()、~/.flocks或显式配置/环境变量解析路径。 - 需要具体 CDP 命令、浏览器启动方式、验证码识别、selector、tab/iframe 处理或页面关键词时，必须先阅读 references/cdp-workflow.md，不要在本文件重复展开。
bu.port是 Flocks browser daemon 的 IPC 端口文件，不是 Chrome remote-debugging 端口；禁止手工创建或修改。- 默认认证和仪表盘采集开始时不得启动 browser daemon；只有用户明确选择
browser_login、执行validate_auth_state/complete_manual_login，或 HTTP 登录连续 3 次失败进入降级流程时，才允许使用 browser/CDP。 - HTTP 登录连续 3 次失败后必须按 browser/CDP 自动化登录→手动登录顺序降级；自动化登录阶段仍需账密，手动登录阶段不得要求账密。
- 任何 API 采集前必须完成认证探测；认证探测失败时不得继续调用业务接口。
- 威胁资产分析的分页请求必须复用同一套 Cookie/token，不得在分页过程中重新拼接或替换认证参数。
- 资产清点 API 请求必须复用同一套 Cookie/token；不得把抓包中的 sessionid、token 或设备地址写死为通用凭据或地址。
- 高级威胁分页必须复用同一套 Cookie/token；不得输出响应
req中的 token，也不得把抓包中的uid、token、Cookie 或设备地址写死。 - 用户未提供接口参数名时，必须根据中文语义完成上述映射；无法确认的筛选条件不得猜测数值，应省略筛选或向用户确认。