Add files via upload

README.md

@@ -132,7 +132,7 @@ CyberStrikeAI is an **AI-native security testing platform** built in Go. It inte
 - 🖼️ **Vision analysis (`analyze_image`)**: separate VL model (e.g. `qwen-vl-max`) via MCP for local screenshots, captchas, and UI; image bytes stay out of agent history (text summaries only). Configure `vision` in `config.yaml`; see [docs/VISION.md](docs/VISION.md)
 - 🎯 **Skills (refactored for Eino)**: packs under `skills_dir` follow **Agent Skills** layout (`SKILL.md` + optional files); **multi-agent** sessions use the official Eino ADK **`skill`** tool for **progressive disclosure** (load by name), with optional **host filesystem / shell** via `multi_agent.eino_skills`; optional **`eino_middleware`** adds patchtoolcalls, tool_search, **plantask** (`TaskCreate` / `TaskList` boards under `skills_dir/.eino/plantask/`), reduction, file **checkpoints** (`checkpoint_dir`), ChatModel **retries**, session **output key**, and Deep tuning—20+ sample domains (SQLi, XSS, API security, …) ship under `skills/`
 - 📱 **Chatbot**: Personal WeChat, WeCom, DingTalk, Lark, Telegram, Slack, Discord, and QQ Bot—chat from mobile or IM apps (see [Robot / Chatbot guide](docs/robot_en.md))
-- 🧑‍⚖️ **Human-in-the-loop (HITL)**: Chat sidebar to set approval mode and tool allowlists (listed tools skip approval); global list in `config.yaml` under `hitl.tool_whitelist`; **Apply** can merge new tools into the file and update the running server without restart; dedicated **HITL** page for pending approvals
+- 🧑‍⚖️ **Human-in-the-loop (HITL)**: Chat sidebar to set approval mode and tool allowlists (listed tools skip approval); global list in `config.yaml` under `hitl.tool_whitelist`; the Audit Agent can use a separate lightweight model via `hitl.audit_model`; **Apply** can merge new tools into the file and update the running server without restart; dedicated **HITL** page for pending approvals. See [HITL best practices](docs/hitl-best-practices_en.md)
 - 🐚 **WebShell management**: Add and manage WebShell connections (e.g. IceSword/AntSword compatible), use a virtual terminal for command execution, a built-in file manager for file operations, and an AI assistant tab that orchestrates tests and keeps per-connection conversation history; supports PHP, ASP, ASPX, JSP and custom shell types with configurable request method and command parameter.
 - 📡 **Built-in C2**: AI-oriented lightweight command-and-control—**listeners** (TCP reverse, HTTP/HTTPS beacon, WebSocket), **encrypted** beacon channel, **session** and **task** queues with persistence, **payload** helpers (one-liner / build / download), **SSE** live events, REST under `/api/c2/*`, plus unified MCP tools (`c2_listener`, `c2_session`, **`c2_task`**, `c2_task_manage`, `c2_payload`, `c2_event`, `c2_profile`, `c2_file`); optional **HITL** approval for sensitive operations and OPSEC-style controls (e.g. command deny rules). **Authorized testing only.**
 
@@ -265,7 +265,7 @@ Requirements / tips:
 - **WebShell management** – Add and manage WebShell connections (PHP/ASP/ASPX/JSP or custom). Use the virtual terminal to run commands, the file manager to list, read, edit, upload, and delete files, and the AI assistant tab to drive scripted tests with per-connection conversation history. Connections are stored in SQLite; supports GET/POST and configurable command parameter (e.g. IceSword/AntSword style).
 - **Built-in C2** – Create/start **listeners**, generate **payloads**, track **sessions**, enqueue **tasks**, and subscribe to **events** (SSE) from the Web UI or `/api/c2/*`. Agents and external clients use the C2 MCP tool family (including **`c2_task`**); when HITL is enabled, high-risk tasks can require human approval. Intended **only** for systems you are explicitly authorized to test.
 - **Settings** – Tweak provider keys, MCP enablement, tool toggles, and agent iteration limits.
