# 版本 1.0.0

Custodes

一个极简的 CLI 工具，帮助您避免将密钥提交到 Git 仓库中。

🌐 项目主页 · GitHub repository

## 这个程序是什么？ **Custodes** 是一款面向开发者的轻量级本地安全工具。 Custodes 的主要任务是在提交前检查暂存区（staged）的更改，如果发现潜在的密钥（如 API 密钥、token、密码、私钥或配置中的其他禁止字符串），则阻止 commit。 Custodes 并不旨在替代 Gitleaks 或 TruffleHog 等专业工具。它是一个具有教育意义且可扩展的 pet-project，只专注于完成一个特定任务：**防止意外将密钥提交到仓库中**。 ## 它是如何工作的？ 安装后，Custodes 会在 Git 仓库中创建一个 `pre-commit` hook。 工作流程如下： ``` git commit ↓ .git/hooks/pre-commit ↓ custodes check ↓ сканирование staged-файлов ↓ секрет найден → commit блокируется секретов нет → commit проходит ``` Custodes 仅检查 **staged changes**，即通过以下命令添加的更改： ``` git add ``` ## 功能 目前，Custodes 能够： - 在当前的 Git 仓库中安装 `pre-commit` hook； - 在 commit 之前检查 staged 文件； - 搜索 `.env` 中配置的禁止词和模式； - 通过 exit code `1` 阻止 commit； - 输出发现违规行为的文件和行列表； - 显示已安装版本的状态； - 打开配置文件进行编辑； - 从系统中卸载 Custodes； - 从项目仓库进行更新。 ## 安装 克隆仓库： ``` git clone https://github.com/No1se-pi/Custodes.git cd Custodes ``` 运行安装程序： ``` bash installer.sh ``` 安装完成后，检查命令是否可用： ``` custodes help ``` 如果未找到命令，请检查 `PATH` 环境变量中是否包含 `~/.local/bin`。 ## 快速开始 进入目标 Git 仓库： ``` cd my-project ``` 安装 hook： ``` custodes init ``` 现在，在执行常规 commit 时，Custodes 将自动运行： ``` git add . git commit -m "test commit" ``` 如果在 staged 更改中检测到密钥，commit 将被阻止。 ## 命令 ``` custodes help ``` 显示帮助信息。 ``` custodes init ``` 在当前的 Git 仓库中安装 `pre-commit` hook。 ``` custodes check ``` 手动检查 staged 文件中是否存在密钥。 ``` custodes status ``` 检查当前已安装的 Custodes 版本以及是否有更新。 ``` custodes update ``` 从 GitHub 仓库更新 Custodes 文件。 ``` custodes config ``` 打开配置文件 `.env`。 ``` custodes uninstall ``` 从系统中卸载 Custodes。 ``` custodes about ``` 显示项目信息。 ## `.env` 示例 ### 为什么需要 `.env`？ `.env` 用于存储 Custodes 的设置： - 禁止词列表； - 被阻止时是否显示 logo； - 是否输出具体的违规行； - 提示信息的语言。 ### 填写示例 ``` banwords=SSH_KEY,API_KEY,password,hash logo_custodes=yes # values: yes; any other value means no output_violations=yes # values: yes; any other value means no lang_custodes=ru # values: eng, ru ``` ### 可用参数 #### `banwords` 以逗号分隔的禁止词列表。 示例： ``` banwords=SSH_KEY,API_KEY,password,token ``` 如果在新增的行中发现这些值之一，commit 将被阻止。 #### `logo_custodes` 启用或禁用在阻止 commit 时显示 ASCII logo。 ``` logo_custodes=yes ``` 除 `yes` 之外的任何值都将被视为禁用。 #### `output_violations` 控制是否输出发现违规的具体行。 ``` output_violations=yes ``` 除 `yes` 之外的任何值都将被视为禁用。 #### `lang_custodes` Custodes 的提示信息语言。 ``` lang_custodes=ru ``` 可用值： ``` ru — русский язык eng — английский язык ``` ## 阻止提交示例 假设在文件中添加了以下行： ``` API_KEY=12345 ``` 在执行以下命令后： ``` git add . git commit -m "add config" ``` Custodes 会找到禁止词 `API_KEY` 并阻止 commit。 ## 重要限制 Custodes 是一种基于 Git hook 的本地防护机制，因此存在以下限制： - `git commit --no-verify` 可以绕过 `pre-commit` hook； - 该工具目前无法替代专业的 secret-scanner 解决方案； - 当前版本主要针对 Linux 系统； - 目前的搜索规则较为简单，主要基于 `banwords` 列表； - 可能会出现误报。 ## 路线图 计划改进的功能： - 更精确地处理 Git diff； - 输出行号； - 针对密钥、私钥和 API 密钥的 regex 规则； - 针对随机密钥的 entropy detection； - 针对文件和值的 allowlist； - 更完善的 update/uninstall 流程； - Windows 版本； - 打包为单一可执行文件。 ## 作者 项目作者：**Yaroslav Boikov / No1se**。 GitHub: 网站: ## 免责声明 Custodes 是作为一个 pet-project 和学习工具创建的，旨在练习 Git、Bash、Python 以及 DevSecOps 实践。 请谨慎使用，并在将其应用于重要仓库之前仔细检查配置。

标签：Git钩子, StruQ, 应用安全, 开发安全, 本地AI, 逆向工具