maiductuan/code-security-scanner

` | 无 | AI 提供商：`openai`、`anthropic`、`ollama` | `openai` | `deepscan scan --ai --ai-provider ollama` | | `--parallel ` | 无 | 并行执行的 worker 数量 | `4` | `deepscan scan --parallel 8` | | `--incremental` | 无 | 仅扫描更改的文件（基于 git） | `false` | `deepscan scan --incremental` | | `--preset ` | 无 | 使用预设配置 (`node-api`, `python-web`, `java-spring`, `minimal`) | 无 | `deepscan scan --preset node-api` | | `--config ` | 无 | 配置文件的路径 | `.deepscan.yml` | `deepscan scan --config ./deepscan-ci.yml` | ### CLI 子命令 ``` # 规则管理 deepscan rules list # List all loaded rules deepscan rules list --category injection # Filter rules by category deepscan rules low security/sql-injection # Show detailed rule details deepscan rules categories # Show all available categories # 配置 deepscan init # Initialize standard config file deepscan init --preset node-api # Initialize config with preset # 报告转换 deepscan report convert results.json --to html --output report.html ``` ## 🤖 AI 辅助验证 启用 AI 验证以减少误报（可选）： ``` # 设置 API key export OPENAI_API_KEY=sk-... # 或 export ANTHROPIC_API_KEY=sk-ant-... # 运行 AI validation deepscan scan --ai --ai-provider openai # 或使用本地 Ollama deepscan scan --ai --ai-provider ollama ``` ``` # .deepscan.yml ai: enabled: true provider: openai # or anthropic, ollama model: gpt-4o-mini maxFindings: 20 ``` ## 🏗️ 架构 ``` CLI → Pipeline → File Discovery → Language Detection ↓ Scanner Engines (parallel) ├── Security Scanner (patterns, taint, context) ├── Quality Scanner (complexity, duplication, metrics) └── CVE Scanner (dependency parsing, OSV query) ↓ Rule Engine (built-in + custom YAML rules) ↓ [Optional] AI Validator ↓ Reporter (JSON / CSV / HTML / SARIF / Console) ``` ## 📊 对比 | 功能 | DeepScan | SonarQube | Semgrep | Trivy | |---------|----------|-----------|---------|-------| | SAST | ✅ | ✅ | ✅ | ❌ | | SCA/CVE | ✅ | ✅ | ❌ | ✅ | | Secrets | ✅ | ✅ | ✅ | ✅ | | 感知上下文 | ✅ | ❌ | ❌ | ❌ | | 污点分析 | ✅ | ✅ | ✅ | ❌ | | AI 验证 | ✅ | ❌ | ✅ | ❌ | | 零基础设施 | ✅ | ❌ | ✅ | ✅ | | 自定义规则 (YAML) | ✅ | ❌ | ✅ | ❌ | | HTML 报告 | ✅ | ✅ | ✅ | ✅ | | SARIF 输出 | ✅ | ✅ | ✅ | ✅ | | 免费且开源 | ✅ | 部分免费 | 部分免费 | ✅ | ## 🛠️ 开发者与源码指南 本节面向希望从源码运行 DeepScan、贡献代码、修改规则处理脚本或调试 CLI 行为的开发者和用户。 ### 前置条件 - Node.js >= 18.0.0 - npm 或 yarn ### 设置 克隆仓库并安装所有依赖： ``` git clone https://github.com/your-org/code-scan-security.git cd code-scan-security npm install ``` ### 从源码运行 你可以使用 JIT 编译，直接从源码执行 DeepScan，而无需构建步骤。 ``` # 常规扫描 npm run dev -- scan ./src # 使用特定 flags 扫描 (例如：仅 security-only、JSON 输出) npm run dev -- scan ./src --security --format json # 运行规则列表 npm run dev -- rules list ``` 或者，你可以使用 `npx` 运行（它不需要 `--` 分隔符）： ``` npx tsx src/bin/deepscan.ts scan ./src --security ``` ### 构建 CLI 要将代码库编译为纯 JavaScript 以用于生产环境测试或分发： ``` npm run build ``` 这会将 TypeScript 源文件编译到 `dist/` 目录中： - `dist/bin/deepscan.js`（可执行入口点） - `dist/index.js`（库导出） 运行编译后的 JavaScript CLI 包： ``` node dist/bin/deepscan.js scan ./src ``` ### 测试、Lint 和类型检查 在进行更改之前，请验证测试和静态分析是否通过。 ``` # 运行所有测试一次 npm run test # 在 watch 模式下运行测试 npm run test:watch # Typecheck TypeScript 文件 npm run typecheck # Lint 代码库 (ESLint) npm run lint ``` ### 规则与脚本开发 - 要测试转换单个 Semgrep 规则文件： npx tsx scripts/convert-rules.ts --input tests/fixtures/semgrep-sample.yml --output rules/built-in/converted-semgrep.yml - 要运行完整的自动下载/转换脚本： 1. 在 [scripts/update-rules.ts](file:///d:/code/code-scan-security/scripts/update-rules.ts) 中进行修改。 2. 执行更新脚本： npm run rules:update 3. 运行测试套件： npm run test ## 📊 基准测试与准确性结果 为了验证 DeepScan 的检测能力，我们在 `examples/` 目录中维护了一个真实的多语言 monorepo 基准测试。它包含易受攻击的 controller、web 视图、动态路由和依赖清单，以及与之对应的 **Node/Express/NestJS**、**Python/Flask/Django**、**Go/net/http** 和 **PHP/Laravel** 安全代码。 我们的自动化评估框架衡量**召回率**（对真实漏洞的检测覆盖率）和**精确率**（避免对干净代码产生误报）。 ### 最新基准测试结果 (v1.0) - **真实漏洞总数**：29 - **召回率（检测率）**：**100.0%**（捕获 29/29 个漏洞） - **精确率（误报率）**：**100.0%**（触发 0 次误报） - **F1 分数**：**100.0%** #### 语言细分 | 语言 / 框架 | 预期漏洞 | 已捕获 (TP) | 遗漏 (FN) | 误报 (FP) | 准确率 (召回率) | |----------------------|---------------|-------------|-------------|-------------------|-------------------| | **JavaScript / TypeScript (Express, NestJS)** | 13 | 13 | 0 | 0 | **100.0%** | | **Python (Flask, Django)** | 7 | 7 | 0 | 0 | **100.0%** | | **Go (net/http)** | 3 | 3 | 0 | 0 | **100.0%** | | **Java (Maven, 标准)** | 3 | 3 | 0 | 0 | **100.0%** | | **PHP (Laravel, Blade)** | 3 | 3 | 0 | 0 | **100.0%** | 要运行准确性评估脚本并生成交互式 [evaluation-report.html](file:///d:/code/code-scan-security/evaluation-report.html) 仪表板： ``` npm run evaluate ``` ## 📚 文档 有关详细的设置和操作说明，请参阅： - [管理员指南](file:///d:/code/code-scan-security/docs/admin-guide.md) — 系统配置、自动规则集更新、CLI 选项参考以及规则分发。 ## 📄 许可证 MIT © DeepScan 贡献者