redforge-ai

KO | EN

gitlite — search

#python #java #typescript #docker #nodejs #golang #tensorflow #react-native #node #keras #hacktoberfest #testing

★ 79 Open GitHub ↗

Open-core AI red teaming and offensive AI security evaluation platform.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# RedForge AI

简体中文 | [English](README.en.md)

[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://raw.githubusercontent.com/Aimer-zero/redforge-ai/main/)
[![Status](https://img.shields.io/badge/status-early%20preview-orange)](https://raw.githubusercontent.com/Aimer-zero/redforge-ai/main/)
[![Use](https://img.shields.io/badge/use-authorized%20testing%20only-red)](https://raw.githubusercontent.com/Aimer-zero/redforge-ai/main/)

**RedForge AI 是一个证据优先的 AI 红队评估框架**，面向 LLM 应用、RAG 系统、AI Agent、工具调用、记忆机制和模型供应链风险。

它不是简单的 jailbreak prompt 列表，而是帮助团队在授权范围内运行测试活动、记录可复现证据、评估发现、生成报告，并支持修复后的回归验证。

> RedForge 不是 C2 框架，不是通用 Web 扫描器，也不会证明“系统绝对安全”。它是一个用于授权 AI 安全评估的受控测试框架。

## 能做什么

- **范围受控的评估活动**：显式配置 target、allow-host、attack budget 和授权范围。
- **证据优先**：记录 payload、模型响应、RAG 检索内容、工具调用、记忆变更、副作用、评估理由和报告引用。
- **AI 原生风险面**：prompt injection、jailbreak、RAG poisoning、tool abuse、memory poisoning、泄漏/抽取抗性检查、配置漂移、多 Agent 信任边界。
- **CLI 与服务模式**：可直接命令行运行，也可启动 FastAPI 控制面。
- **可扩展架构**：公开 plugin 接口、target adapter、attack pack、report 和 schema。

## 快速开始

### 三步跑通本地 demo

```bash
make setup   # 检查 Python、uv 和项目虚拟环境
make demo    # 运行本地授权 demo campaign
uv run redforge doctor
open "$(uv run redforge latest-report --path-only --format html)"
```

demo 成功时，你会看到：

- 终端输出 `HTML_REPORT: artifacts/reports/<campaign_id>.html`
- 报告里有结果表、finding 卡片、payload、trace、原始响应、replay 命令和修复建议
- trace 文件写入 `artifacts/traces/<campaign_id>.jsonl`

`prove` 会用内置 vulnerable demo 自动跑出 confirmed finding、复放一个代表性 case、
导出 campaign 证据包，并打印最重要的路径：

- `HTML_REPORT`：先打开它，看 payload、AI 返回、证据、replay 命令和修复建议
- `trace_jsonl`：完整执行轨迹
- `export_bundle`：可给安全/研发复核的证据包
- `redforge show-trace <campaign_id> --format human`：人类可读攻击路径摘要

### 环境要求

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)

### 从源码运行

```bash
git clone https://github.com/Aimer-zero/redforge-ai.git
cd redforge-ai
make setup
make demo
```

也可以运行 smoke 脚本：

```bash
./scripts/demo_mvp.sh
```

查看最新报告路径：

```bash
uv run redforge latest-report --path-only --format html
uv run redforge latest-campaign
uv run redforge campaign-status
```

导出 campaign：

```bash
uv run redforge export-campaign
uv run redforge export-campaign <campaign_id> --out redforge-campaign.zip
```

## 常用命令

```bash
make test        # ruff + migration gates + pytest
make build       # 构建所有 workspace packages
make clean       # 清理生成物和缓存
make api         # 启动 API 服务
make smoke-api   # API smoke test
make agent       # 启动内置 vulnerable demo agent
```

默认生成物目录：

```text
artifacts/
  campaigns/   campaign summaries
  traces/      JSONL evidence traces
  payloads/    replayable payload files
  reports/     Markdown and HTML reports
```

这些文件可能包含目标响应和测试证据，分享前请先审查。

## 让 OpenClaw / 其他 agent 使用 RedForge

RedForge 现在提供 stdio MCP server，OpenClaw、Codex、Claude Code 或任意
MCP-compatible agent 都可以把 RedForge 当成工具来调用。先查看可安装的 agent
集成方式：

```bash
uv run redforge agent list
```

生成 OpenClaw 集成计划（默认只是 dry-run，不会改本机）：

```bash
uv run redforge agent install openclaw
```

确认后可写入全局 `redforge` skill。RedForge 不会安装 OpenClaw，也不会调用
OpenClaw CLI 自动改配置；MCP 配置请使用 dry-run 输出里的 `mcp_config_snippet`
手动加入你的 agent 客户端。

```bash
uv run redforge agent install openclaw --yes
```

如果你是在源码 checkout 里使用，还没有把 `redforge` 安装到全局 PATH，可以让
agent 通过 `uv run redforge mcp` 启动 MCP server：

```bash
uv run redforge agent install openclaw \
  --mcp-command uv \
  --mcp-args-json '["run","redforge","mcp"]'
```

其他 agent 只要支持 MCP，就使用 dry-run 输出里的 `mcp_config_snippet`：

```json
{
  "mcpServers": {
    "redforge": {
      "command": "redforge",
      "args": ["mcp"]
    }
  }
}
```

Agent 侧拿到 RedForge 后，优先使用这些 MCP tools：`redforge_doctor`、
`redforge_http_dry_run`、`redforge_run_http_campaign`、
`redforge_run_registered_target`、`redforge_latest_report`。

## 测试 HTTP 目标

完整示例见：

- [`examples/README.md`](examples/README.md)
- [`examples/custom_http_fastapi/app.py`](examples/custom_http_fastapi/app.py)
- [`docs/custom_http_target.md`](docs/custom_http_target.md)

```bash
uv run redforge run-http \
  --url https://example.test/chat \
  --allow-host example.test \
  --attack-budget 5
```

不想手写完整命令时，可以先生成可复用 target 配置：

```bash
uv run redforge connect \
  --target-type custom_http \
  --project-id demo \
  --target-id customer-chat \
  --url https://example.test/chat \
  --allow-host example.test \
  --body-template '{"message":"{{payload}}"}' \
  --response-json-path answer \
  --out target.json
uv run redforge validate-target --config target.json
```

## 测试 OpenAI-compatible API

复制 [`.env.example`](.env.example)，然后参考 [`docs/openai_compatible_target.md`](docs/openai_compatible_target.md)。

```bash
OPENAI_API_KEY=sk-... uv run redforge run-openai \
  --base-url https://api.openai.com/v1 \
  --model gpt-5 \
  --allow-host api.openai.com \
  --attack-catalog datasets/seed_attacks/default.md
```

也可以通过环境变量配置默认 provider：

```bash
export REDFORGE_OPENAI_MODEL="gpt-5"
export REDFORGE_ANTHROPIC_MODEL="claude-sonnet-4-6"
export REDFORGE_GEMINI_MODEL="gemini-3.1-pro-preview"
```

## Breakthrough proof mode

Breakthrough mode 会按 LLM/Agent 边界规划可复放 proof chain，并区分
`confirmed_finding`、`near_miss` 和 `no_signal`；工具、RAG、memory、browser、
code-agent 等边界需要真实 trace/side-effect/retrieval/memory 证据，不能只凭模型自称确认。

```bash
uv run redforge breakthrough-run \
  --target-type local_demo \
  --suites foundation_model,tool_abuse \
  --allowed-tools send_email \
  --budget 2
```

更多 CLI/API/产物说明见 [`docs/breakthrough_mode.md`](docs/breakthrough_mode.md)。

## 服务模式

```bash
uv run uvicorn redforge_api.main:app --host 127.0.0.1 --port 8000
```

常用接口：

- `GET /health`
- `POST /v1/campaigns/local-demo/run`
- `POST /v1/campaigns/openai-compatible/run`
- `POST /v1/campaigns/custom-http/run`
- `POST /v1/breakthrough/run`
- `GET /campaigns`
- `GET /campaigns/{campaign_id}`
- `GET /campaigns/{campaign_id}/report`
- `GET /campaigns/{campaign_id}/trace?limit=20`

## 架构概览

```mermaid
flowchart LR
  CLI["CLI"] --> Control["Control Plane"]
  API["FastAPI Service"] --> Control
  Worker["Worker"] --> Engine["Campaign Engine"]
  Control --> Engine
  Engine --> Scope["Scope Guard"]
  Engine --> Attacks["Attack Packs"]
  Engine --> Targets["Target Adapters"]
  Engine --> Eval["Evaluators"]
  Targets --> Obs["Observations"]
  Obs --> Evidence["Evidence Trace"]
  Eval --> Evidence
  Evidence --> Reports["Reports"]
  Plugins["External Plugins"] --> Attacks
  Plugins --> Targets
```

主要 package：

```text
packages/redforge-core           核心模型、scope guard、证据、指标、报告
packages/redforge-plugins        plugin SDK、registry、loader、capabilities
packages/redforge-attacks-basic  公开基础 attack pack
packages/redforge-targets        target adapters 和 demo runtime
packages/redforge-engine         campaign 编排、评估器、记忆、规划
packages/redforge-control        projects、findings、live sessions、CI/policy services
packages/redforge-api            FastAPI service
packages/redforge-cli            CLI entrypoints
packages/redforge-worker         worker process
```

更多细节见 [`docs/architecture.md`](docs/architecture.md)。

## 内置公开攻击目录

公开基础目录位于：

- `datasets/seed_attacks/default.md`
- `datasets/seed_attacks/default.json`

真实目标测试必须显式设置 scope，例如 target ID、allowed hosts、allowed suites、allowed tools、attack budget 和授权信息。

## 一文件配置

```bash
uv run redforge run --config redforge.example.yml
```

`redforge.example.yml` 包含 target、scope、attack budget、suites、CI gate、report 和 artifact retention 示例。

## 本地报告查看器

```bash
uv run redforge report serve --open
uv run redforge report open latest
```

## 项目边界

这个公开仓库只包含可复用的开源运行时：scope 控制、campaign 执行、target adapter、证据 trace、报告、plugin 接口和公开基础 attack pack。

不包含：

- 私有客户集成
- 比赛/竞赛专用实现
- 企业私有 attack pack
- 私有部署 overlay
- 破坏性或无授权范围的自动化能力

## 合规使用

| 适合使用 RedForge | 不适合使用 RedForge |
|---|---|
| 对自己拥有、运营或明确授权的 AI 系统做安全评估 | 扫描未授权第三方系统 |
| 在 allow-host 和预算限制内运行 campaign | C2、持久化、越权利用或破坏性操作 |
| 生成证据、报告、replay 和修复回归验证 | 声称系统“绝对安全” |
| 团队 triage prompt injection、RAG、tool、memory、agent 风险 | 未审查就上传敏感目标证据 |

推荐流程：明确书面授权 → 注册 target → 设置 `--allow-host` → 运行有限预算 campaign → 本地审查 artifacts → triage findings → 修复后 replay 验证。

## 开发

```bash
uv run ruff check .
uv run python scripts/check_migration_gates.py
uv run pytest -q
```

贡献说明见 [`CONTRIBUTING.md`](CONTRIBUTING.md)，安全报告说明见 [`SECURITY.md`](SECURITY.md)。

## 项目状态

RedForge 目前处于 early preview。公开 API、schema 和 CLI 命令在稳定版本前可能变化。当前仓库适合从源码运行、本地 demo、实验和授权评估工作流。

## 社区与友链

- [LINUX DO](https://linux.do) — 开发者与开源社区。

## 许可证

RedForge AI 使用 MIT License。详见 [`LICENSE`](LICENSE)。

redforge-ai

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README