mirror of
https://github.com/Ed1s0nZ/CyberStrikeAI.git
synced 2026-07-10 22:33:48 +02:00
Add files via upload
This commit is contained in:
公明
@@ -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` 后先在页面点击 **测试审计模型**。
|
||||
- 对生产、客户、真实业务系统操作前，应保留人工最终确认。
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user