Grimwald79/Zero-Point-Secret-Scanner
GitHub: Grimwald79/Zero-Point-Secret-Scanner
一款基于 AST 语法树和熵值算法的本地 Pre-Commit 扫描器，用于精准拦截高熵密钥与 Token 泄露。
Stars: 0 | Forks: 0
# Zero Point Secret Scanner
一款自动化的本地 Pre-Commit Secret Scanner，旨在防止高熵加密密钥和 API Token 进入你的 Git 历史。
与严重依赖脆弱正则表达式 的传统 Secret Scanner 不同，该工具结合了 **Shannon Entropy Mathematics** 和 **Abstract Syntax Tree (AST) Parsing**，以语义化方式理解你的代码并大幅减少误报。
## 🧠 架构：为什么选择 AST + Entropy？
大多数 Secret Scanner 使用 Regex 查找诸如 `secret` 或 `password` 之类的关键词。当自然语言字符串或 docstrings 触发误报时，这会导致“警报疲劳”。
本扫描器采用“基于技能”的方法：
1. **语义理解 (AST)：** 扫描器使用 Python 原生的 `ast` 模块 (`ast.walk`)。它忽略变量名、函数定义和注释。它*仅*评估代码中赋值的字面值 (`ast.Constant`)。
2. **数学随机性：** 如果评估一个字符串，我们会计算其 Shannon Entropy ($H = -\sum p_i \log_2 p_i$)。由于字符的随机性，加密密钥（如 AWS Access Key）具有较高的 Entropy 得分。
3. **结构化启发式规则：** 为了防止长英文句子触发 Entropy 阈值，扫描器会显式过滤掉包含空格的字符串。
## 🛡️ 内置威胁模型缓解措施
* **无命令注入：** 对 Git 的 Subprocess 调用使用带有 `shell=False` 的严格列表参数。
* **Doos 防护：** 在向 AST Parser 分配内存之前强制执行文件大小限制（默认 500 KB）。
* **信息泄露防护：** 发现的 Secret 在写入生成的 Markdown 报告之前会在本地进行掩码处理 (`AKI...[MASKED]...PLE`)。
* **路径遍历保护：** 所有本地文件生成均利用严格的路径解析限制。
## ⚙️ 环境要求
* **Python：** 3.12+（利用现代类型提示和语法）
* **Git：** 必须在你的仓库中初始化
* **操作系统：** 跨平台（Windows、macOS、Linux）
## 🚀 安装与设置
你无需配置复杂的 CI/CD Pipeline 即可开始防御你的本地仓库。包含的安装程序会动态生成一个拦截你 Commit 的 Git Hook。
1. **将脚本 Clone 或复制到你的仓库根目录：**
确保 `secret_scanner.py` 和 `install_hook.py` 存在。
2. **运行 Hook 安装程序：**
*git add .*
*git commit -m "feat: added new S3 connection logic"*
### “快乐路径”（代码干净）
如果未检测到 Secret，Commit 将静默且正常地进行。
### “受阻路径”（检测到 Secret）
如果你意外暂存了高熵 API Token，扫描器将拦截 Commit 生命周期并中止操作：
*[+] Running Zero Point Secret Scanner...*
*--- Running Automated Verification Suite ---*
*[PASS] Entropy calculations are mathematically sound.*
*[PASS] Secret masking prevents local data leaks.*
*[PASS] AST Scanner accurately isolates high-entropy constants.*
*--- Verification Complete ---*
*[+] Starting Pre-Commit Secret Scan...*
*[!] Found 1 potential secrets. Report written to /path/to/secrets_report.md*
*[!] COMMIT REJECTED: Secrets detected. Review the markdown report.*
*[-] Commit aborted by Secret Scanner.*
打开生成的 `secrets_report.md` 以确切查看哪个文件和行号导致了违规，在代码中掩盖该 Secret，暂存更改，然后再次 Commit。
## 🧪 自动化验证 (Protocol 10)
该工具假定代码在 proven innocent 之前是有罪的。每次扫描器运行时，它首先执行一个内部测试套件，断言 Shannon Entropy 数学计算已正确校准，并且 AST Parser 成功隔离了常量。如果数学计算失败，扫描器会安全中止以保护你的 Pipeline。
## 📜 许可证与教育免责声明
这是一个教育工具，旨在演示 Static Application Security Testing (SAST) 的机制。对于企业级分布式扫描，请考虑将此逻辑整合到集中的 `.pre-commit-config.yaml` 框架中。
标签：API Token 扫描, AST 解析, DevSecOps, Git Hooks, Git 安全, meg, Pre-Commit, Python, Shannon Entropy, StruQ, 上游代理, 信息安全, 信息安全工具, 安全助手, 密码学, 手动系统调用, 指令劫持, 敏感数据检测, 无后门, 网络安全, 网络安全研究, 逆向工具, 错误基检测, 防泄露, 隐私保护, 静态代码分析, 高熵检测