-- **Human-in-the-loop (HITL)** – Sidebar sets mode and allowlisted tools (comma- or newline-separated); global list lives in `config.yaml` under `hitl.tool_whitelist`. **Apply** updates browser/server and can merge new tools into the file (**no restart**). **New chat** keeps sidebar choices; **HITL** nav shows pending approvals. Removing a tool in the sidebar does not remove it from the global list in `config.yaml`—edit the file if needed.
+- **Human-in-the-loop (HITL)** – Sidebar sets mode and allowlisted tools (comma- or newline-separated); global list lives in `config.yaml` under `hitl.tool_whitelist`. The Audit Agent can use a separate low-cost model through `hitl.audit_model`, useful when human reviewers cannot keep up. **Apply** updates browser/server and can merge new tools into the file (**no restart**). **New chat** keeps sidebar choices; **HITL** nav shows pending approvals. Removing a tool in the sidebar does not remove it from the global list in `config.yaml`—edit the file if needed.
 
 ### Built-in Safeguards
 - Required-field validation prevents accidental blank API credentials.
@@ -634,6 +634,7 @@ enabled: true
 - [Multi-agent mode (Eino)](docs/MULTI_AGENT_EINO.md): **Deep**, **Plan-Execute**, **Supervisor**, `agents/*.md`, `eino_skills` / `eino_middleware`, APIs, and chat/stream behavior.
 - [Graph orchestration guide](docs/workflow-graph_en.md): visual workflow design, node configuration, `previous` / `outputs` variable passing, and role binding.
 - [Robot / Chatbot guide](docs/robot_en.md): Setup, commands, and troubleshooting for WeChat, WeCom, DingTalk, Lark, Telegram, Slack, Discord, and QQ Bot.
+- [HITL best practices](docs/hitl-best-practices_en.md): reviewer modes, allowlists, Audit Agent prompts, and separate small-model configuration.
 
 ## Project Layout
 

README_CN.md

@@ -131,7 +131,7 @@ CyberStrikeAI 是一款 **AI 原生安全测试平台**，基于 Go 构建，集
 - 🖼️ **视觉分析（`analyze_image`）**：独立 Vision 模型（如 `qwen-vl-max`），MCP 工具分析本地截图/验证码/UI；图片仅在单次 VL 调用中出现，对话上下文只保留文字摘要。配置见 `config.yaml` → `vision` 与 [视觉分析说明](docs/VISION.md)
 - 🎯 **Skills（面向 Eino 重构）**：技能包放在 **`skills_dir`**，遵循 **Agent Skills** 目录规范（`SKILL.md` + 可选文件）；**多代理** 下通过 Eino 官方 **`skill`** 工具 **渐进式披露**（按 name 加载）。**`multi_agent.eino_skills`** 控制是否启用、本机文件/Shell 工具、工具名覆盖；**`eino_middleware`** 可选 patch、tool_search、**plantask**（`TaskCreate` / `TaskList` 任务板，落在 `skills_dir/.eino/plantask/`）、reduction、文件型 **checkpoint**（`checkpoint_dir`）、ChatModel **重试**、会话 **输出键** 及 Deep 调参。20+ 领域示例仍可绑定角色
 - 📱 **机器人**：个人微信、企业微信、钉钉、飞书、Telegram、Slack、Discord、QQ 机器人，在手机或 IM 中与 CyberStrikeAI 对话（详见 [机器人使用说明](docs/robot.md)）
