# sec-scan **Repository Path**: cabbagezzw/sec-scan ## Basic Information - **Project Name**: sec-scan - **Description**: 代码安全扫描skill - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-22 - **Last Updated**: 2026-08-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # sec-scan-code 多语言安全代码扫描器，基于 OWASP Top 10:2025 规则体系，支持宪法优先级系统和 MCP 部署。 ## 概述 sec-scan-code 是一个面向代码安全审计的扫描工具，可作为 **Claude Code Skill**、**Trae Skill**、**CodeBuddy Skill** 和 **MCP Server** 使用。它采用规则分离架构，将漏洞的"是什么"（OWASP 元数据）与"怎么查"（语言特定模式）解耦，在扫描时动态合并，实现对 Python、JavaScript、Go、Java、C 五种语言的精准安全扫描。 同时提供 AI 代码生成安全规则，支持 Claude Code、Trae 和 CodeBuddy 在生成代码时自动遵守安全编码规范。 ### 重要: 下载技能包之后，对于包内的.codebuddy和.trae中的规则文件，可以复制到codebuddy或trae对应的规则文件目录中；对于其他技能文件，claude code和codebuddy可以复制到skill目录中直接使用，trae需要在IDE的配置中导入skill zip文件才能通过 /sec-scan-code 命令使用。 ## 核心特性 - **多语言支持** — Python、JavaScript、Go、Java、C - **OWASP Top 10 (2025)** — 完整覆盖 OWASP Top 10 漏洞类别 - **补充规则** — CSRF、XSS、路径穿越、不安全反序列化、竞态条件 - **宪法优先级系统** — 双层宪法文件驱动扫描优先级 - **三种扫描模式** — 增量扫描（默认）、全量扫描、快速扫描 - **大数据分析** — 历史扫描趋势分析，自动更新项目宪法 - **多格式报告** — JSON（默认）、XML、CSV、HTML - **MCP 部署** — 作为 MCP Server 暴露 6 个工具供外部调用 - **只读安全** — 扫描器不修改任何源代码，仅产出发现和建议 - **AI 安全规则** — Trae/CodeBuddy 代码生成时自动遵守安全规范 ## 架构 ### 规则分离架构 ``` OWASP YAML (查什么) × Language YAML (怎么查) → 完整扫描规则 ───────────────────────── ───────────────────────── ────────────── rule_id: A03-INJECTION language: python A03 × python categories: [sql-injection, rules: → sql-injection: [...] command-injection, ...] - category: sql-injection command-injection: [...] owasp: A03 patterns: [...] ``` ### 宪法优先级系统 | 优先级 | 宪法文件 | 说明 | | --- | ---------------------------------- | ------------------------------ | | 最高 | 宪法文件2（`constitution-project.yaml`） | 项目特定规则，由 `--analyze` 大数据分析自动生成 | | 高 | 宪法文件1（`constitution-owasp.yaml`） | OWASP Top 10 规则，始终加载 | | 普通 | 补充规则（`rules/supplementary/`） | `--full` 时或显式请求时加载 | ### 扫描流程 ``` Phase 0: 确定扫描范围（增量/全量/指定文件） ↓ Phase 1: 语言检测（检测项目使用的编程语言） ↓ Phase 2: 规则加载（OWASP 元数据 × 语言模式 → 合并规则） ↓ Phase 3: 任务收集（列出待扫描的漏洞类别） ↓ Phase 4: 扫描执行（逐文件逐规则匹配，支持子代理并行） ↓ Phase 5: 结果汇总（去重、按严重度排序） ↓ Phase 6: 结果持久化（写入 .sec-scan-code/reports/） ↓ Phase 7: 大数据分析（可选，更新项目宪法文件） ``` ## 项目结构 ``` sec-scan-code/ ├── SKILL.md # Claude Code Skill 定义文件 ├── README.md # 本文档 ├── pyproject.toml # Python 项目配置 ├── bin/ │ ├── detect-languages.sh # 语言检测脚本 │ └── generate-constitution-brief.sh # 宪法摘要生成脚本 ├── secscancode/ │ ├── __init__.py │ ├── server.py # MCP Server（6 个工具） │ ├── scanner.py # 扫描引擎 │ ├── rules_loader.py # 规则加载与合并 │ ├── analyzer.py # 大数据趋势分析 │ └── reporter.py # 多格式报告生成 ├── rules/ │ ├── constitution-owasp.yaml # 宪法文件1：OWASP Top 10 │ ├── constitution-project.yaml # 宪法文件2：项目特定规则 │ ├── owasp/ # OWASP 漏洞元数据（A01-A10） │ ├── supplementary/ # 补充规则（CSRF/XSS/路径穿越等） │ ├── languages/ # 语言特定模式 │ │ ├── python.yaml │ │ ├── javascript.yaml │ │ ├── go.yaml │ │ ├── java.yaml │ │ └── c.yaml │ └── docs/ # 漏洞说明文档 ├── templates/ │ ├── report-html.py # HTML 报告模板（独立使用） │ └── report-html.css # HTML 报告样式 ├── install.sh # 安装脚本（macOS/Linux） └── install.ps1 # 安装脚本（Windows） ``` *** ## 使用方式 ### 一、Claude Code Skill 在 Claude Code 中直接使用斜杠命令： | 命令 | 说明 | | ------------------------------------ | ------------------- | | `/sec-scan-code` | 增量扫描（默认，仅扫描当前会话变更） | | `/sec-scan-code --full` | 全量扫描（扫描项目所有源文件） | | `/sec-scan-code --quick` | 快速扫描（仅宪法规则检查变更文件） | | `/sec-scan-code --lang python` | 仅扫描指定语言 | | `/sec-scan-code --owasp` | 仅扫描 OWASP Top 10 规则 | | `/sec-scan-code --files a.py,b.go` | 扫描指定文件 | | `/sec-scan-code --analyze` | 大数据分析（更新项目宪法） | | `/sec-scan-code --formats json,html` | 指定输出格式（默认 JSON） | #### 安装方法 使用安装脚本（推荐）： ```bash # macOS / Linux bash install.sh # Windows PowerShell powershell -ExecutionPolicy Bypass -File install.ps1 ``` 安装脚本会交互式引导你选择： 1. **目标智能体**：Claude Code / Trae / CodeBuddy 2. **安装级别**：用户级（全局可用）/ 项目级（仅当前项目） 脚本会自动将文件复制到正确目录并替换路径占位符。 也可以通过命令行参数直接指定： ```bash # macOS / Linux bash install.sh --agent claude-code --level user # Windows PowerShell powershell -ExecutionPolicy Bypass -File install.ps1 -Agent trae -Level project -ProjectPath C:\my-project ``` 配置hook，进行AI代码生成时规则检查，在setting.json中添加以下内容： ```json "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "bash ~/.claude/skills/sec-scan-code/bin/hook-inject-constitution.sh", "timeout": 10 } ] } ] }, ``` 参数说明： | 参数 | 说明 | 可选值 | | ---------------- | -------------- | ---------------------------------- | | `--agent` | 目标智能体 | `claude-code`, `trae`, `codebuddy` | | `--level` | 安装级别 | `user`（用户级）, `project`（项目级） | | `--project-path` | 项目路径（项目级时） | 默认当前目录 | | `--skip-deps` | 跳过 Python 依赖安装 | - | | `-y` / `--yes` | 非交互模式（自动确认） | - | *** ### 二、Trae Skill 使用安装脚本（推荐）： ```bash bash install.sh --agent trae --level user # 用户级 bash install.sh --agent trae --level project # 项目级 ``` 安装完成后： - **sec-scan-code 技能**安装到 `~/.trae/skills/sec-scan-code/`（用户级）或 `.trae/skills/sec-scan-code/`（项目级） - 在对话中输入 `/sec-scan-code` 即可使用 - **AI 安全规则**需要单独安装（见下方「AI 安全规则」部分） *** ### 三、CodeBuddy Skill 使用安装脚本（推荐）： ```bash bash install.sh --agent codebuddy --level user # 用户级 bash install.sh --agent codebuddy --level project # 项目级 ``` 安装完成后： - **sec-scan-code 技能**安装到 `~/.codebuddy/skills/sec-scan-code/`（用户级）或 `.codebuddy/skills/sec-scan-code/`（项目级） - 在对话中输入 `/sec-scan-code` 即可使用 - **AI 安全规则**需要单独安装（见下方「AI 安全规则」部分） *** ### 四、AI 安全规则（独立安装） AI 安全规则让 Trae/CodeBuddy 在生成代码时自动遵守安全编码规范，独立于扫描技能打包和安装。 | 平台 | 规则目录 | 文件格式 | | --------- | ---------------------------------------------------- | ------ | | Trae | `~/.trae/rules/`（用户级）或 `.trae/rules/`（项目级） | `.md` | | CodeBuddy | `~/.codebuddy/rules/`（用户级）或 `.codebuddy/rules/`（项目级） | `.mdc` | 安装方式：将对应的规则包解压到规则目录即可。 规则覆盖范围： | 规则文件 | 激活条件 | 覆盖漏洞类型 | | ------------------- | -------------------------------- | ---------------------------------------------------- | | security-general | 所有文件 | 输入验证、凭据管理、认证授权、错误处理、CORS、加密、日志、随机数、重定向、文件上传、HTTP头 | | security-python | `*.py`, `*.pyw` | SQL注入、命令注入、模板注入、eval/exec、反序列化、SSRF、Django专项、文件操作、限流 | | security-javascript | `*.js`, `*.ts`, `*.jsx`, `*.tsx` | DOM XSS、原型污染、eval、正则DoS、Node.js专项 | | security-go | `*.go` | SQL注入、命令注入、路径穿越、SSRF、并发安全 | | security-java | `*.java`, `*.kt` | SQL注入、XXE、反序列化、Spring Security、路径穿越 | | security-c | `*.c`, `.h`, `.cpp` | 缓冲区溢出、格式化字符串、整数溢出、内存管理 | *** ### 五、MCP Server 安装脚本会自动处理路径。如需手动配置 MCP Server，在智能体配置目录的 `settings.json` 中添加： ```json { "mcpServers": { "sec-scan-code": { "command": "python", "args": ["-m", "secscancode.server"], "cwd": "" } } } ``` 将 `` 替换为实际的 skill 安装路径。 MCP 工具列表： | 工具名 | 说明 | | --------------------------------- | ------------- | | `sec_scan_incremental` | 增量扫描 | | `sec_scan_full` | 全量项目扫描 | | `sec_scan_quick` | 快速宪法扫描 | | `sec_scan_analyze` | 大数据分析与宪法更新 | | `sec_scan_list_rules` | 列出可用规则 | | `sec_scan_get_constitution_brief` | 获取宪法摘要用于上下文注入 | *** ## 扫描结果示例 ``` SEC-SCAN RESULTS ════════════════ Mode: incremental Files: 3 scanned, 450 lines Languages: python, javascript FINDINGS (sorted: severity desc, category asc) ════════ # Sev Category File:Line 1 CRIT command-injection app/models/user.py:42 2 CRIT sql-injection app/models/user.py:38 3 HIGH hardcoded-secret config/settings.py:15 4 HIGH xss-reflected src/api/handler.js:18 5 MEDIUM cors-wildcard app/main.py:15 TOTALS: 2 CRITICAL, 2 HIGH, 1 MEDIUM ⚠ AI扫描不完善风险：可能遗漏复杂漏洞链、跨文件数据流漏洞、 运行时才触发的漏洞。建议结合专业安全审计工具使用。 ``` *** ## 漏洞覆盖 ### OWASP Top 10 (2025) | ID | 漏洞类别 | 严重度 | | --- | -------------- | -------- | | A01 | 权限控制失效（含 SSRF） | CRITICAL | | A02 | 安全配置错误 | HIGH | | A03 | 供应链失败 | HIGH | | A04 | 加密失败 | HIGH | | A05 | 注入攻击 | CRITICAL | | A06 | 不安全设计 | HIGH | | A07 | 认证失败 | CRITICAL | | A08 | 软件和数据完整性失败 | HIGH | | A09 | 日志监控失败 | MEDIUM | | A10 | 异常处理不当（新增） | HIGH | ### 补充规则 - CSRF — 跨站请求伪造 - XSS — 跨站脚本攻击 - 路径穿越 - 不安全反序列化 - 竞态条件 *** ## 依赖 - Python >= 3.10 - mcp >= 1.0.0 - PyYAML >= 6.0 - Jinja2 >= 3.1 *** ## 重要规则 - **默认增量扫描** — 全量扫描开销大，需显式指定 `--full` - **语言感知** — 仅加载检测到语言的规则 - **宪法优先** — OWASP + 项目特定规则始终优先检查 - **只读操作** — 不修改源代码，仅产出发现和建议 - **置信度评分** — 每个发现附带 1-10 置信度，低于 7 会附加说明 - **AI 局限性声明** — 结果中始终包含 AI 扫描局限性提示 *** ## 许可证 MIT License