---
title: "harness - HitlStrategy 安全审计策略"
---



`HitlStrategy` 是 `solon-ai-harness` 内置的 HITL（Human-in-the-Loop）安全审计策略，默认绑定到 `bash` 工具。当 `hitlEnabled=true` 时，所有 `bash` 工具调用在执行前都会经过 `HitlStrategy.evaluate()` 审计，高危命令会被拦截并要求人工确认。

### 1、七层安全防护体系

`HitlStrategy` 实现了分层递进的安全审计，从 A 到 G 共七层：

#### A. 注入与子 Shell 防御（最高优先级）

拦截反引号、`$(...)` 子 Shell 展开、以及重定向到系统设备（`/dev/`）的命令：

```
检测到潜在的命令注入或设备重定向风险。
```

匹配规则：命令中包含反引号 `` ` ``、`$()` 子 Shell 语法、或 `/dev/` 设备路径。

#### B. 系统级安全（绝对黑名单）

拦截系统特权与身份篡改命令、进程与资源控制命令：

* **特权与身份篡改**：`sudo`、`su`、`chown`、`chmod`、`chgrp`、`passwd`、`visudo`、`alias`、`unalias`
* **进程与资源控制**：`kill`、`pkill`、`xargs`、`nohup`、`disown`、`reboot`、`shutdown`、`init`、`systemctl`、`service`

```
检测到系统特权或进程控制指令 [...]
```

#### C. 路径边界检查（严格限制）

* **路径回溯**：拦截 `../` 或 `..\` 路径回溯操作，禁止访问工作区外目录。
* **敏感目录**：拦截 `/etc/`、`/var/`、`/root/`、`~/.ssh/`、`~/.bashrc`、`~/.zshrc` 等敏感配置文件。

```
检测到路径回溯操作，禁止访问工作区外目录。
禁止访问系统敏感配置文件。
```

#### D. 包管理与环境变更（分级策略）

对包管理器和环境变更工具进行分级拦截。只要包含修改性子命令（如 `install`、`add`、`remove`、`rm`、`publish`、`push`、`commit`、`checkout`、`update`、`upgrade`、`stop`、`prune`、`build`、`config`、`set`），就需要人工确认。

拦截的工具：`apt`、`yum`、`dnf`、`npm`、`pnpm`、`yarn`、`pip`、`docker`、`kubectl`、`git`、`brew`、`cargo`

```
检测到环境变更或包管理修改操作。
```

#### E. 网络行为（零信任原则）

任何非 `--help` / `--version` 的网络工具调用都需要拦截：

拦截的工具：`curl`、`wget`、`ssh`、`scp`、`ftp`、`nc`、`telnet`、`dig`、`nslookup`、`ping`

```
检测到网络外连或远程探测指令。
```

#### F. 管道与命令组合（只读安全链）

* **多命令组合**：拦截包含 `;` 或 `&` 的命令组合，确保审计追踪。
* **管道操作**：只允许管道流向安全工具白名单，拦截非法管道链。

管道安全工具白名单：`grep`、`head`、`tail`、`awk`、`sort`、`uniq`、`wc`、`jq`、`column`、`less`、`sed`、`xxd`

```
禁止执行多条组合命令以确保审计追踪。
检测到潜在风险的管道链操作。
```

#### G. 破坏性文件操作

* **递归删除**：拦截 `rm -r` / `rm -rf` / `rm -Rf` 以及 Windows 的 `rd /s` / `rmdir /s`。
* **文件移动**：拦截 `mv` 命令（可能导致数据丢失）。

```
检测到递归删除操作 [...]。
检测到文件移动操作 [...]。
```

### 2、放行规则

基础查询命令（如 `ls`、`cat`、`pwd`、`echo`、`find` 等）全数放行，无需人工确认。

### 3、自定义安全策略

如果内置的 `HitlStrategy` 不能满足需求，可以实现自定义的 `HITLInterceptor.InterventionStrategy`：

```java
HITLInterceptor hitl = new HITLInterceptor();
hitl.onTool("bash", new HITLInterceptor.InterventionStrategy() {
    @Override
    public String evaluate(ReActTrace trace, Map<String, Object> args) {
        String cmd = (String) args.get("command");
        // 自定义审计逻辑
        if (isDangerous(cmd)) {
            return "检测到危险操作:" + cmd;
        }
        return null; // 放行
    }
});

HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .hitlInterceptor(hitl)
        .hitlEnabled(true)
        .build();
```

也可以对多个工具绑定不同的策略：

```java
hitl.onTool("bash", new BashAuditStrategy());
hitl.onTool("write", new WriteAuditStrategy());
```

### 4、运行时开关

```java
engine.setHitlEnabled(true);   // 启用人工介入
engine.setHitlEnabled(false);  // 禁用人工介入
```

`setHitlEnabled` 会同步更新引擎配置和拦截器的 enabled 状态。