SetraTheXX/next-secure-check
GitHub: SetraTheXX/next-secure-check
这是一个专为 Next.js 设计的规则驱动静态安全扫描器，用于在开发阶段发现常见安全漏洞。
Stars: 4 | Forks: 0
# next-安全检查
适用于 Next.js 项目的确定性安全检查工具。无需 AI。
`next-secure-check` 帮助开发者在项目上线前发现常见的安全问题：泄露的密钥、不安全的 API 路由、缺失的速率限制、薄弱的配置、XSS 风险、原始 SQL 模式、不安全的文件上传端点以及缺失的安全标头。
演示视频计划中。
于 2026 年 5 月 9 日启动。
## 当前状态
已完成：
- 命令行界面 MVP
- 20 条确定性安全规则
- 跨包和网页演示共 374 项测试通过
- 终端、JSON、Markdown、GitHub 和 SARIF 报告格式
- 关于发现结果的上下文元数据
- 用于应用、严格、CI、审计、库和 monorepo 扫描的命令行预设系统
- 具有上下文感知的严重性/置信度调整，以减少大型代码库中的噪声结果
- 基于抽象语法树辅助的命令执行、原始 SQL 插值、危险 HTML 渲染和密码处理检查
- 具有路由感知的管理员路由检测和端点感知的文件上传验证
- 带有步骤摘要输出的 GitHub Actions 验证
- `docs/rules` 目录中的规则文档
- 用于扫描公共 GitHub 仓库的 `apps/web` 网页演示
- GitHub 仓库 URL 验证、元数据检查、tarball 下载、安全解压、清理、API 扫描端点、报告界面、排除开关以及 JSON/Markdown 导出
- 第 4.5+ 阶段网页演示加固，包括仓库大小检查、服务端脱敏、扫描滥用防护、强化安全标头、孤立临时文件清理、可选的 GitHub 令牌支持以及强化的客户端 IP 解析
- 发布前对提交的 `.env.*` 变体和部分安全标头检测的规则覆盖优化
当前发布重点：
```
v0.2.x: collect real project feedback, improve usage docs, and keep false-positive handling honest.
```
网页演示仅使用静态分析扫描公共 GitHub 仓库。它不会运行仓库代码、安装依赖、执行测试或访问私有仓库。
## GitHub Actions 演示
命令行界面在 GitHub Actions 中作为此仓库 CI 的一部分运行。
- 工作流使用 `--format github` 运行扫描器，并通过 `$GITHUB_STEP_SUMMARY` 将 markdown 报告写入作业的 **步骤摘要**。
- 当使用 `--fail-on high` 时，如果报告了任何严重级别为 HIGH 的发现，作业将失败。
- 当使用 `--fail-on critical` 时，仅当扫描摘要的风险级别为 `critical` 时作业才会失败。
- 步骤顺序为：构建 -> 类型检查 -> 测试 -> 安全检查，确保在类型检查之前编译工作区包。
- 发现结果是确定的模式匹配；不执行漏洞利用证明。
## 存在意义
AI 辅助开发使得快速交付变得容易，但也容易忽略安全基础。本项目专注于基于证据的检查，这些检查易于理解，对初级开发者、自由职业者、小型 SaaS 团队和代理机构非常有用。
## 学习项目与开发理念
这是一个由学生构建的学习项目。作为一名计算机编程专业的一年级学生，我正在开发它以提升我在 TypeScript、Next.js 安全、静态分析、开源项目结构、测试和产品思维方面的技能。
AI 在速度、结构和反馈方面有所帮助，但技术所有权、产品方向、代码审查、测试、发布决策和最终责任仍由我承担。
我仍在学习中，因此欢迎提出问题、反馈和批评性评论。发现结果应被视为审查信号，而不是漏洞利用的证明，并且可能存在误报或漏报。
## 当前规则
扫描器目前检查 20 种常见的安全模式。您可以在[规则文档](./docs/rules)目录中阅读有关每条规则的更多信息。
1. **[secrets/env-file-committed](./docs/rules/env-file-committed.md)**: 检测已提交的 `.env` 文件。
2. **[secrets/hardcoded-secret](./docs/rules/hardcoded-secret.md)**: 检测硬编码的 API 密钥和令牌。
3. **[secrets/weak-jwt-secret](./docs/rules/weak-jwt-secret.md)**: 检测弱或默认的 `JWT_SECRET` 值。
4. **[injection/no-eval](./docs/rules/no-eval.md)**: 检测 `eval()` 的使用。
5. **[injection/no-new-function](./docs/rules/no-new-function.md)**: 检测 `new Function()` 的使用。
6. **[injection/command-exec](./docs/rules/command-exec.md)**: 检测 shell 命令执行。
7. **[xss/dangerously-set-inner-html](./docs/rules/dangerously-set-inner-html.md)**: 检测 React 中的原始 HTML 渲染。
8. **[config/insecure-cors-wildcard](./docs/rules/insecure-cors-wildcard.md)**: 检测通配符 CORS 源。
9. **[auth/login-without-rate-limit](./docs/rules/login-without-rate-limit.md)**: 检测缺少速率限制的登录端点。
10. **[auth/register-without-rate-limit](./docs/rules/register-without-rate-limit.md)**: 检测缺少速率限制的注册端点。
11. **[auth/password-without-hashing-library](./docs/rules/password-without-hashing-library.md)**: 检测未使用 bcrypt/argon2 处理密码。
12. **[injection/raw-sql-concat](./docs/rules/raw-sql-concat.md)**: 检测原始 SQL 字符串插值。
13. **[headers/missing-security-headers](./docs/rules/missing-security-headers.md)**: 检测 Next.js 配置中缺失的安全标头。
14. **[secrets/next-public-secret](./docs/rules/next-public-secret.md)**: 检测类似 `NEXT_PUBLIC_` 的密钥变量。
15. **[upload/missing-file-type-validation](./docs/rules/missing-file-type-validation.md)**: 检测缺少文件类型验证的上传端点。
16. **[upload/missing-file-size-limit](./docs/rules/missing-file-size-limit.md)**: 检测缺少文件大小限制的上传端点。
17. **[validation/api-route-without-validation](./docs/rules/api-route-without-validation.md)**: 检测可能缺少输入验证的 API 路由。
18. **[auth/admin-route-without-auth](./docs/rules/admin-route-without-auth.md)**: 检测可能缺少身份验证保护的管理员路由。
19. **[config/production-browser-source-maps](./docs/rules/production-browser-source-maps.md)**: 检测 Next.js 配置中的 `productionBrowserSourceMaps: true`。
20. **[config/next-powered-by-header](./docs/rules/next-powered-by-header.md)**: 检测 Next.js 配置中缺少 `poweredByHeader: false`。
## CLI 用法
推荐的一次性使用方式：
```
npx --yes next-secure-check@latest scan . --preset app
```
为了实现可重现的 CI 运行，请固定包版本：
```
npx --yes next-secure-check@0.2.0 scan . --preset app
```
全局安装：
```
npm install -g next-secure-check
next-secure-check scan .
```
如果存在旧的全局安装，无版本的 `npx next-secure-check` 有时会重用旧的二进制文件，并且在 v0.2 选项（如 `--preset`）上失败。请在需要时检查并移除全局安装：
```
next-secure-check --version
npm list -g next-secure-check
npm uninstall -g next-secure-check
npm cache verify
```
或者无需全局安装即可运行：
```
npx --yes next-secure-check@latest scan .
npx --yes next-secure-check@latest scan . --format json
npx --yes next-secure-check@latest scan . --format markdown --output report.md
npx --yes next-secure-check@latest scan . --format github
npx --yes next-secure-check@latest scan . --format sarif --output report.sarif
npx --yes next-secure-check@latest scan . --fail-on high
npx --yes next-secure-check@latest scan . --fail-on critical
npx --yes next-secure-check@latest scan . --category secrets,auth,xss
npx --yes next-secure-check@latest scan . --exclude "**/*.test.ts,examples/**"
npx --yes next-secure-check@latest scan . --preset app
npx --yes next-secure-check@latest scan . --preset strict
npx --yes next-secure-check@latest scan . --preset ci
node packages/cli/dist/index.js scan . --exclude "**/*.test.ts,examples/**"
```
`--preset` 于 v0.2.0 中添加。建议本地一次性扫描使用 `npx --yes next-secure-check@latest`，或在 CI 中固定 `next-secure-check@0.2.0`。
`--fail-on critical` 是一个风险级别门控。仅当 `scan.summary.riskLevel` 为 `critical` 时，它才以退出码 `1` 退出。`--fail-on high`、`medium`、`low` 和 `info` 继续作为严重性阈值使用。
## 预设
预设为常见的扫描模式调整路径覆盖范围。它们不能替代手动审查；它们有助于为仓库选择合适的信号/噪声平衡。
| 预设名称 | 最佳用途 | 行为 |
| --- | --- | --- |
| `default` | 通用本地扫描 | 具有标准上下文调优的广泛基线覆盖 |
| `app` | 生产应用代码的合理性检查 | 排除测试、示例、文档、生成输出以及 GitHub 工作流/工具路径 |
| `strict` | 激进审查 | 关闭调优并进行广泛扫描 |
| `ci` | 拉取请求检查 | 排除测试和生成输出，同时保持面向 CI 的实用行为 |
| `audit` | 广泛手动审查 | 关闭调优进行保守审查 |
| `library` | 组件/库仓库 | 减少文档/示例/测试/生成内容的噪声 |
| `monorepo` | 多应用工作区 | 针对 apps/packages 风格仓库的应用聚焦覆盖 |
## 针对大型仓库的应用聚焦扫描
`next-secure-check` v0.2 作为应用代码的快速审查信号最为有用。大型 monorepo、模板仓库、生成器 CLI、发布脚本以及演示/示例密集型仓库仍然可能产生噪声，但上下文元数据、预设和基于抽象语法树的辅助规则使默认体验更加实用。
对于专注于生产应用代码的扫描，您可以从以下开始：
```
npx --yes next-secure-check@latest scan . --preset app
```
当您需要更激进的审查模式时，使用 `--preset strict`。当仓库有特定于项目的生成、演示或固定路径时，您仍然可以添加 `--exclude` 模式。发现结果不能替代安全审计；它们是针对常见错误的、集中的发布前审查信号。
## CLI 配置
CLI 可以从扫描目标根目录读取名为 `.next-secure-check.json` 的本地 JSON 配置文件。
支持的字段：
- `excludePaths`: 要忽略的相对路径 glob 模式
- `categories`: 要运行的规则类别
- `failOn`: 严重性阈值，或 `critical` 以基于扫描摘要风险级别进行门控
- `format`: 报告输出格式
- `preset`: 扫描预设（`default`、`app`、`strict`、`ci`、`audit`、`library` 或 `monorepo`）
示例：
```
{
"preset": "app",
"excludePaths": ["**/*.test.ts", "**/*.spec.tsx", "examples/**"],
"categories": ["secrets", "auth", "headers"],
"failOn": "high",
"format": "json"
}
```
命令行标志始终优先于配置值：
```
CLI flag > config file > default
```
例如，如果配置文件设置了 `"format": "markdown"` 但命令使用了 `--format json`，CLI 将输出 JSON。
您也可以指定一个明确的配置文件：
```
npx --yes next-secure-check@latest scan . --config path/to/config.json
```
网页演示不会读取被扫描仓库中的 `.next-secure-check.json` 文件。托管/公共扫描将改用网页演示自身的服务器端选项。
## SARIF 输出
SARIF 2.1.0 输出可用于 GitHub Code Scanning 等工具：
```
npx --yes next-secure-check@latest scan . --format sarif --output report.sarif
```
SARIF 报告器包括：
- 带有 `informationUri` 的工具元数据
- 唯一的规则元数据
- 带有文件、行和列（如可用）的结果位置
- `security-severity` 和精度元数据
- 用于更稳定结果跟踪的确定性 `partialFingerprints`
- 基于发现结果标题、描述和推荐构建的简洁结果消息
SARIF 输出中不包含原始密钥证据。
## Monorepo 布局
```
apps/
web/ local public-repository web demo app
packages/
core/ scanner orchestration, shared types, score engine
cli/ command line entrypoint
rules/ built-in rule modules
reporter/ terminal, JSON, markdown, GitHub, SARIF report output
examples/
vulnerable-next-app/
secure-next-app/
docs/
rules/
```
## 本地开发
```
pnpm install
pnpm build
pnpm typecheck
pnpm test
```
根测试命令当前运行包测试和网页演示测试。
预期的当前测试覆盖率：
```
packages: 231 tests
apps/web: 143 tests
total: 374 tests
```
构建后，可以在本地运行 CLI：
```
node packages/cli/dist/index.js scan examples/vulnerable-next-app
node packages/cli/dist/index.js scan examples/vulnerable-next-app --format json
node packages/cli/dist/index.js scan examples/vulnerable-next-app --format markdown --output report.md
node packages/cli/dist/index.js scan examples/vulnerable-next-app --format github --fail-on high
node packages/cli/dist/index.js scan examples/vulnerable-next-app --format sarif --output report.sarif
node packages/cli/dist/index.js scan . --exclude "**/*.test.ts,examples/**"
```
## 网页演示状态
网页演示位于 `apps/web` 下。它是一个用于扫描公共 GitHub 仓库的本地演示，而不是生产就绪的托管扫描服务。
当前网页演示流程：
```
Public GitHub repo URL
-> URL validation
-> public repository metadata check
-> tarball download
-> safe tarball extraction
-> core scanner
-> server-side evidence redaction
-> cleanup
-> report UI
-> optional test/example exclusion
-> JSON / Markdown export
```
网页演示包括：
- 公共 GitHub 仓库 URL 验证
- 公共仓库元数据检查
- 使用 `User-Agent: next-secure-check` 从 GitHub 下载 tarball
- 可选的 `GITHUB_TOKEN` 支持以提高 GitHub API 速率限制
- 带有存档限制和路径检查的安全 tarball 解压
- 解压后临时文件的清理保证
- 扫描成功但立即清理失败时的清理警告行为
- 核心扫描器集成
- 在结果到达浏览器之前的服务器端证据脱敏
- `POST /api/scans` 后端端点
- 包含加载、错误和结果状态的 UI 扫描流程
- **排除测试和示例** 以进行更干净的生产类扫描的开关
- JSON 和 Markdown 导出操作
网页演示有意进行了限制。
它不会：
- 访问私有仓库
- 要求登录
- 包含付费
- 运行仓库代码
- 运行 `npm install`
- 运行被扫描仓库的构建、测试或包脚本
- 执行动态分析
其目标是仅使用安全的静态分析扫描公共 GitHub 仓库。与密钥相关的证据在网页响应和导出之前会在服务端进行脱敏。
默认情况下，网页演示可以排除测试/规范文件和 `examples/**`：
```
**/*.test.ts
**/*.test.tsx
**/*.spec.ts
**/*.spec.tsx
examples/**
```
运行本地网页演示：
```
pnpm install
pnpm build
pnpm -C apps/web dev
```
然后打开本地 Next.js 应用并输入一个公共 GitHub 仓库 URL。
扫描 API 接受：
```
POST /api/scans
Content-Type: application/json
{
"repoUrl": "https://github.com/owner/repo",
"excludePaths": ["**/*.test.ts", "examples/**"]
}
```
真实的本地 API 冒烟测试通过：
```
https://github.com/octocat/Hello-World
```
## 安全模型/加固
网页演示仅设计用于公共、静态扫描：
- 仅限公共仓库
- 不执行被扫描仓库的脚本
- 不在被扫描仓库内安装依赖
- 下载前进行 GitHub 仓库元数据和大小检查
- 带有存档限制的安全 tarball 解压
- 路径遍历保护
- 拒绝符号链接和硬链接
- 拒绝重复的存档路径
- 服务器端密钥证据脱敏
- 可选的 `GITHUB_TOKEN` 支持用于 GitHub 元数据和 tarball 请求
- GitHub 请求使用 `User-Agent: next-secure-check`
- 可选的 Upstash Redis REST 分布式扫描防护
- 内存中的 IP 速率限制和全局并发防护回退
- 强化的客户端 IP 解析器，具有平台头优先、IPv4/IPv6 验证和大头部回退
- GitHub 请求和扫描阶段超时及安全错误响应
- 针对旧扫描器解压目录的孤立临时文件清理
- 即使立即清理失败，成功的扫描结果仍然返回，并带有安全的清理警告
内存中的扫描防护仅适用于本地/单实例演示阶段。公共多实例或无服务器部署应配置分布式防护或等效的平台级保护。
## 已知限制
- 规则是确定的，并结合了轻量级模式匹配、语法级抽象语法树检查和路径/上下文信号，因此仍然可能产生误报和漏报。
- 发现结果是审查信号，而不是漏洞利用的证明。
- 大型 monorepo、演示/示例密集型仓库、模板仓库和工具导向型仓库仍然可能产生噪声发现。
- 即使行为对于工具是有意的，命令行生成器和发布/工具脚本也可能触发命令执行发现。
- 完全的类型感知分析是 v0.3 的路线图项目。
- 内存中的扫描防护仅作为本地/单实例回退。
- 公共部署应使用可选的 Upstash/分布式防护或等效的平台级保护。
- 基于 IP 的限制依赖于受信任的代理/平台转发头。
- 网页演示仅扫描公共仓库，并且不运行仓库代码。
## GitHub Actions
本地终端扫描是手动的：`next-secure-check` 仅在您执行 CLI 时运行。GitHub Actions 扫描在您将工作流文件添加到仓库后是自动的；然后 GitHub 在配置的推送或拉取请求事件上运行扫描。该工具不会自行扫描仓库。
要获取基本的步骤摘要工作流，请将以下内容复制到 `.github/workflows/next-secure-check.yml` 中：
```
name: next-secure-check
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
security-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Run next-secure-check
shell: bash
run: |
set -o pipefail
npx --yes next-secure-check@0.2.0 scan . --preset app --format github --fail-on high | tee -a "$GITHUB_STEP_SUMMARY"
```
当发现严重级别为 `HIGH` 或以上的发现结果时，这将使拉取请求失败。如果您的团队需要更严格的严重性门控，请将 `--fail-on` 更改为 `medium`、`low` 或 `info`。当您仅希望在扫描摘要风险级别为 `critical` 时失败时，请使用 `--fail-on critical`。
对于 GitHub Code Scanning，请生成 SARIF 并上传：
```
name: next-secure-check SARIF
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
security-events: write
jobs:
security-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Run next-secure-check SARIF
run: npx --yes next-secure-check@0.2.0 scan . --preset app --format sarif --output next-secure-check.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: next-secure-check.sarif
```
发现结果是确定的模式匹配，而不是漏洞利用的证明。在将发现结果视为已确认的漏洞之前，请审查 `confidence`、`evidence` 和 `recommendation` 字段。
## 验证说明
手动验证说明：
- [第 4 阶段验证](./docs/validation/phase-4-validation.md)
- [第 4.5 阶段验证](./docs/validation/phase-4-5-validation.md)
- [第 6 阶段外部审查修复](./docs/validation/phase-6-external-review-fixes.md)
## v0.3 路线图
- 针对需要更深层数据流上下文的规则，进行完整的类型感知分析。
- 更深层的 XSS 清理器和源分析。
- 路由图和中间件感知的身份验证检测。
- 更好的 `unknown` 上下文分类。
- 自定义规则配置和规则启用/禁用控制。
- 网页演示的基于 Nonce/哈希的 CSP 加固。
- 公共托管演示加固。
- 更多的 GitHub Code Scanning 集成示例。
- 规则噪声减少和误报跟踪。
- VS Code 扩展或 ESLint 插件探索。
## 发布门控
```
CLI works before web.
Tests pass before NPM release.
GitHub Action works before SaaS.
Real user feedback comes before payments.
```
## 许可证
[MIT 许可证](./LICENSE)
标签：API路由安全, AST辅助分析, GitHub Actions集成, MITM代理, Next.js安全, npm包, SARIF报告, SQL注入检测, XSS风险检测, 上传安全, 仓库扫描, 图数据库, 安全头检查, 安全检查, 开发安全工具, 暗色界面, 确定性规则, 秘密泄露检测, 自动化攻击, 速率限制检查, 配置安全, 静态分析工具, 静态安全扫描, 预设扫描