# 快速开始

## 安装

需要 Python 3.11+。

### 方式一：pipx（推荐，普通用户）

```bash
pipx install agentsec-eval
```

或用 `uv`（按需运行，无须持久安装）：

```bash
uvx --from agentsec-eval agentsec --help
```

PyPI 包名是 `agentsec-eval`（`agentsec` 已被另一个项目占用），CLI 命令仍是 `agentsec`。

### 方式二：源码（开发 / 贡献）

```bash
git clone https://github.com/raoliaoyuan/AgentSec.git
cd AgentSec
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

## 配置 LLM 评判器

LLM / hybrid 类的测试用例需要一个评判模型（deterministic-only 套件可跳过）。AgentSec 支持任意主流提供商，按下面任选一种导出环境变量即可：

```bash
# Anthropic Claude（默认）
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export AGENTSEC_LLM_PROVIDER=openai \
       AGENTSEC_LLM_BASE_URL=https://api.openai.com/v1 \
       AGENTSEC_LLM_MODEL=gpt-4o-mini \
       AGENTSEC_LLM_API_KEY=sk-...

# DeepSeek（OpenAI 兼容）
export AGENTSEC_LLM_BASE_URL=https://api.deepseek.com/v1 \
       AGENTSEC_LLM_MODEL=deepseek-chat \
       AGENTSEC_LLM_API_KEY=sk-...

# 本地 Ollama
export AGENTSEC_LLM_BASE_URL=http://127.0.0.1:11434/v1 \
       AGENTSEC_LLM_MODEL=qwen2.5:14b \
       AGENTSEC_LLM_API_KEY=ollama
```

完整的提供商矩阵（Qwen、Moonshot、OpenRouter、Together、vLLM、MLX 等）见 [README 中的「用环境变量切换提供商」](../../README.md#用环境变量切换提供商不写-yaml-也行)。

> 进阶用法：在 `openclaw-target.yaml` 里写 `judge:` 段可以做更细粒度的控制（比如同一次 `multi-evaluate` 里不同目标用不同评判器）；yaml 优先级高于环境变量。

## 运行第一次评估

> pipx 用户的 cwd 里没有仓库自带的 `test_suites/` —— 可以从 [GitHub](https://github.com/raoliaoyuan/AgentSec/tree/main/test_suites) 拷一份，或写自己的 YAML 套件，或用社区市场：`agentsec suite install <name>` 后 `agentsec run --suite <name>`。

```bash
# 使用本地测试用例对目标 Agent 做完整评估
agentsec run ./test_suites/ \
  --target http://your-agent-host:8080 \
  --name "my-agent" \
  --output report.md

# 只跑单个类别
agentsec run ./test_suites/prompt_injection.yaml \
  --target http://your-agent-host:8080 \
  --name "my-agent"
```

评估完成后，`report.md` 包含按严重度分类的失败列表和 judge 的推理说明。

## 目录结构

```
test_suites/          # 内置攻击测试用例（YAML）
src/agentsec/
  adapters/           # 目标 Agent 接口适配器
  evaluator/          # LLM-as-Judge 评判器
  reports/            # 报告渲染
  runner.py           # 并发调度
  cli.py              # CLI 入口
docs/
  adr/                # 架构决策记录
  guide/              # 用户手册（本目录）
```

## 服务器侧审计（v0.2.0，全 10 项检查）

Server-audit 通过只读 SSH 探针对已部署的 OpenClaw 实例做主机级体检，输出经过 redaction 的 findings。v0.2.0 共执行 10 项检查：

**Stage D（4 项）：** `native_audit`、`config_audit`、`version_patch`、`active_test`  
**Stage E（6 项）：** `exposure_scan`、`filesystem`、`process_forensics`、`credential_audit`、`plugin_static`、`log_review`

IOC 文件（`cve_database.json`、`clawhavoc_skills.json`、`attack_signatures.yaml`）位于 `src/agentsec/audit/ioc/`，默认自动加载，无需额外配置。

1. 生成签名密钥：

   ```bash
   python -c "import secrets; print(secrets.token_urlsafe(32))" > /tmp/key
   export AGENTSEC_AUTH_SIGNING_KEY=$(cat /tmp/key)
   ```

2. 把仓库根目录的 `AUTHORIZATION.txt.example` 复制为 `AUTHORIZATION.txt`，填好 `target_host`、有效期与 `report_output_path_prefix`。

3. 计算并填入签名：

   ```bash
   python -c "import os; from agentsec.audit.authorization import Authorization; \
     a = Authorization.load('AUTHORIZATION.txt'); \
     print(a.compute_signature(os.environ['AGENTSEC_AUTH_SIGNING_KEY'].encode()))"
   ```

   把输出粘进 `signature:` 字段。

4. 运行：

   ```bash
   .venv/bin/agentsec server-audit \
     --host openclaw.example.com --user ubuntu --key ~/.ssh/id_rsa \
     --consent-file AUTHORIZATION.txt --output ./report-2026-04-27/ \
     --policy-path src/agentsec/audit/ssh_policy.yaml   # 可选，覆盖默认策略路径
   ```

   > **注意：** `--skip-active-test` 标志已在 v0.2.0（Stage E）移除。`active_test` 始终注册；若 SSH 隧道建立失败，该检查会自动跳过（`not_applicable`），不会中断整个审计流程。

输出会写到 `--output` 目录：`findings.json`、`server-audit-report.md`、`audit-log.jsonl`。

如果 `AUTHORIZATION.txt` 用了 `signature_mode: none` 或者 `identity_assertion` 留空，CLI 会打印 `LOW_ASSURANCE` 横幅，报告里也会标注。

## 在 GitHub Actions 中跑

仓库自带一份示例工作流：[`.github/workflows/agentsec-evaluate.yml.example`](../../.github/workflows/agentsec-evaluate.yml.example)。把它复制到自己的 OpenClaw 部署仓库（去掉 `.example` 后缀），按文件头注释配齐 `ANTHROPIC_API_KEY`、`OPENCLAW_API_KEY`、`OPENCLAW_SSH_KEY` 三个 Repository Secret，再放一份 `openclaw-target.yaml` 即可。

工作流会按 cron 触发 `agentsec evaluate`，把六份产物（`combined-report.md` / `findings.json` 等，spec §9.3）作为 GitHub artifact 上传，并在 job summary 中输出 Grade 行。

## 对比两次运行结果

拥有两次 `agentsec evaluate` 的输出（例如昨天和今天的 cron 运行）后，可以用以下命令对比：

```bash
agentsec diff path/to/report-2026-04-29/ path/to/report-2026-04-30/ \
  --output diff.md
```

输出是一份 Markdown 文件，显示发生了哪些变化：新增和已解决的 findings、来自威胁情报更新的严重度升级，以及评分 / 覆盖率回归。可用于 PR 评论或每周摘要。

## 下一步

- [编写自定义 Adapter](./writing-adapters.md) — 接入 OpenClaw、Hermes 等目标 Agent
- [编写测试用例](./writing-test-cases.md) — 扩展攻击测试库