-- 🧑‍⚖️ **人机协同（HITL）**：对话页侧栏配置协同模式与免审批工具白名单；全局列表在 `config.yaml` 的 `hitl.tool_whitelist`；点「应用」可将新增工具合并写入配置文件且**无需重启**即可生效；导航 **人机协同** 页处理待审批工具调用
+- 🧑‍⚖️ **人机协同（HITL）**：对话页侧栏配置协同模式与免审批工具白名单；全局列表在 `config.yaml` 的 `hitl.tool_whitelist`；审计 Agent 可通过 `hitl.audit_model` 使用独立小模型；点「应用」可将新增工具合并写入配置文件且**无需重启**即可生效；导航 **人机协同** 页处理待审批工具调用。详见 [人机协同最佳实践](docs/hitl-best-practices.md)
 - 🐚 **WebShell 管理**：添加与管理 WebShell 连接（兼容冰蝎/蚁剑等），通过虚拟终端执行命令、内置文件管理进行文件操作，并提供按连接维度保存历史的 AI 助手标签页；支持 PHP/ASP/ASPX/JSP 及自定义类型，可配置请求方法与命令参数。
 - 📡 **内置 C2**：面向 AI 协同的轻量 **C2**——**多种监听器**（TCP 反向、HTTP/HTTPS Beacon、WebSocket）、**加密** Beacon 信道、**会话与任务**队列及持久化、**Payload** 辅助（一键命令 / 构建 / 下载）、**SSE** 实时事件、REST（`/api/c2/*`）及智能体侧 **一组 C2 MCP 工具**（如 `c2_listener`、`c2_session`、**`c2_task`**、`c2_task_manage`、`c2_payload`、`c2_event`、`c2_profile`、`c2_file`）；敏感操作可对接 **人机协同（HITL）**，并支持 OPSEC 类规则（如命令拒绝正则）。**仅限授权测试。**
 
@@ -263,7 +263,7 @@ go build -o cyberstrike-ai cmd/server/main.go
 - **WebShell 管理**：添加并管理 WebShell 连接（PHP/ASP/ASPX/JSP 或自定义类型）。使用虚拟终端执行命令（带命令历史与快捷命令），使用文件管理浏览、读取、编辑、上传与删除目标文件，并支持按路径导航和名称过滤。连接信息持久化存储于 SQLite，支持 GET/POST 及可配置命令参数（兼容冰蝎/蚁剑等）。
 - **内置 C2**：在 Web 界面或 `/api/c2/*` 创建/启动 **监听器**、生成 **Payload**、查看 **会话**、下发 **任务** 并订阅 **事件（SSE）**。智能体与外部客户端通过 **C2 MCP 工具族**（含 **`c2_task`** 等）编排；开启人机协同时，高风险任务可走审批。**仅用于已获明确授权的目标。**
 - **可视化配置**：在界面中切换模型、启停工具、设置迭代次数等。
-- **人机协同（HITL）**：侧栏设置协同模式与免审批工具（逗号或换行）；全局白名单见 `config.yaml` 的 `hitl.tool_whitelist`。点「**应用**」可写浏览器/服务端并合并新增工具进配置（**无需重启**）。**新对话**保留侧栏选择；导航 **人机协同** 处理待审批。从侧栏删掉工具不会自动从配置文件移除全局项，需手改 `config.yaml`。
+- **人机协同（HITL）**：侧栏设置协同模式与免审批工具（逗号或换行）；全局白名单见 `config.yaml` 的 `hitl.tool_whitelist`。审计 Agent 可通过 `hitl.audit_model` 单独配置低成本模型，适合人工审计压力较大时接管常规审批。点「**应用**」可写浏览器/服务端并合并新增工具进配置（**无需重启**）。**新对话**保留侧栏选择；导航 **人机协同** 处理待审批。从侧栏删掉工具不会自动从配置文件移除全局项，需手改 `config.yaml`。
 
 ### 默认安全措施
 - 设置面板内置必填校验，防止漏配 API Key/Base URL/模型。
@@ -632,6 +632,7 @@ enabled: true
 - [多代理模式（Eino）](docs/MULTI_AGENT_EINO.md)：**Deep**、**Plan-Execute**、**Supervisor**、`agents/*.md`、`eino_skills` / `eino_middleware`、接口与流式说明。
 - [图编排使用说明](docs/workflow-graph.md)：可视化流程搭建、节点配置、`previous` / `outputs` 变量传参与角色绑定。
 - [机器人使用说明](docs/robot.md)：个人微信、企业微信、钉钉、飞书、Telegram、Slack、Discord、QQ 机器人的配置、命令与排查。
+- [人机协同最佳实践](docs/hitl-best-practices.md)：审批方模式、白名单、审计 Agent 提示词策略与独立小模型配置。
 
 ## 项目结构
 

docs/hitl-best-practices.md

