maneesh-kumar-thakur/VSCE-Guardian-Secrets-Scanner

# 🛡️ Guardian - VS Code 密钥扫描器 **先进的安全扩展，可通过熵分析和自定义模式检测，在代码、配置和文本文件中发现密码、API密钥、令牌和敏感数据。** ## 🔒 我们的核心原则 ### 安全第一 Guardian 从构建之初就秉持 **安全第一的理念**。我们不仅检测密钥——更通过多层防御机制防止其进入您的代码库： - **🛡️ 多层防御**：实时扫描 → IDE 诊断 → 提交前阻止（需安装钩子） - **🚨 对关键密钥零容忍**（启用提交前钩子时）：AWS密钥、私钥和数据库密码将自动阻止提交 - **⚡ 安全左移**：在密钥被 **提交前** 就捕捉，而非暴露后才反应 - **🎯 主动预防，而非被动应对**：内置预防机制，不仅仅是检测 ### 设计即隐私 您的代码和数据隐私 **不容妥协**： - **🔐 100% 本地处理**：所有扫描都在您的机器上进行——任何数据都不会发送到外部服务器 - **🚫 零遥测**：我们不收集、传输或存储您的任何代码或发现结果 - **🎭 密钥掩码**：所有检测到的密钥在界面和日志中会自动掩码显示（例如：`AKIA****MPLE`） - **📜 开源**：完全透明——您可以自行审计我们的代码 - **🏠 您的数据归您所有**：无云依赖、无API调用、无数据泄露 ### 责任与合规 我们认真对待自身责任： ## 🚀 核心功能 ### Guardian 有何不同？ 1. **熵分析** - 使用香农熵计算来检测传统模式匹配可能遗漏的高随机性字符串 2. **多语言支持** - 扫描代码文件（.js, .ts, .py, .go 等）、配置文件（.env, .yaml 等）和文本文件 3. **上下文保留** - 每个发现结果都包含周围的代码上下文，方便人工审查 4. **实时扫描** - 保存时自动扫描文件（默认启用）；打开时扫描可用（默认禁用） 5. **全面的模式库** - 可检测 36 种类型的密钥，包括： - 云凭据（AWS、Azure、GCP） - API 密钥和令牌 - 数据库连接字符串 - 加密私钥 - 支付服务凭据 - 源代码控制令牌 - 以及更多... 6. **自定义模式支持** - 添加您自己的正则表达式模式，用于检测组织特定的密钥 7. **误报抑制** - 可将发现结果标记为误报并附上理由；轻松管理抑制记录 8. **安全仪表板** - 可视化仪表板，展示安全概览和发现结果摘要 9. **导出为 Markdown 或 CSV** - 导出报告用于外部分析和合规 10. **基于严重性的过滤** - 优先关注关键问题 11. **Git 提交阻止** - 提交前钩子（安装后）可阻止包含密钥的提交 ## 📦 安装 ### 通过 VSIX 安装 1. 下载 `.vsix` 文件 2. 打开 VS Code 3. 按下 `Ctrl+Shift+P`（Mac 上为 `Cmd+Shift+P`） 4. 输入 "Install from VSIX" 5. 选择已下载的文件 ### 从源代码安装 ``` git clone https://github.com/maneesh-kumar-thakur/VSCE-Guardian-Secrets-Scanner.git cd VSCE-Guardian-Secrets-Scanner npm install npm run compile # 在 VS Code 中按 F5 进行调试 ``` ## 🎯 使用 ### 命令 按下 `Ctrl+Shift+P`（Mac 上为 `Cmd+Shift+P`）并搜索： - **Guardian: 扫描整个工作区** - 扫描工作区中的所有文件 - **Guardian: 扫描当前文件** - 仅扫描活动文件 - **Guardian: 显示安全仪表板** - 打开可视化安全仪表板 - **Guardian: 清除所有发现** - 清除所有已检测到的发现结果 - **Guardian: 导出安全报告** - 将发现结果导出为 Markdown 或 CSV - **Guardian: 添加自定义模式** - 添加组织特定的检测模式 - **Guardian: 安装提交前钩子** - 阻止包含密钥的提交 - **Guardian: 扫描暂存文件** - 在提交前检查文件 - **Guardian: 查看抑制报告** - 查看所有抑制记录的审计 - **Guardian: 打开设置** - 配置 Guardian 选项 ### 活动栏 点击活动栏中的 **Guardian 盾牌** 图标可查看： - 按严重性分组的安全发现结果 - 统计数据和概览 - 快速导航到问题位置 ### 状态栏 底部状态栏实时显示安全状态： - 🛡️ **Guardian: 安全** - 未检测到问题 - ⚠️ **Guardian: X 个关键问题** - 发现关键问题 - ℹ️ **Guardian: X** - 较低严重性问题 ## ⚙️ 配置 Guardian 提供直观的设置界面以便于配置。 ### 打开设置 **选项 1：通过命令面板** ``` Ctrl+Shift+P (or Cmd+Shift+P on Mac) → "Guardian: Show Settings" ``` **选项 2：通过仪表板** - 点击 Guardian 安全仪表板上的 **设置** 按钮 **选项 3：通过标准设置** ``` Ctrl+, (or Cmd+, on Mac) → Search for "Guardian" ``` ### 设置类别 #### 🔍 检测设置 - **熵分析** - 通过分析字符随机性来检测密钥（默认启用） - **熵阈值** - 配置敏感性（3.0 = 捕获更多，6.0 = 严格，默认 4.5） - **最低严重性级别** - 仅报告关键、高、中或低严重性的发现结果 #### 📁 扫描设置 - **排除模式** - 要跳过的文件夹（默认为 node_modules, dist, build, .git） - **保存时扫描** - 启用文件保存时的自动扫描（默认：true） - **打开时扫描** - 启用文件打开时的自动扫描（默认：false） #### 🎯 自定义模式 - 添加您自己的正则表达式模式，用于检测组织特定的密钥 - 适用于检测公司特定的 API 密钥格式或内部令牌 #### 🔐 Git 安全设置 - **阻止关键密钥** - 阻止包含关键密钥的提交（默认：安装钩子时启用） - **阻止高严重性** - 可选择也阻止高严重性的密钥 - **自动扫描暂存区** - 每次提交前自动扫描暂存的文件 ### 高级配置 (settings.json) 您也可以直接在 `settings.json` 中编辑设置： ``` { // Detection "guardian.enableEntropyAnalysis": true, "guardian.entropyThreshold": 4.5, "guardian.severityLevel": "medium", // Scanning "guardian.scanOnSave": true, "guardian.scanOnOpen": false, "guardian.excludePatterns": [ "**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**" ], // Custom patterns "guardian.customPatterns": [], // Git integration "guardian.git.blockOnCritical": true, "guardian.git.blockOnHigh": false, "guardian.git.autoScanStaged": false } ``` ## 🔍 检测类别 Guardian 检测以下类别的密钥： ### 云凭据 - AWS 访问密钥、秘密密钥、会话令牌 - Google Cloud API 密钥、服务帐户、OAuth - Azure 存储密钥、客户端密钥 ### API 密钥与令牌 - 通用 API 密钥 - Bearer 令牌 - 授权头 - JSON Web Tokens (JWT) ### 源代码控制 - GitHub 个人访问令牌、OAuth、应用令牌 - GitLab 个人访问令牌 ### 数据库 - 连接字符串（MongoDB、MySQL、PostgreSQL） - 数据库密码 ### 加密密钥 - RSA 私钥 - SSH 私钥 - PGP 私钥 ### 支付服务 - Stripe API 密钥 - PayPal/Braintree 令牌 ### 通讯服务 - Slack 令牌和 Webhooks - Twilio API 密钥 ### 邮件服务 - SendGrid API 密钥 - Mailgun API 密钥 - Mailchimp API 密钥 ### 包管理器 - NPM 令牌 - PyPI API 令牌 ### 通用密钥 - 代码中的密码 - 密钥 - 敏感关键字附近的高熵字符串 ## 🧮 熵分析 Guardian 使用 **香农熵** 来检测不符合已知模式的潜在密钥： ``` Entropy = -Σ(p(x) * log₂(p(x))) ``` - **低熵**（~2.0）："aaaaaaa" 或 "1111111" - **中等熵**（~3.5）："password123" - **高熵**（~4.5+）："K7x9Mq2Wp5Nz8Rt3" ← 很可能是密钥！ 具有高熵（随机性）且字符类型多样的字符串会被标记为潜在密钥。 ## 📊 安全仪表板 可视化仪表板提供： - **统计信息**：按严重性和类别统计的发现计数 - **概览**：快速查看安全状态 - **导航**：点击发现结果可跳转到代码中的确切位置 - **过滤**：关注特定严重性级别或类型 ## 🛡️ 最佳实践 ### Git 提交保护 **安装提交前钩子**： ``` # 通过命令面板 Ctrl+Shift+P → "Guardian: Install Pre-commit Hook" ``` 这将自动阻止包含密钥的提交： - ✅ 关键密钥 → 提交被阻止 - ⚠️ 高严重性密钥 → 警告（可配置） - ℹ️ 中/低严重性 → 仅提示信息 **手动验证**： ``` # 提交之前 Ctrl+Shift+P → "Guardian: Scan Staged Files" ``` 有关详细的 Git 配置，请参见上面的设置部分。 ### 预防措施 1. **使用环境变量**：将密钥存储在 `.env` 文件中（添加到 `.gitignore`） 2. **密钥管理**：使用 AWS Secrets Manager、HashiCorp Vault 或类似工具 3. **提交前钩子**：将 Guardian 添加到提交前钩子，以防止密钥被提交 4. **定期扫描**：安排工作区定期扫描 ### 修复措施 如果 Guardian 发现密钥： 1. **关键/高严重性**： - ✅ 立即轮换凭据 - ✅ 检查访问日志是否有未授权使用 - ✅ 从仓库历史记录中删除（使用 `git-filter-repo`） - ✅ 更新所有使用该凭据的系统 2. **中/低严重性**： - ✅ 审查是否为真实密钥或误报 - ✅ 移至环境变量或密钥管理器 - ✅ 更新 `.gitignore` 以防止未来提交 ### 管理误报 Guardian 提供 **带有审计跟踪的综合抑制系统**： **抑制某个发现**： ``` # 通过树视图（推荐） Right-click finding in Guardian Security sidebar → "Suppress Finding (Mark as False Positive)" # 通过命令面板 Ctrl+Shift+P → "Guardian: Suppress Finding" ``` - 提供理由（例如：“单元测试模拟 AWS 密钥”） - 抑制记录将存储您的用户名和时间戳 - 自动记录到审计跟踪 **查看所有抑制记录**： ``` Ctrl+Shift+P → "Guardian: View Suppressed Findings" ``` - 查看所有已抑制的发现结果及其理由 - 可选择查看文件 - 可选择取消抑制发现 **审计与合规**： ``` # 查看抑制统计和历史 Ctrl+Shift+P → "Guardian: View Suppression Report" # 审查待处理超过 30 天的抑制 Ctrl+Shift+P → "Guardian: Review Pending Suppressions" # 为外部工具导出发现结果 Ctrl+Shift+P → "Guardian: Export Security Report" ``` **存储与审计跟踪**： - ✅ **工作存储**：`.vscode/guardian-suppressions.json`（工作区本地） - ✅ **审计日志**：`SUPPRESSIONS_AUDIT.md`（可由 Git 跟踪） - ✅ **元数据**：文件路径、行号、模式、原因、时间戳、用户名 - ✅ **历史记录**：所有抑制/取消抑制/审查操作的完整记录 **用于团队与合规**： - 提交 `SUPPRESSIONS_AUDIT.md` 以实现团队可见性 - 所有抑制记录均关联用户名以确保责任可溯 - 历史审计跟踪用于安全审查 有关审计日志的完整详细信息，请参阅 [SUPPRESSION_AUDIT_GUIDE.md](docs/SUPPRESSION_AUDIT_GUIDE.md)。 ## 🎨 自定义模式 添加组织特定的模式： ``` // Example: Detect custom API key format { "name": "Acme Corp API Key", "pattern": "ACME_[A-Z]{4}_[0-9a-f]{32}", "severity": "critical", "description": "Acme Corp API key detected", "flags": "gi" } ``` ## 📈 性能 - **快速扫描**：使用优化的正则表达式模式 - **智能排除**：自动跳过 node_modules、dist 等目录 - **增量式**：保存时扫描仅检查已修改的文件 - **可配置**：控制扫描范围 ## 📄 许可证 MIT 许可证 - 详见 LICENSE 文件 ## 🧪 测试 Guardian 包含全面的单元测试，涵盖： - 模式检测准确性 - 熵计算 - 扫描器功能 - 误报过滤 ``` # 运行测试 npm install npm test ``` 测试位于 `src/test/` 目录中。 ## 🔒 安全与隐私保证 ### 我们保护什么 **您的代码**： - ✅ 永远不会离开您的机器 - ✅ 永远不会发送到外部服务器 - ✅ 永远不会被远程记录或存储 - ✅ 永远不会用于训练或分析 **您的密钥**： - ✅ 在所有界面显示中被掩码 - ✅ 在所有日志文件中被掩码 - ✅ 在导出的报告中被掩码 - ✅ 永远不会在错误消息中暴露 **您的隐私**： - ✅ 无用户跟踪 - ✅ 无分析数据收集 - ✅ 无回传功能 - ✅ 无需互联网连接 ### 安全架构 ``` ┌─────────────────────────────────────────┐ │ Your VS Code (Local Environment) │ │ │ │ ┌───────────────────────────────┐ │ │ │ Guardian Extension │ │ │ │ │ │ │ │ • Scans locally │ │ │ │ • Processes in-memory │ │ │ │ • No network calls │ │ │ │ • No external dependencies │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Your Files │ │ │ │ (Never sent externally) │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────────┘ ↓ Results stay local ↓ You control everything ``` ### 安全认证 - ✅ 无外部 API 依赖 - ✅ 无遥测或跟踪 - ✅ 完全离线运行 - ✅ 开源以供安全审计 - ✅ 无第三方数据共享 ### 信任模型 **零信任架构**： 1. 默认不信任任何事物 2. 本地验证一切 3. 假设已被入侵（多层防御） 4. 最小化爆炸半径（在提交前阻止） 5. 持续验证（实时扫描） Guardian 帮助您发现密钥，但自身 **绝不** 成为漏洞。 ## 🛡️ 安全最佳实践 Guardian 是一款 **安全工具**，而非安全风险。用它来： - ✅ 防止凭据暴露 - ✅ 满足合规要求 - ✅ 教育开发人员安全意识 - ✅ 建立安全第一的文化 始终将 Guardian 与以下措施结合使用： - 密钥管理工具（AWS Secrets Manager、Vault） - 代码审查流程 - 安全培训 - 事件响应计划 **请记住**：没有完美的工具。将 Guardian 作为综合安全策略的一部分使用。 ## ⚠️ 免责声明 虽然 Guardian 很全面，但没有自动工具能捕捉 100% 的密钥。请始终： - 人工审查代码中的敏感数据 - 使用适当的密钥管理实践 - 遵循您组织的安全政策 ### 获取帮助 - **文档**： - [README](README.md) - 功能概述（本文件） - [安全策略](SECURITY.md) - 安全漏洞与报告 - [抑制指南](docs/SUPPRESSION_AUDIT_GUIDE.md) - 审计日志与抑制 - [变更日志](docs/CHANGELOG.md) - 版本历史与更新 - **报告错误**：[GitHub Issues](https://github.com/maneesh-kumar-thakur/VSCE-Guardian-Secrets-Scanner/issues) - 包含 Guardian 版本、VS Code 版本、文件类型 - 提供最小化的复现步骤 - 请勿在错误报告中包含实际的密钥 - **功能请求**：[GitHub Issues](https://github.com/maneesh-kumar-thakur/VSCE-Guardian-Secrets-Scanner/issues) 并打上 `enhancement` 标签 - 描述使用场景 - 解释它如何提高安全性 - **问题与讨论**：[GitHub Discussions](https://github.com/maneesh-kumar-thakur/VSCE-Guardian-Secrets-Scanner/discussions) - 提问使用方法 - 分享技巧和最佳实践 ### 安全报告 **重要**：如果您发现 **Guardian 本身** 存在漏洞： 1. **请勿** 公开发布 GitHub issue 2. 将安全详情发送至邮箱：[maneeshkumar.thakur@outlook.com](mailto:maneeshkumar.thakur@outlook.com) 3. 包括描述、复现步骤和潜在影响 4. 请允许 48 小时的确认时间 5. **替代方案**：使用 [GitHub 安全公告](https://github.com/maneesh-kumar-thakur/VSCE-Guardian-Secrets-Scanner/security) ### 快速故障排除 **Guardian 未检测到密钥？** - 验证设置中 `guardian.scanOnSave` 已启用 - 检查文件类型是否受支持（JavaScript、Python、Go、Java、TypeScript 等） - 尝试手动扫描：`Ctrl+Shift+P` → "Guardian: 扫描整个工作区" - 检查熵阈值设置 **误报过多？** - 增加 `guardian.entropyThreshold`（值越高 = 检测越严格） - 带理由地抑制发现结果，以便团队查看 - 在 `guardian.excludePatterns` 中添加模式以排除误报类别 **提交前钩子问题？** - 验证工作区中已初始化 Git - 运行：`Ctrl+Shift+P` → "Guardian: 安装提交前钩子" - 检查 `.git/hooks/pre-commit` 文件权限 - 验证钩子可执行：`chmod +x .git/hooks/pre-commit` **性能问题？** - 禁用 `guardian.scanOnOpen`（默认仅在保存时扫描） - 在 `guardian.excludePatterns` 中排除大型文件夹 - 使用 `guardian.severityLevel` 关注关键问题 **为关心安全的开发者打造 🛡️** **"安全第一。隐私始终。信任从无。"** - Guardian 之道

标签：API密钥检测, AWS安全, DInvoke, GitHub安全, MITM代理, Redis利用, Shift-Left安全, Slack安全, Stripe安全, VS Code扩展, 人工智能安全, 代码安全, 令牌检测, 合规性, 多语言支持, 安全测试框架, 实时扫描, 密码检测, 开源, 敏感数据, 本地处理, 模式匹配, 漏洞枚举, 熵分析, 秘密扫描, 网络安全, 自动化攻击, 自动化资产收集, 输入验证, 配置文件扫描, 隐私保护