@redscope-ai/redscope 1.0.1 → 1.0.3

package/README.en.md

@@ -0,0 +1,227 @@
+# 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.