@@ -0,0 +1,122 @@
+# 人机协同（HITL）最佳实践
+
+[English](hitl-best-practices_en.md)
+
+人机协同用于在 Agent 执行工具前做审批拦截。它适合控制高风险操作、保留审计痕迹，并在人工审计压力过大时让审计 Agent 接管常规审批。
+
+## 配置入口
+
+Web 端进入 **系统设置 → 人机协同**，可配置：
+
+- 全局默认审批方：`human` 或 `audit_agent`
+- 审计 Agent 专用模型：`hitl.audit_model`
+- 已决策审计日志保留天数
+- 免审批工具白名单：`hitl.tool_whitelist`
+- 审批模式与审查编辑模式的审计提示词
+
+对应的 `config.yaml` 示例：
+
+```yaml
+hitl:
+  default_reviewer: human
+  audit_model:
+    provider: ""
+    base_url: ""
+    api_key: ""
+    model: "" # 可填小模型；留空复用 openai.model
+  retention_days: 90
+  tool_whitelist: [read_file, list_dir, glob, grep, tool_search]
+```
+
+`audit_model` 的字段可以只填一部分。空字段会自动继承主 `openai` 配置，因此常见做法是只填 `model`，让审计 Agent 使用更便宜的小模型。
+
+## 推荐审批策略
+
+### 1. 默认人工，逐步放权
+
+刚开始建议：
+
+- `default_reviewer: human`
+- 仅把明显只读工具加入 `tool_whitelist`
+- 对写文件、执行命令、C2 任务、WebShell 操作保持人工审批
+
+运行一段时间后，观察审计日志，把重复、低风险、误报少的工具加入白名单。
+
+### 2. 人工审不过来时，用小模型接管常规审批
+
+当待审批积压明显时，可以切换为：
+
+```yaml
+hitl:
+  default_reviewer: audit_agent
+  audit_model:
+    model: "your-small-reviewer-model"
+```
+
+建议让小模型处理：
+
+- 只读查询
+- 信息收集
+- 端口与服务扫描
+- 目录枚举
+- 无破坏性的验证命令
+
+仍建议人工处理：
+
+- 删除、覆盖、清空数据
+- 修改权限、密码、账号
+- 持久化、横向移动、C2 高风险任务
+- 对生产目标的写入操作
+
+### 3. 用提示词定义组织策略
+
+审计 Agent 的提示词应该写成策略，而不是泛泛地说“谨慎审批”。建议明确：
+
+- 默认放行哪些低风险操作
+- 必须拒绝哪些破坏性操作
+- 哪些情况需要人工升级
+- 审查编辑模式下允许怎样收窄参数
+
+示例策略片段：
+
+```text
+常规信息收集、只读查询、端口扫描默认 approve。
+涉及删除文件、清空数据库、修改账号权限、写入持久化后门、停止关键服务时必须 reject。
+若目标范围超出用户授权范围，应 reject。
+审查编辑模式下，可将路径、目标、命令参数收窄后 approve，但不得扩大攻击面。
+```
+
+### 4. 白名单只放稳定低风险工具
+
+白名单工具会跳过审批，因此要保守维护。推荐放：
+
+- `read_file`
+- `list_dir`
+- `glob`
+- `grep`
+- `tool_search`
+
+不建议直接全局白名单：
+
+- 任意 shell 执行工具
+- 文件写入/删除工具
+- C2 任务工具
+- WebShell 命令执行工具
+
+## 模式选择
+
+| 模式 | 适用场景 |
+|------|----------|
+| 关闭 | 本地实验、完全信任工具链 |
+| 审批模式 | 只需要通过/拒绝 |
+| 审查编辑 | 希望审计 Agent 收窄参数后放行 |
+
+如果你已经配置了小模型审计，推荐从 **审批模式** 开始。只有当你希望 AI 自动收窄路径、目标范围或命令参数时，再开启 **审查编辑**。
+
+## 运维建议
+
+- 定期查看 **人机协同 → 审计日志**，调整白名单和提示词。
+- 高风险环境下保持 `default_reviewer: human`，只让审计 Agent 辅助给出建议。
+- 小模型审批失败时默认保守拒绝，这是预期行为。
+- 修改 `hitl.audit_model` 后先在页面点击 **测试审计模型**。
+- 对生产、客户、真实业务系统操作前，应保留人工最终确认。

docs/hitl-best-practices_en.md

