react2shell-guard

安全扫描器，用于CVE-2025-55182——React Server Components中一个严重的（CVSS 10.0）未经验证的远程代码执行漏洞。

⚠️ 免责声明

这是一个安全扫描器，不是漏洞利用工具。它旨在帮助开发者和安全团队识别其项目中存在漏洞的依赖项。

这是一个社区驱动的开源项目，按“原样”提供，不提供任何明示或暗示的担保。作者和贡献者不对因使用本工具而造成的任何损害或安全事故负责。

自行承担使用风险和责任。 始终手动验证发现结果，并遵循组织的安全策略。如果您发现任何问题、错误或有建议，请贡献以帮助改进项目，惠及所有人。

🤝 寻找贡献者

本项目正在积极寻找测试人员和贡献者！无论您是想报告错误、提出功能建议、改进文档还是提交代码——所有贡献都欢迎。请查看我们的贡献指南开始。

致谢

本项目旨在帮助社区应对CVE-2025-55182。我们感谢以下人员：

Lachlan Davidson (react2shell.com) - 于2025年11月29日发现并负责任地披露了React Server Components漏洞（CVE-2025-55182）。安全社区感谢他的勤勉，识别出这一关键缺陷，并与React和Next.js团队合作确保补丁可用。他的努力帮助保护了全球无数应用和用户。请查看他的原始PoC了解技术细节。

快速开始

1. 即时扫描（无需安装）

检查项目是否存在漏洞的最快方法：```bash npx react2shell-guard .

就这样！这将扫描你当前的目录并立即显示结果。

### 2. 扫描特定项目```bash
npx react2shell-guard /path/to/your/project

3. 自动修复漏洞

发现漏洞了？自动修复它们：```bash

Preview what will be changed

npx react2shell-guard fix --dry-run

Apply fixes

npx react2shell-guard fix

Apply fixes and reinstall dependencies

npx react2shell-guard fix --install

### 4. 扫描实时URL

检查已部署的应用程序是否存在漏洞：```bash
npx react2shell-guard scan-url https://your-app.com

5. 验证补丁已应用

确认您部署的修复程序正在工作：```bash npx react2shell-guard verify-patch https://your-app.com

### 6. 扫描容器镜像

检查你的Docker镜像是否包含易受攻击的软件包：```bash
npx react2shell-guard scan-image myapp:latest

7. 创建修复PR (GitHub)

自动创建GitHub PR来修复漏洞：```bash npx react2shell-guard create-pr --dry-run # Preview npx react2shell-guard create-pr # Create PR

---

## 什么是 CVE-2025-55182？

2025年11月29日，安全研究员 Lachlan Davidson 发现并负责任地披露了 React 服务端组件中的一个严重漏洞。该缺陷存在于 React 解码发送至 React Server Function 端点的载荷的方式，使得未经认证的攻击者能够在无需用户交互的情况下，在受影响的服务器上实现远程代码执行。

CVE-2025-55182 的 CVSS 评分为 10.0（严重），影响 React Server Components（RSC）及使用 RSC 的 “Flight” 协议的框架。

**受影响包：**
- `react-server-dom-webpack` 19.0.0, 19.1.0-19.1.1, 19.2.0
- `react-server-dom-parcel`（相同版本）
- `react-server-dom-turbopack`（相同版本）
- `next` 15.0.0-15.0.4, 15.1.0-15.1.8, 15.2.0-15.2.5, 15.3.0-15.3.5, 15.4.0-15.4.7, 15.5.0-15.5.6, 16.0.0-16.0.6

**更多信息：**
- [React 安全公告](https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components)
- [Wiz 研究](https://www.wiz.io/blog/critical-vulnerability-in-react-cve-2025-55182)

---

## 安装（可选）

如需频繁使用，请全局安装：```bash
npm install -g react2shell-guard

然后在不使用 npx 的情况下直接使用：```bash react2shell-guard .

---

## 使用指南

### 基本扫描```bash
# Scan current directory
react2shell-guard .

# Scan specific directory
react2shell-guard /path/to/project

# Scan and ignore certain paths
react2shell-guard . --ignore-path "examples/**" "test/**"

