Zayan-Mohamed/secscan

# SecScan - 增强型密钥扫描器 ## 🚀 快速安装 ### Linux & macOS ``` curl -fsSL https://raw.githubusercontent.com/Zayan-Mohamed/secscan/main/scripts/install-curl.sh | bash ``` ### Windows (PowerShell) ``` irm https://raw.githubusercontent.com/Zayan-Mohamed/secscan/main/scripts/install-windows.ps1 | iex ``` ### 使用 Go ``` go install github.com/Zayan-Mohamed/secscan/v2@latest ``` ## 🚀 功能 - ✅ **增强型检测** - 内置 20 多种 API key、token 和密钥检测模式 - 🧠 **智能熵分析** - 可配置的 Shannon 熵检测，降低误报率 - 🎯 **去重** - 自动移除跨提交的重复发现 - 🚫 **白名单支持** - 过滤已知的误报 - 📊 **详细统计** - 跟踪扫描性能和覆盖率 - 🎨 **丰富的输出** - 颜色编码的严重性级别和整洁的格式 - 📜 **Git 历史扫描** - 深入扫描您的整个 git 历史 - 🔧 **可配置** - 通过 TOML 配置自定义规则 - ⚡ **快速** - 使用 Go 编写以实现最高性能 - 📄 **JSON 导出** - 用于 CI/CD 集成的机器可读输出 - 🙈 **Gitignore 支持** - 自动遵循 `.gitignore` 模式以跳过不相关的文件 - 🌍 **跨平台** - 适用于 Linux、macOS 和 Windows ## 📦 安装 ### 按平台快速安装 #### 🐧 Linux / 🍎 macOS ``` # 导航到 secscan 目录 cd secscan # 选项 1：使用安装脚本（推荐） ./install.sh # 选项 2：使用 Make make install # System-wide (requires sudo) # 或者 make install-local # User-only (no sudo) ``` #### 🪟 Windows ``` # 导航到 secscan 目录 cd secscan # 使用 PowerShell 脚本（推荐） .\install.ps1 # 对于全系统安装（需要管理员权限）： .\install.ps1 -Global ``` #### 🌍 通用安装程序（所有平台） 适用于 Linux、macOS 和 Windows： ``` cd secscan go run installer/install.go ``` ### 验证安装 ``` secscan -version which secscan ``` ## 🎯 快速开始 ``` # 扫描当前目录 secscan # 扫描指定目录 secscan -root /path/to/project # 不扫描 git 历史（更快） secscan -history=false # 遵守 .gitignore 文件（默认行为） secscan -respect-gitignore=true # 禁用 gitignore（扫描所有文件，包括被忽略的文件） secscan -respect-gitignore=false # 调整熵阈值（有效范围约 4.0-4.8；参见下方的 Entropy Threshold） secscan -entropy 4.5 # 完全禁用熵检测 secscan -no-entropy # 将结果导出为 JSON secscan -json report.json # 详细输出（显示所有发现） secscan -verbose # 静默模式（用于 CI/CD） secscan -quiet ``` ## 🔍 检测模式 SecScan 开箱即用地检测以下密钥类型： - **云服务提供商**：AWS key、Google API key - **支付**：Stripe key（live 和 restricted） - **版本控制**：GitHub token（PAT、OAuth、App） - **通讯**：Slack token 和 webhook - **电子邮件**：SendGrid、Mailgun API key - **数据库**：连接字符串（PostgreSQL、MySQL、MongoDB、Redis） - **身份验证**：JWT token、Supabase key - **通用**：API key、secret、密码 - **高熵**：看似随机的字符串（可配置） ## ⚙️ 配置 ### 自定义规则文件 创建一个 `.secscan.toml` 文件： ``` # 自定义检测规则 custom_api = "mycompany_api_[0-9a-zA-Z]{32}" internal_token = "int_tok_[A-Za-z0-9]{40}" ``` 使用它： ``` secscan -config .secscan.toml ``` ### Gitignore 支持 **SecScan 会自动遵循您仓库中的 `.gitignore` 文件**，这有助于： - ✅ 跳过构建产物、依赖项和生成的文件 - ✅ 减少来自 vendor 代码的误报 - ✅ 通过跳过不相关的文件来加快扫描速度 - ✅ 与您现有的 Git 工作流无缝协作 **工作原理：** - 自动查找并加载仓库中的所有 `.gitignore` 文件 - 支持子目录中的嵌套 `.gitignore` 文件 - 处理否定模式（`!important.txt`） - 支持仅目录模式（`logs/`） - 兼容标准的 gitignore glob 模式 **示例：** ``` # 默认：启用 gitignore secscan -root . # 显式启用 gitignore（与默认相同） secscan -respect-gitignore=true # 禁用 gitignore 以扫描所有文件（适用于安全审计） secscan -respect-gitignore=false # 详细模式会显示哪些文件正在被跳过 secscan -verbose -respect-gitignore=true ``` **何时禁用 gitignore：** - 需要扫描所有内容的安全审计 - 检查构建产物中是否存在密钥 - 调试扫描结果 ### 熵阈值 熵阈值控制字符串必须达到何种程度的“随机”才会被标记。 仅在将值命名为凭据的行上（`api_key = "..."`、`token: ...`），并且仅针对长度为 20-100 个字符的 token 才会参考熵。 单独使用它不是一个可用的检测器 —— 将其设置得足够高以拒绝普通 源代码时，它也会拒绝真正的凭据；将其设置得足够低以捕获它们时， 树中的每个 base64 片段都会触发。 - **默认**：4.1 - **更严格**：4.5（更少、更高置信度的发现） - **禁用**：使用 `-no-entropy` 有用的范围很窄，而且上限并不是个人喜好的问题。基于 token 自身字符的 Shannon 熵不能超过 `log2(len)`，因此 20 个字符的密钥最高为 4.32，32 个字符的最高为 5.00。真正的 凭据大约在 4.7 到 4.8 之间 —— GitHub PAT 得分为 4.77， Stripe key 为 4.75。5.0 或以上的阈值并不“严格”；它是 无法达到的，并且什么也检测不到。高于 ~4.8 的值没有用处。 默认值刚好高于 `log2(16) = 4.0`（即十六进制的上限），因此 git SHA 和完整性哈希在构造上而非运气上被排除在外。 ``` # 更严格 - 更少、置信度更高的发现 secscan -entropy 4.5 # 宽松模式 - 捕获更多潜在的 secrets secscan -entropy 4.0 ``` ## 📊 输出格式 ### 人类可读输出 ``` 🔍 SecScan v2.0.0 - Enhanced Secret Scanner 📂 Scanning: /path/to/project ⚙️ Entropy threshold: 4.1 📋 Rules loaded: 20 📜 Git history: enabled 🔍 Secret Scan Results ================================================== Total findings: 5 Critical (≥0.9): 2 High (≥0.8): 1 Medium (≥0.6): 2 Low (<0.6): 0 ================================================== 🔴 [CRITICAL] [AWS_ACCESS_KEY] src/config.js:42 → AKIA****************ABCD (confidence: 0.90) 🟠 [HIGH] [GITHUB_PAT] .env:15 → ghp_********************************WXYZ (confidence: 0.85) 📊 Scan Statistics ================================================== Files scanned: 1,234 Commits scanned: 567 Total findings: 12,345 Unique findings: 5 Scan duration: 2.5s ================================================== ``` ### JSON 输出 ``` { "findings": [ { "file": "src/config.js", "line": 42, "pattern": "aws_access_key", "excerpt": "AKIA****************ABCD", "confidence": 0.9, "verified": false, "hash": "a1b2c3d4e5f6g7h8" } ], "stats": { "files_scanned": 1234, "commits_scanned": 567, "findings_total": 12345, "findings_unique": 5, "scan_duration_ms": 2500 }, "version": "2.0.0" } ``` ## 🛡️ CI/CD 集成 ### GitHub Actions ``` name: Secret Scan on: [push, pull_request] jobs: secscan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 # Full history for git scanning - name: Setup Go uses: actions/setup-go@v4 with: go-version: "1.21" - name: Install SecScan run: | cd secscan make install-local - name: Run SecScan run: secscan -quiet -json secscan-report.json - name: Upload Results if: always() uses: actions/upload-artifact@v3 with: name: secscan-report path: secscan-report.json ``` ### GitLab CI ``` secret_scan: image: golang:1.21 script: - cd secscan - make install-local - export PATH="$HOME/.local/bin:$PATH" - secscan -quiet -json report.json artifacts: reports: junit: report.json when: always ``` ## 🎓 工作原理 ### 1. 模式匹配 SecScan 使用正则表达式模式来检测已知的密钥格式（AWS key、GitHub token 等） ### 2. 熵分析 计算 Shannon 熵以查找可能是密钥的高随机性字符串： ``` Entropy = -Σ(p(x) * log2(p(x))) ``` 具有熵 > 阈值且字符集多样的字符串将被标记。 ### 3. 去重 使用 SHA-256 哈希来识别并移除跨不同文件/提交的重复发现。 ### 4. 白名单 过滤常见的误报： - 全大写常量 - 测试/示例值 - 布尔字面量 - 已掩码的密钥 ## 🔧 高级用法 ### 为提高速度跳过 Git 历史 ``` secscan -history=false ``` ### 仅扫描特定模式 创建一个仅包含所需规则的最小配置： ``` # minimal-rules.toml aws_access_key = "AKIA[0-9A-Z]{16}" github_pat = "ghp_[0-9a-zA-Z]{36}" ``` ``` secscan -config minimal-rules.toml ``` ### 与其他工具结合使用 ``` # 查找 secrets 并按 pattern 过滤 secscan -json findings.json jq '.findings[] | select(.pattern == "aws_access_key")' findings.json # 按类型统计 secrets 数量 jq '.findings | group_by(.pattern) | map({pattern: .[0].pattern, count: length})' findings.json ``` ## 📈 相比 v1.0 的改进 | 功能 | v1.0 | v2.0 | | -------------------- | -------------------- | -------------------- | | 检测模式 | 4 | 20+ | | 误报率 | 高（511K 个发现） | 低（约减少 95%） | | 去重 | ❌ | ✅ | | 白名单支持 | ❌ | ✅ | | 可配置熵 | ❌（固定为 4.0） | ✅（默认为 4.1） | | 跳过文件/目录 | 有限 | 全面 | | 输出格式 | 基础 | 带有颜色的丰富格式 | | 统计 | ❌ | ✅ | | 性能 | 良好 | 极佳 | ## 📄 许可证 MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件 ## 📞 支持 - 🐛 [报告问题](https://github.com/Zayan-Mohamed/secscan/issues) - 💬 [讨论](https://github.com/Zayan-Mohamed/secscan/discussions) - 📧 电子邮件：[Zayan Mohamed](mailto:itsm.zayan@gmail.com)

标签：DevSecOps, EVTX分析, Go, Python安全, Ruby工具, StruQ, 上游代理, 安全助手, 日志审计