@@ -0,0 +1,122 @@
+# Human-in-the-loop (HITL) Best Practices
+
+[中文](hitl-best-practices.md)
+
+HITL reviews tool calls before an Agent executes them. Use it to control high-risk operations, keep an audit trail, and let an Audit Agent take over routine approvals when human reviewers cannot keep up.
+
+## Where To Configure
+
+Open **System Settings → Human-in-the-loop** in the web UI. You can configure:
+
+- Global default reviewer: `human` or `audit_agent`
+- Dedicated Audit Agent model: `hitl.audit_model`
+- Resolved audit log retention days
+- No-approval tool allowlist: `hitl.tool_whitelist`
+- Audit prompts for approval mode and review-edit mode
+
+Example `config.yaml`:
+
+```yaml
+hitl:
+  default_reviewer: human
+  audit_model:
+    provider: ""
+    base_url: ""
+    api_key: ""
+    model: "" # set a small model here; blank reuses openai.model
+  retention_days: 90
+  tool_whitelist: [read_file, list_dir, glob, grep, tool_search]
+```
+
+`audit_model` supports partial configuration. Empty fields inherit from the main `openai` config, so the common setup is to fill only `model` and run approvals on a cheaper small model.
+
+## Recommended Approval Strategy
+
+### 1. Start With Humans, Then Delegate Gradually
+
+At the beginning, prefer:
+
+- `default_reviewer: human`
+- Only clearly read-only tools in `tool_whitelist`
+- Human approval for file writes, command execution, C2 tasks, and WebShell operations
+
+After observing audit logs, move repeated low-risk operations into the allowlist.
+
+### 2. Use A Small Model When Humans Cannot Keep Up
+
+When pending approvals start piling up, switch routine review to the Audit Agent:
+
+```yaml
+hitl:
+  default_reviewer: audit_agent
+  audit_model:
+    model: "your-small-reviewer-model"
+```
+
+Good candidates for small-model review:
+
+- Read-only queries
+- Reconnaissance
+- Port and service scans
+- Directory enumeration
+- Non-destructive validation commands
+
+Keep human review for:
+
+- Deleting, overwriting, or clearing data
+- Modifying permissions, passwords, or accounts
+- Persistence, lateral movement, and high-risk C2 tasks
+- Writes against production targets
+
+### 3. Encode Your Policy In The Prompt
+
+The Audit Agent prompt should describe an operational policy, not just say “be careful.” Make it explicit:
+
+- Which low-risk actions are normally approved
+- Which destructive actions must be rejected
+- Which cases require escalation to a human
+- How review-edit mode may narrow arguments
+
+Example policy snippet:
+
+```text
+Approve routine reconnaissance, read-only queries, and port scans by default.
+Reject file deletion, database clearing, account or permission changes, persistence, and stopping critical services.
+Reject actions outside the user-authorized target scope.
+In review-edit mode, you may narrow paths, targets, or command arguments before approving, but must not expand the attack surface.
+```
+
+### 4. Keep The Allowlist Conservative
+
+Allowlisted tools skip approval, so keep the list stable and low-risk. Recommended examples:
+
+- `read_file`
+- `list_dir`
+- `glob`
+- `grep`
+- `tool_search`
+
+Avoid globally allowlisting:
+
+- Arbitrary shell execution tools
+- File write/delete tools
+- C2 task tools
+- WebShell command execution tools
+
+## Mode Selection
+
+| Mode | Best for |
+|------|----------|
+| Off | Local labs or fully trusted toolchains |
+| Approval | Approve/reject only |
+| Review-edit | Let the Audit Agent narrow arguments before approval |
+
+If you configured a small audit model, start with **Approval** mode. Use **Review-edit** only when you want the AI to safely narrow paths, target ranges, or command arguments.
+
+## Operations Tips
+
+- Review **Human-in-the-loop → Audit logs** regularly and tune allowlists/prompts.
+- In high-risk environments, keep `default_reviewer: human` and use the Audit Agent only for recommendations.
+- If the small-model reviewer fails, CyberStrikeAI rejects conservatively by default.
+- After changing `hitl.audit_model`, click **Test audit model** in the settings page.
+- For production, customer, or real business systems, keep a human as the final approver.