# RedScope AI

English | [中文](README.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 is a security-focused AI CLI for penetration testing, asset reconnaissance, threat tracing, and red-team orchestration. It is built with Bun, TypeScript, React/Ink, MCP tooling, multiple model providers, plugins, a self-hostable remote-control server, and a controlled security workflow suite.

> Use RedScope AI only on targets, assets, logs, and repositories you are authorized to test. The security-suite workflow is designed around scope files, approvals, rate limits, evidence handling, and auditable reporting.

## Contents

- [What It Does](#what-it-does)
- [Install](#install)
- [Model Configuration](#model-configuration)
- [Usage](#usage)
- [Security Workflow](#security-workflow)
- [Architecture Flow](#architecture-flow)
- [Tech Stack](#tech-stack)
- [Documentation](#documentation)
- [Sponsor](#sponsor)

## What It Does

- Interactive AI terminal assistant: `redscope`
- Headless and pipeline mode: `redscope -p "..." --output-format json`
- Multi-provider model runtime: Anthropic, OpenAI-compatible endpoints, Gemini, Grok, Bedrock, Vertex, Foundry
- MCP extension layer: stdio, SSE, HTTP, WebSocket, plugin-provided MCP, Chrome and Computer Use integrations
- Security workflow suite: controlled tool installation, scope validation, profile planning/execution, report normalization, observability memory, delivery packages
- Remote control: self-hosted Remote Control Server plus ACP/Bridge-related integrations
- Extensibility: plugin marketplace, custom agents, slash commands, hooks, layered settings

## Install

Requirements:

- Node.js/npm

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

When developing or debugging this repository from source, install dependencies and build with Bun:

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

Development mode:

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

Common checks:

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

## Model Configuration

RedScope recommends storing model endpoints, API keys, and default model IDs in the user-level `env.config` file:

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

This repository includes [env.config.example](env.config.example). Copy it to your user config directory and fill in only one provider preset. Shell environment variables override `env.config` for the current process.

OpenAI-compatible endpoint:

```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
```

See the [usage guide](docs/usage.md#配置文件) for more configuration files and variables.

## Usage

Start an interactive session:

```bash
redscope
```

Pass a prompt directly:

```bash
redscope "Review this repository for security risks"
```

Run in pipe mode:

```bash
echo "Summarize package.json scripts" | redscope -p
redscope -p "Return a JSON summary" --output-format json
```

Select a model and permission mode:

```bash
redscope --model sonnet --permission-mode acceptEdits
redscope -p "Generate release notes" --allowedTools "Read,Grep,Glob"
```

MCP examples:

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

Authentication:

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

For the full command reference, see [docs/usage.md](docs/usage.md).

## Security Workflow

The RedScope security suite follows an authorize, plan, execute, report, and deliver flow. It plans by default and does not run active scanners unless you explicitly pass `--execute --confirm-active` and provide a valid scope file.

```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"]
```

## Architecture Flow

```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"]
```

## Tech Stack

- Runtime: Bun
- Language: TypeScript, TSX, ESM
- CLI: Commander.js
- Terminal UI: React 19 + Ink fork
- Build: Bun.build, optional Vite 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`

## Documentation

- [Usage Guide](docs/usage.md)
- [Tools Security Suite](tools/README.md)
- [Self-Hosted Remote Control](docs/features/remote-control-self-hosting.md)
- [MCP Configuration](docs/extensibility/mcp-configuration.mdx)
- [Permission Model](docs/safety/permission-model.mdx)
- [External Dependencies](docs/external-dependencies.md)

## Sponsor

If RedScope AI saves you time, you can support ongoing maintenance:

- GitHub Sponsors: [github.com/sponsors/redscope-ai](https://github.com/sponsors/redscope-ai)
- Issues / Stars: [open an issue](https://github.com/redscope-ai/redscope-ai/issues) or star the repository
- WeChat / Alipay tips: add QR images at `docs/images/sponsor-wechat.png` and `docs/images/sponsor-alipay.png`, then render them in this section

## License

This README displays the Anti 996 badge as a labor-value statement. Before publishing, confirm the repository's actual `LICENSE` file and package license metadata.
