duriantaco/hush2

# hush2 `hush2` 是为终端用户开发者设计的本地、安全的密钥运行工具。 它将密钥存储在 AES-256-GCM 加密的 SQLite 保险库中，作为环境变量注入到子进程中，默认情况下屏蔽密钥值，并在旧版保险库数据损坏时提供恢复工具。 最直接的用例是：运行部署脚本、迁移、测试框架或由代理编写的命令时，仅注入所需密钥，而无需将值粘贴到提示符、shell 历史记录或明文 `.env` 文件中。 ## 为何使用 hush2 - 将 API 密钥、数据库 URL 和令牌排除在提示符、shell 历史记录和明文 `.env` 文件之外。 - 在运行时提供密钥以运行代理编写的命令，而不是将值粘贴到聊天中。 - 使用 `hush2 NAME -- cmd` 仅注入请求的密钥，或使用 `hush2 run` 注入当前活动的保险库。 - 默认屏蔽子进程输出中的密钥值。 - 扫描代码库以发现保险库中的真实密钥泄露。 - 使用 `hush2 doctor` 从旧版混合密钥损坏中恢复。 ## 最佳适用场景 - 主要在终端中工作的独立开发者和小型团队。 - AI 辅助或代理驱动的工作流，其中命令执行频繁但密钥处理存在风险。 - 希望获得明确密钥来源和可审计性的本地开发环境。 `hush2` 不是托管的团队密钥平台。它是一个本地开发者工具，专注于在单机上实现安全运行时注入、屏蔽、扫描和恢复。 ## 功能特性 - 每个项目独立的加密保险库：`.hush2/envs//vault.db` - 可选的全球保险库：`~/.hush2/envs//vault.db` - 静态存储使用 AES-256-GCM 加密 - 使用 PBKDF2-HMAC-SHA256 进行密钥派生，每个保险库使用独立盐值 - 在可用时通过操作系统钥匙串进行密码查找 - `HUSH2_PASSWORD` 作为 CI、无头 Shell 或无钥匙链支持设备的备用方案 - 将密钥注入子进程并屏蔽标准输出/标准错误 - 密钥历史记录与回滚 - 密钥标签与标签过滤执行 - 导入与导出 `.env` 文件 - 密钥生成 - 审计日志 - 精确值密钥扫描并可选熵检测 - 备份、恢复与保险库修复诊断 ## 安装 从本地代码库安装： ``` pipx install . ``` 或使用 `uv`： ``` uv tool install . ``` 或使用纯 `pip`： ``` python -m pip install . ``` 开发模式安装： ``` python -m pip install -e '.[dev]' ``` ## 快速开始 核心工作流程如下： 1. 为当前项目创建保险库。 2. 保存命令实际需要的密钥。 3. 通过 `hush2` 运行命令。 在当前项目中创建保险库： ``` hush2 init ``` 添加密钥： ``` hush2 set OPENAI_API_KEY sk-live-abc123 hush2 set DATABASE_URL postgres://user:pass@host/db --tag db --tag prod ``` 读取或列出密钥： ``` hush2 get OPENAI_API_KEY hush2 list hush2 list --tag prod ``` 运行并注入密钥的命令： ``` hush2 run ./deploy.sh hush2 OPENAI_API_KEY DATABASE_URL -- python app.py ``` 对于代理编写的命令，优先使用显式模式： ``` hush2 OPENAI_API_KEY -- python agent_task.py ``` 这样可以保持密钥选择范围狭窄，并使来源在审计日志中清晰可查。 检查保险库健康状态： ``` hush2 doctor ``` ## 信任清单 在依赖 `hush2` 之前，请完成以下操作一次： ``` hush2 doctor hush2 scan --staged hush2 backup ``` - `doctor` 确认保险库可读且认证元数据健康。 - `scan --staged` 检查暂存更改是否存在精确密钥泄露。 - `backup` 在进行大型迁移或导入前提供可恢复的备份。 ## hush2 工作原理 1. `hush2 init` 在 `.hush2/envs/default/` 创建本地保险库（除非传入 `--env` 或 `--global`）。 2. `hush2 set` 加密密钥值并存储到 SQLite。 3. `hush2 run` 或 `hush2 NAME -- command` 仅解密子进程所需的密钥。 4. 子进程输出默认被屏蔽，除非使用 `--no-mask` 显式关闭。 5. 命名密钥请求在 exec 模式下默认仅从保险库解析，除非显式传入 `--allow-env-fallback`。 6. `hush2 doctor` 可诊断不可读记录并修复可恢复的旧版损坏。 使 `hush2` 区别于其他工具的组合是：本地加密存储、显式运行时注入、默认屏蔽以及精确值泄露扫描。 ## 常用命令 | 命令 | 描述 | |------|------| | `init` | 在当前项目或全局创建新保险库 | | `set NAME [VALUE]` | 存储或更新密钥 | | `get NAME` | 打印密钥值 | | `list` | 列出密钥 | | `list envs` | 列出可用环境 | | `rm NAME [NAME...]` | 删除密钥 | | `run CMD...` | 运行命令并注入所有保险库密钥 | | `NAME [NAME...] -- CMD` | 仅注入特定密钥 | | `--allow-env-fallback NAME -- CMD` | 显式允许缺失名称从父环境获取 | | `import FILE` | 从文件导入 `.env` 值 | | `import --stdin` | 从标准输入导入 `.env` 值 | | `import --from-env` | 从当前环境导入匹配值 | | `export` | 以 `.env` 格式导出密钥 | | `tag NAME TAG...` | 为密钥添加标签 | | `untag NAME TAG...` | 移除密钥标签 | | `history NAME` | 显示密钥的历史版本 | | `rollback NAME --to N` | 恢复到旧版本 | | `generate` | 生成密码、令牌、密钥或 UUID | | `audit` | 显示审计日志 | | `scan` | 扫描文件以查找精确密钥泄露和可选高熵值 | | `backup [FILE]` | 写入保险库备份文件 | | `restore FILE` | 从备份恢复保险库 | | `doctor` | 诊断保险库健康 | | `doctor --repair` | 修复可恢复的旧版损坏 | | `completion bash|zsh|fish` | 输出 Shell 补全脚本 | ## 运行带密钥的命令 注入保险库中的所有密钥： ``` hush2 run ./deploy.sh ``` 仅注入命名密钥： ``` hush2 OPENAI_API_KEY DATABASE_URL -- python app.py ``` 在 `NAME -- CMD` 模式下解析的名称默认来自活动保险库。如果请求的名称缺失，`hush2` 会失败，而不是静默回退到父 Shell 环境。 按标签注入密钥： ``` hush2 --tag prod -- ./deploy.sh hush2 run --tag db -- python migrate.py ``` 如果明确希望某个名称来自父环境，可显式启用： ``` export TEMP_TOKEN=abc123 hush2 --allow-env-fallback TEMP_TOKEN -- python script.py ``` ### 输出屏蔽 屏蔽功能在 `run` 和 `NAME -- CMD` exec 模式下默认启用。 ``` hush2 run sh -c 'echo $OPENAI_API_KEY' # [REDACTED] hush2 run --mask-style partial sh -c 'echo $OPENAI_API_KEY' # sk...23 hush2 run --mask-style hash sh -c 'echo $OPENAI_API_KEY' # [sha:a2c62cb9] hush2 run --no-mask sh -c 'echo $OPENAI_API_KEY' # prints the real value ``` 仅在明确希望子进程输出包含真实密钥时使用 `--no-mask`。 ## 环境与保险库作用域 创建环境专属保险库： ``` hush2 init --env staging hush2 --env staging set API_KEY value hush2 --env staging run ./deploy.sh ``` 创建全局保险库： ``` hush2 init --global hush2 --global set SHARED_TOKEN value ``` 本地保险库查找会从当前工作目录向上遍历，直到找到 `.hush2/` 目录，使嵌套项目命令按预期工作。 ## 导入与导出 从 `.env` 文件导入： ``` hush2 import .env ``` 从标准输入导入： ``` cat .env | hush2 import --stdin ``` 从当前 Shell 环境导入： ``` hush2 import --from-env --pattern '^(OPENAI|STRIPE|AWS_)' ``` 以 `.env` 格式导出： ``` hush2 export hush2 export --env-file .env.secure hush2 export --tag prod ``` 这使得迁移更灵活：你可以采用 `hush2` 而不锁定到专有格式，也可以在进行较大更改前保留备份。 ## 密钥历史、回滚与标签 更新密钥时会记录版本历史： ``` hush2 history OPENAI_API_KEY hush2 rollback OPENAI_API_KEY --to 1 ``` 标签可用于组织执行和列出密钥： ``` hush2 set STRIPE_KEY sk-live-abc --tag payments --tag prod hush2 tag DATABASE_URL db prod hush2 list --tag prod hush2 --tag prod -- ./deploy.sh ``` ## 密钥生成 ``` hush2 generate --type password --length 32 hush2 generate --type token --encoding hex --length 32 hush2 generate --type key hush2 generate --type uuid hush2 generate --type password --save SESSION_SECRET --tag app ``` ## 扫描泄露 `hush2 scan` 检查文件以查找来自保险库的实时密钥值，避免基于正则表达式的误报。 ``` hush2 scan hush2 scan --path ./src hush2 scan --staged hush2 scan --entropy --threshold 4.5 ``` 如果发现泄露，`scan` 会以非零状态退出。 ## 备份、恢复与修复 创建备份： ``` hush2 backup hush2 backup my-vault.bak ``` 恢复备份： ``` hush2 restore my-vault.bak hush2 restore my-vault.bak --env staging ``` 诊断并修复旧版损坏： ``` hush2 doctor hush2 doctor --repair hush2 doctor --repair --force ``` 修复行为： - 如果当前密钥不可读但存在旧版本仍可解密，`doctor --repair` 会恢复最新可读的历史记录。 - 如果不可读记录无可替换版本，`doctor --repair --force` 可将其移除。 - 如果钥匙串不可用，恢复或新建保险库可能需要 `HUSH2_PASSWORD` 才能解锁。 ## CI 与无头环境 如果操作系统钥匙串不可用或需要确定性非交互式解锁，可设置 `HUSH2_PASSWORD`： ``` export HUSH2_PASSWORD=my-vault-password hush2 run ./ci-script.sh ``` 这是当前代码库的行为，在 `keyring` 无法存储或检索保险库密码的系统上需要此设置。 ## 集成到工作流 在评估 `hush2` 时，建议从一个具体流程开始，而不是一次性迁移所有密钥： 1. 选择一个已在本地运行的命令，例如部署、迁移或集成测试脚本。 2. 仅将该命令所需的密钥迁移到 `hush2`。 3. 先使用 `hush2 NAME -- cmd` 运行，再根据需要扩展为 `hush2 run` 以实现全保险库注入。 4. 将 `hush2 scan --staged` 添加到预提交或发布流程中。 5. 在批量导入、环境迁移或恢复操作前保留最新的 `hush2 backup`。 ## 安全注意事项 - 密钥在静态存储中使用 AES-256-GCM 加密。 - 密钥通过 PBKDF2-HMAC-SHA256 与每个保险库的盐值派生。 - 密钥值仅在命令需要时解密。 - `HUSH2_PASSWORD` 在命令执行前从子进程环境中移除。 - `get`、`export` 和 `run --no-mask` 在被请求时有意暴露值。 - `NAME -- CMD` 模式下默认仅从保险库解析名称，确保来源明确且可审计。 - 恢复工具可抢救可读的旧版数据，但无法重建真正不可读的密钥。 - `hush2` 可减少本地工作流中的意外泄露，但不隔离已授予密钥的子进程。 ## 项目文档 - 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解本地设置、测试期望和版本策略。 - 参见 [SECURITY.md](SECURITY.md) 了解支持的上报流程和当前安全边界。 - 参见 [CHANGELOG.md](CHANGELOG.md) 了解初始基线和未来发布说明。

标签：AES-256-GCM, CI友好, HMAC-SHA256, OS钥匙串, PBKDF2, SQLite, 威胁情报, 子进程安全, 密钥回滚, 密钥恢复, 开发安全, 开发者工具, 本地加密存储, 机密安全, 机密审计, 机密扫描, 标签过滤, 环境变量注入, 环境隔离, 终端工具, 逆向工具, 防泄露, 项目级加密