输出格式```bash

Human-readable text (default)

react2shell-guard .

JSON output (for scripting)

react2shell-guard . --json

SARIF output (for GitHub Security tab)

react2shell-guard . --sarif

HTML report (standalone, shareable)

react2shell-guard . --html report.html

### CLI 选项

| 选项 | 描述 |
|--------|-------------|
| `--json` | 以 JSON 格式输出结果 |
| `--sarif` | 以 SARIF 2.1.0 格式输出结果 |
| `--html <file>` | 生成独立的 HTML 报告 |
| `--no-exit-on-vuln` | 发现漏洞时不退出并返回代码 1 |
| `--ignore-path <patterns>` | 要忽略的路径（例如 `examples/**`） |
| `--debug` | 启用调试输出 |

### 退出代码

| 代码 | 含义 |
|------|---------|
| `0` | 未发现漏洞 |
| `1` | 检测到漏洞 |
| `2+` | 致命错误 |

## 实时 URL 扫描

扫描实时端点以检测它们是否容易受到攻击：```bash
# Scan a single URL
react2shell-guard scan-url https://example.com

# Batch scan from a file (one URL per line)
react2shell-guard scan-url urls.txt --list

# With options
react2shell-guard scan-url https://example.com --timeout 5000 --json

实时 URL 扫描的工作原理

该扫描器使用被动指纹识别技术，在不利用漏洞的情况下检测存在漏洞的 React Server Components 端点：

探测请求：发送一个构造的 POST 请求，模拟 RSC Server Action 调用，携带最小有效载荷：
- 使用 multipart/form-data 内容类型，带有类似 RSC 的数据结构
- 包含 Next-Action 头部，以触发 Server Action 处理
响应分析：分析 HTTP 响应中的漏洞特征：
- 检查 HTTP 500 状态码（错误响应）
- 将响应体与 RSC Flight 协议错误模式进行匹配：
  - ^[0-9]+:E{ - RSC Flight 协议错误格式
  - "digest":"...RSC - 错误响应中的 RSC 摘要
  - ReactServerComponentsError - React 错误类名
  - text/x-component.*error - 组件错误内容类型
非破坏性：这纯粹是一种检测机制——它不会执行任何恶意有效载荷或利用漏洞。探测使用良性数据，会在存在漏洞的服务器上触发错误响应，但不会造成任何危害。

注意：积极检测结果意味着服务器运行存在漏洞的版本，并返回了 RSC 特定的错误签名。这并不意味着服务器已被利用。

URL 扫描器选项

补丁验证

验证目标是否已修补漏洞：```bash

Verify patch status (runs multiple scans for accuracy)

react2shell-guard verify-patch https://example.com

With JSON output

react2shell-guard verify-patch https://example.com --json

### 补丁验证工作原理

补丁验证执行**多次连续扫描**（默认：3次），每次扫描之间设有短暂延迟，以确保准确检测：

1. **多次探测**：以500毫秒的间隔运行相同的被动指纹检测，共3次
2. **置信度评分**：
   - **高置信度**：2次及以上成功扫描且结果一致
   - **中置信度**：1次成功扫描且有明确结果
   - **低置信度**：所有扫描均失败或结果不明确
3. **结果分类**：
   - **已修补**：在所有成功扫描中均未检测到漏洞特征
   - **存在漏洞**：在一次或多次扫描中检测到漏洞特征
   - **结论不确定**：结果不一致或所有扫描均失败

这种多次扫描方法可减少因临时网络问题导致的误报，并提高对补丁状态的置信度。

### 验证选项

| 选项 | 描述 |
|--------|-------------|
| `--timeout <ms>` | 请求超时时间（毫秒，默认值：10000） |
| `--json` | 以JSON格式输出结果 |
| `--skip-ssl-verify` | 跳过SSL证书验证 |

## 容器镜像扫描

扫描Docker/OCI容器镜像中的有漏洞软件包：```bash
# Scan a local or remote image
react2shell-guard scan-image myapp:latest

# Scan from a registry
react2shell-guard scan-image registry.example.com/myapp:v1.0

# Skip pulling (use local image only)
react2shell-guard scan-image myapp:latest --skip-pull

# With JSON output
react2shell-guard scan-image myapp:latest --json

# With SARIF output
react2shell-guard scan-image myapp:latest --sarif

容器扫描器选项

要求：

必须安装并运行 Docker
有足够的磁盘空间用于镜像提取

Vercel 部署集成

在易受攻击的部署进入生产环境前进行阻止：```bash

Run as part of your build command

react2shell-guard vercel-check

In package.json

{ "scripts": { "vercel-build": "react2shell-guard vercel-check && next build" } }

Or in vercel.json

{ "buildCommand": "npx react2shell-guard vercel-check && npm run build" }

### Vercel 检查选项

| 选项 | 描述 |
|--------|-------------|
| `--no-fail` | 警告但不因漏洞导致构建失败 |
| `--ignore-path <patterns>` | 忽略的路径（glob 模式） |
| `--debug` | 启用调试输出 |

## GitHub PR 自动化

自动创建拉取请求以修复漏洞：```bash
# Preview what will be done
react2shell-guard create-pr --dry-run

# Create branch and PR
react2shell-guard create-pr

# Create branch but don't push/create PR
react2shell-guard create-pr --no-push

# Custom branch name
react2shell-guard create-pr --branch fix/security-update

创建 PR 选项

选项	描述
`--branch <name>`	修复的分支名称（默认值：`fix/cve-2025-55182`）
`--dry-run`	显示将要执行的操作，但不实际进行更改
`--no-push`	创建分支和提交，但不推送或创建 PR

要求：

必须安装并认证 GitHub CLI (gh)
必须在具有远程仓库的 git 仓库中

示例输出```

react2shell-guard - CVE-2025-55182 Scanner ──────────────────────────────────────────────────

Scanned 1 project(s)

✗ my-app [VULNERABLE] Path: /path/to/my-app Framework: nextjs v15.2.1 App Router: Yes (RSC enabled)

Vulnerabilities found: - react-server-dom-webpack @ 19.1.0 Upgrade to: 19.1.2 Advisory: https://react.dev/blog/2025/12/03/... - next @ 15.2.1 Upgrade to: 15.2.6 Advisory: https://react.dev/blog/2025/12/03/...

────────────────────────────────────────────────── VULNERABLE - Action required! Upgrade affected packages to patched versions immediately.

## GitHub Actions 集成

> **注意：** 我们积极发布新版本，包含改进的检测模式和修复。使用 `@v1` 获取稳定版本，或使用 `@latest` 获取最新版本。

### GitHub Marketplace Action

最简单的集成方式是使用我们的官方 GitHub Action：```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan for CVE-2025-55182
        uses: gensecaihq/react2shell-scanner@v1
        with:
          path: '.'
          fail-on-vuln: true

全功能设置 (SARIF + PR Comments)```yaml

name: Security Scan

on: [push, pull_request]

jobs: scan: runs-on: ubuntu-latest permissions: security-events: write # For SARIF upload pull-requests: write # For PR comments

steps:
  - uses: actions/checkout@v4

  - name: Scan for CVE-2025-55182
    uses: gensecaihq/react2shell-scanner@v1
    with:
      path: '.'
      format: sarif
      fail-on-vuln: true
      upload-sarif: true        # Upload to GitHub Security tab
      add-pr-comment: true      # Comment on PRs with results
      ignore-paths: 'examples/**,test/fixtures/**'

### 操作输入

| 输入 | 描述 | 默认值 |
|------|------|--------|
| `path` | 要扫描的路径 | `.` |
| `scan-type` | 扫描类型：`repo`、`sbom`、`container` | `repo` |
| `format` | 输出格式：`text`、`json`、`sarif` | `text` |
| `fail-on-vuln` | 如果发现漏洞则失败 | `true` |
| `upload-sarif` | 将SARIF上传至GitHub安全 | `false` |
| `add-pr-comment` | 添加PR评论并显示结果 | `false` |
| `ignore-paths` | 以逗号分隔的忽略路径 | `''` |
| `sbom-file` | SBOM文件路径（当扫描类型为sbom时） | `''` |
| `container-image` | Docker镜像（当扫描类型为container时） | `''` |

### 操作输出

| 输出 | 描述 |
|------|------|
| `vulnerable` | 是否发现漏洞（`true`/`false`） |
| `findings-count` | 存在漏洞的包数量 |
| `scan-result` | 完整扫描结果（JSON格式） |
| `sarif-file` | SARIF输出文件路径 |

### 扫描容器镜像```yaml
- name: Scan Docker image
  uses: gensecaihq/react2shell-scanner@v1
  with:
    scan-type: container
    container-image: myapp:latest

扫描SBOM文件```yaml

name: Scan SBOM uses: gensecaihq/react2shell-scanner@v1 with: scan-type: sbom sbom-file: sbom.json

### 手动 CLI 使用

如果你更喜欢直接使用 CLI：```yaml
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'

- name: Scan for vulnerabilities
  run: npx react2shell-guard@latest .

支持的包管理器

react2shell-guard 会自动检测并解析以下锁文件：

npm - package-lock.json（v2 和 v3 格式）
pnpm - pnpm-lock.yaml
yarn - yarn.lock（Classic 和 Berry 格式）

功能特性

快速扫描 - 直接分析锁文件，无需安装依赖
Monorepo 支持 - 自动发现并扫描所有项目
框架检测 - 识别 Next.js 和 App Router 的使用
多种输出格式 - 文本、JSON、SARIF 和 HTML 报告
CI/CD 就绪 - 退出码和 GitHub Actions 集成
零网络调用 - 完全离线工作
自动修复 - 自动更新有漏洞的依赖
预提交钩子 - 阻止提交包含有漏洞的依赖
SBOM 扫描 - 扫描 CycloneDX SBOM 文件
MCP 集成 - 通过模型上下文协议支持 AI 助手
运行时保护 - Express.js/Next.js 中间件实现纵深防御
实时 URL 扫描 - 扫描已部署应用的漏洞
容器扫描 - 扫描 Docker/OCI 镜像中的漏洞包
Vercel 集成 - 在上线前阻止有漏洞的部署
GitHub PR 自动化 - 一键自动创建修复 PR

自动修复漏洞

自动更新你的 package.json 以使用补丁版本：```bash

Preview changes (dry run)

react2shell-guard fix --dry-run

Apply fixes

react2shell-guard fix

Apply fixes and run npm/pnpm/yarn install

react2shell-guard fix --install

## Pre-Commit Hooks

安装Git钩子以防止提交有漏洞的依赖项：```bash
# Auto-detect hook framework and install
react2shell-guard init-hooks

# Preview what would be installed
react2shell-guard init-hooks --dry-run

# Force specific hook type
react2shell-guard init-hooks --hook-type husky
react2shell-guard init-hooks --hook-type lefthook
react2shell-guard init-hooks --hook-type standalone

支持的钩子框架：

Husky - 追加到 .husky/pre-commit
Lefthook - 创建/更新 lefthook.yml
Standalone - 创建 .git/hooks/pre-commit

当 package.json 包含易受攻击的依赖项时，钩子将阻止提交，并建议运行 react2shell-guard fix 进行修复。

SBOM 扫描

扫描 CycloneDX SBOM 文件以查找漏洞：```bash

Scan a CycloneDX SBOM

react2shell-guard scan-sbom bom.json

With JSON output

react2shell-guard scan-sbom bom.json --json

With SARIF output

react2shell-guard scan-sbom bom.json --sarif

## MCP Server (AI Assistant Integration)

启动用于AI助手集成的Model Context Protocol服务器：```bash
react2shell-guard mcp-server

可用的 MCP 工具：

scan_repo - 扫描代码仓库中的漏洞
scan_sbom - 扫描 CycloneDX SBOM 文件

使用兼容 MCP 的客户端进行配置（示例配置）：```json { "mcpServers": { "react2shell-guard": { "command": "npx", "args": ["react2shell-guard", "mcp-server"] } } }

## Runtime Protection Middleware

深度防御中间件，可在运行时检测并阻止 CVE-2025-55182 漏洞利用尝试。

### Express.js```typescript
import express from 'express';
import { createExpressMiddleware } from 'react2shell-guard/middleware';

const app = express();

// Add raw body parser for RSC payloads
app.use(express.raw({ type: 'text/x-component' }));
app.use(express.json());

// Add protection middleware
app.use(createExpressMiddleware({
  action: 'block',  // 'block' | 'log' | 'alert'
  onAlert: (result, req) => {
    // Send to your alerting system (Slack, PagerDuty, etc.)
    console.error('CVE-2025-55182 exploit attempt:', result);
  },
  skipPaths: ['/health', '/metrics'],
}));

Next.js```typescript

// middleware.ts import { withReact2ShellGuard } from 'react2shell-guard/middleware';

export const middleware = withReact2ShellGuard({ action: 'block', rscEndpointsOnly: true, // Only check RSC endpoints (recommended) });

export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'], };

**检测到的模式：**
- 序列化函数注入
- 原型污染尝试
- 格式错误的模块引用
- 服务器操作篡改
- 编码的恶意负载
- RSC流格式滥用

## API 使用```typescript
import { scan } from 'react2shell-guard';

const result = scan({
  path: '/path/to/project',
  ignorePaths: ['examples/**'],
  debug: false,
});

console.log(result.vulnerable); // boolean
console.log(result.projects);   // ProjectResult[]

JSON 输出模式```json

{ "cve": "CVE-2025-55182", "vulnerable": true, "scanTime": "2025-12-04T10:30:00Z", "projects": [ { "name": "my-app", "path": "/path/to/my-app", "framework": { "type": "nextjs", "version": "15.2.1", "appRouterDetected": true }, "findings": [ { "package": "react-server-dom-webpack", "currentVersion": "19.1.0", "fixedVersion": "19.1.2", "severity": "critical", "advisoryUrl": "https://..." } ], "vulnerable": true } ], "errors": [] }

## 修复

**自动修复（推荐）：**```bash
react2shell-guard fix --install

手动升级 - React 包:```bash npm install [email protected] # or 19.0.1, 19.2.1

**手动升级 - Next.js:**```bash
npm install [email protected]  # or other patched version for your release line

各发布版本的已修复 Next.js 版本：

15.0.x → 15.0.5
15.1.x → 15.1.9
15.2.x → 15.2.6
15.3.x → 15.3.6
15.4.x → 15.4.8
15.5.x → 15.5.7
16.0.x → 16.0.7

开发```bash

Install dependencies

npm install

Build

npm run build

Run tests

npm test

Run in development mode

npm run dev

## 许可证

MIT

`--list`	将目标视为包含 URL 的文件
`--threads <n>`	并发线程数（默认：10）
`--timeout <ms>`	请求超时时间（毫秒）（默认：10000）
`--json`	以 JSON 格式输出结果
`--skip-ssl-verify`	跳过 SSL 证书验证
`--verbose`	显示所有结果，包括无漏洞的主机

`--timeout <ms>`	操作超时时间（毫秒，默认：120000）
`--skip-pull`	跳过从镜像仓库拉取（仅使用本地镜像）
`--json`	以 JSON 格式输出结果
`--sarif`	以 SARIF 2.1.0 格式输出结果
`--no-exit-on-vuln`	发现漏洞时不返回退出码 1
`--debug`	启用调试输出

react2shell-scanner

最受欢迎

react2shell-guard

致谢

快速开始

1. 即时扫描（无需安装）

3. 自动修复漏洞

Preview what will be changed

Apply fixes

Apply fixes and reinstall dependencies

5. 验证补丁已应用

7. 创建修复PR (GitHub)

输出格式```bash

Human-readable text (default)

JSON output (for scripting)

SARIF output (for GitHub Security tab)

HTML report (standalone, shareable)

实时 URL 扫描的工作原理

URL 扫描器选项

补丁验证

Verify patch status (runs multiple scans for accuracy)

With JSON output

容器扫描器选项

Vercel 部署集成

Run as part of your build command

In package.json

Or in vercel.json

创建 PR 选项

示例输出```

全功能设置 (SARIF + PR Comments)```yaml

扫描SBOM文件```yaml

支持的包管理器

功能特性

自动修复漏洞

Preview changes (dry run)

Apply fixes

Apply fixes and run npm/pnpm/yarn install

SBOM 扫描

Scan a CycloneDX SBOM

With JSON output

With SARIF output

Next.js```typescript

JSON 输出模式```json

开发```bash

Install dependencies

Build

Run tests

Run in development mode