# RedScope AI

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

[![license: Anti 996](https://img.shields.io/badge/license-Anti%20996-blue.svg)](https://github.com/996icu/996.ICU/blob/master/LICENSE)
[![link: 996.icu](https://img.shields.io/badge/link-996.icu-red.svg)](https://996.icu)
[![issues](https://img.shields.io/github/issues/redscope-ai/redscope-ai?label=issues)](https://github.com/redscope-ai/redscope-ai/issues)
[![stars](https://img.shields.io/github/stars/redscope-ai/redscope-ai?label=stars)](https://github.com/redscope-ai/redscope-ai/stargazers)

RedScope AI 是一个面向安全团队、渗透测试、资产侦察、威胁追踪和红队编排的 AI CLI。它基于 Bun、TypeScript、React/Ink 和 MCP 工具生态构建，提供交互式终端助手、非交互式管道模式、多模型 Provider、插件系统、远程控制服务和一套受控的安全工作流脚本。

> 仅在你拥有授权的目标、资产、日志或代码仓库上使用 RedScope AI。项目内置的安全套件强调 scope、审批、速率限制、证据留存和可审计流程，不鼓励也不支持未授权扫描。

## 目录

- [项目能力](#项目能力)
- [快速安装](#快速安装)
- [配置模型](#配置模型)
- [基本使用](#基本使用)
- [安全工作流](#安全工作流)
- [项目流程](#项目流程)
- [技术栈](#技术栈)
- [文档](#文档)
- [赞助打赏](#赞助打赏)

## 项目能力

- 交互式 AI 编程与安全分析终端：`redscope`
- 管道/自动化输出：`redscope -p "..." --output-format json`
- 多 Provider：Anthropic、OpenAI 兼容端点、Gemini、Grok、Bedrock、Vertex、Foundry
- MCP 扩展：stdio、SSE、HTTP、WebSocket、插件内置 MCP、Chrome/Computer Use 集成
- 安全工作流：工具安装、scope 校验、profile 计划/执行、报告归一化、观测记忆、交付包
- 远程控制：自托管 Remote Control Server 和 ACP/Bridge 相关能力
- 插件与 Agent：插件 marketplace、自定义 agent、slash command、hooks、settings 分层配置

## 快速安装

要求：

- Node.js/npm

```bash
npm i -g @redscope-ai/redscope
redscope --version
```

从源码开发或调试本仓库时，再使用 Bun 安装依赖和构建：

```bash
bun install
bun run build
```

开发模式：

```bash
bun run dev
bun run dev:inspect
```

常用检查：

```bash
bun run typecheck
bun test
bun run test:all
```

## 配置模型

RedScope 推荐把模型端点、API Key 和默认模型写入用户配置目录的 `env.config`，默认路径是：

- Windows: `%USERPROFILE%\.redscope\env.config`
- macOS/Linux: `~/.redscope/env.config`

仓库提供了 [env.config.example](env.config.example)，可复制后按需填写。`env.config` 会在启动时加载，shell 中临时设置的环境变量优先级更高。

OpenAI 兼容端点示例：

```dotenv
REDSCOPE_MODEL_PROVIDER=openai
REDSCOPE_BASE_URL=https://api.openai.com/v1
REDSCOPE_API_KEY=sk-your-key
REDSCOPE_MODEL=gpt-4.1
```

DeepSeek 示例：

```dotenv
REDSCOPE_MODEL_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-your-key
DEEPSEEK_MODEL=deepseek-chat
```

Gemini 示例：

```dotenv
REDSCOPE_MODEL_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-key
GEMINI_MODEL=gemini-2.5-pro
```

更多配置项见 [项目使用文档](docs/usage.md#配置文件)。

## 基本使用

启动交互式会话：

```bash
redscope
```

直接传入提示词：

```bash
redscope "帮我审查这个仓库的安全风险"
```

管道模式：

```bash
echo "总结 package.json 的脚本" | redscope -p
redscope -p "输出 JSON 摘要" --output-format json
```

指定模型和权限模式：

```bash
redscope --model sonnet --permission-mode acceptEdits
redscope -p "生成一份发布说明" --allowedTools "Read,Grep,Glob"
```

MCP 示例：

```bash
redscope mcp list
redscope mcp add my-server npx -- -y @my-org/mcp-server
redscope mcp remove my-server
```

认证与状态：

```bash
redscope auth login
redscope auth status --text
redscope auth logout
```

完整命令参考见 [docs/usage.md](docs/usage.md)。

## 安全工作流

RedScope 的安全套件采用先授权、再计划、再执行、最后归档的流程。默认只生成计划，不会运行主动扫描；主动或受限 profile 必须显式传入 `--execute --confirm-active` 并通过 scope 文件校验。

```bash
bun run redscope:profile -- --list
bun run redscope:workflow -- --profile baseline-url-review --scope tools/authorized-scope.example.json --target https://www.example.com/
bun run redscope:report -- --latest --profile baseline-url-review
bun run redscope:observe -- --latest --profile baseline-url-review
```

```mermaid
flowchart LR
  A["Scope / Rules of Engagement"] --> B["Profile Selection"]
  B --> C["Plan Only by Default"]
  C --> D{"--execute?"}
  D -- "No" --> E["Run Artifacts"]
  D -- "Yes + Confirmation" --> F["Controlled Tool Execution"]
  F --> E
  E --> G["Report Pipeline"]
  G --> H["Observability Memory"]
  G --> I["Delivery Package"]
```

## 项目流程

```mermaid
flowchart TD
  U["User / CI / Pipe"] --> CLI["src/entrypoints/cli.tsx"]
  CLI --> MAIN["src/main.tsx Commander CLI"]
  MAIN --> REPL["React Ink REPL"]
  MAIN --> HEADLESS["Print / JSON / Stream JSON"]
  REPL --> ENGINE["QueryEngine"]
  HEADLESS --> ENGINE
  ENGINE --> API["Provider Adapter"]
  API --> P1["Anthropic"]
  API --> P2["OpenAI Compatible"]
  API --> P3["Gemini / Grok / Cloud"]
  ENGINE --> TOOLS["Builtin Tools + MCP Tools"]
  TOOLS --> FILES["Workspace Files"]
  TOOLS --> SHELL["Shell / PowerShell"]
  TOOLS --> MCP["MCP Servers / Plugins"]
```

## 技术栈

- Runtime: Bun
- Language: TypeScript, TSX, ESM
- CLI: Commander.js
- Terminal UI: React 19 + Ink fork
- Build: Bun.build, Vite alternative pipeline
- Test: `bun:test`
- Lint/Format: Biome
- Providers: Anthropic SDK, OpenAI-compatible Chat Completions, Gemini, Grok, AWS Bedrock, Google Vertex, Azure Foundry
- Extensibility: MCP, plugins, custom agents, hooks, slash commands
- Remote UI: React + Vite + Radix UI in `packages/remote-control-server`

## 文档

- [项目使用文档](docs/usage.md)
- [Tools 安全套件说明](tools/README.md)
- [远程控制自托管](docs/features/remote-control-self-hosting.md)
- [MCP 配置](docs/extensibility/mcp-configuration.mdx)
- [权限模型](docs/safety/permission-model.mdx)
- [外部依赖](docs/external-dependencies.md)

## 赞助打赏

如果 RedScope AI 帮你节省了时间，欢迎支持项目继续维护：

- GitHub Sponsors: [github.com/sponsors/redscope-ai](https://github.com/sponsors/redscope-ai)
- Issues / Stars: [提交建议](https://github.com/redscope-ai/redscope-ai/issues) 或给项目点 Star
- 微信/支付宝打赏：将二维码图片放到 `docs/images/sponsor-wechat.png` 和 `docs/images/sponsor-alipay.png` 后，可在本节补充展示

## License

本项目 README 使用 Anti 996 badge 展示劳动价值立场。正式发布前请根据项目实际授权策略补充或确认仓库根目录的 `LICENSE` 文件。
