arzaan789/keyguard

# keyguard 扫描代码库、GCP 项目和 CI 管道中暴露的 Google API 凭证 — 在它们被利用之前。 **问题：** Google 追溯性地在现有的 API 密钥（Maps、Places 等）上启用了 Gemini API 访问，这些密钥原本设计为公开的并嵌入在客户端代码中。当团队中的某人在同一个 GCP 项目中启用 Gemini 时，那些已经公开的密钥会静默地变成 Gemini 凭证 — 使您的项目面临未经授权的 AI 使用和超过 8 万美元的账单事件（[背景](https://news.ycombinator.com/item?id=47156925)）。 **keyguard 的功能：** - `keyguard scan` — 使用正则 + 熵检测在源文件和 git 历史中查找凭证字符串 - `keyguard audit` — 连接到实时 GCP 项目并标记当前具有 Gemini 访问权限的 API 密钥 - `keyguard ci` — 扫描 GitHub Actions、CircleCI 和 GitLab CI 日志和变量中泄露的凭证 ## 安装 ``` pip install keyguard-scan ``` 或者克隆并以开发模式安装： ``` git clone https://github.com/arzaan789/keyguard.git cd keyguard pip install -e ".[dev]" ``` ## 快速开始 ``` # 扫描当前目录和 git 历史 keyguard scan . # 审计您当前的 GCP 项目 keyguard audit # 扫描 CI 平台 keyguard ci ``` ## 命令 ### `keyguard scan` 使用正则 + Shannon 熵过滤扫描源文件和 git 历史中暴露的凭证。低熵占位符（如 `"REPLACE_ME"` 或 `"XXXXXXXX"`）会自动被忽略。 ``` # 扫描目录（文件 + 完整 git 历史） keyguard scan . # 仅文件，跳过 git 历史 keyguard scan . --no-git-history # 导出为 JSON 和 SARIF keyguard scan . --output json --output sarif --out-file report # 显示实际密钥值（未脱敏） keyguard scan . --no-redact # 使用自定义配置文件 keyguard scan . --config /path/to/.keyguard.toml ``` **退出码：** `0` = 无问题，`1` = 有发现，`2` = 错误 ### `keyguard audit` 通过 Cloud Resource Manager、Service Usage 和 API Keys API 连接到实时 GCP 项目。标记无限制的密钥（静默 Gemini 访问）或明确允许 `generativelanguage.googleapis.com` 且项目上已启用 Gemini 的密钥。 默认使用 [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials) 进行身份验证 — 先运行 `gcloud auth application-default login`。 ``` # 审计所有可访问的 GCP 项目 keyguard audit # 审计特定项目 keyguard audit --project my-project-id --project another-project # 使用服务账号密钥文件 keyguard audit --gcp-credentials /path/to/key.json # 导出 JSON 结果 keyguard audit --output json --out-file gcp-findings.json ``` **发现结果：** - `CRITICAL` — 密钥没有 API 限制 + 已启用 Gemini（静默 Maps→Gemini 升级场景） - `HIGH` — 密钥明确允许 `generativelanguage.googleapis.com`（故意的但可能嵌入在客户端代码中） ### `keyguard ci` 扫描 CI 平台日志和存储的变量中暴露的凭证。支持 GitHub Actions、CircleCI 和 GitLab CI。 ``` # 扫描所有已配置的平台 keyguard ci # 仅扫描一个平台 keyguard ci --platform github # 缩小到特定仓库 keyguard ci --repo my-org/api-service # 导出 JSON 结果 keyguard ci --output json --out-file ci-findings.json ``` **扫描内容：** - **GitHub Actions** — 明文仓库变量 + 工作流运行作业日志 - **CircleCI** — 环境变量名称（值被 CircleCI 屏蔽）+ 管道作业步骤日志 - **GitLab CI** — 项目变量（明文）+ 管道作业跟踪 ### `keyguard watch` 每次更改时重新扫描文件。开发过程中很有用。 ``` keyguard watch . ``` ### `keyguard rules list` 列出所有活动的检测规则。 ``` keyguard rules list ``` ### `keyguard config check` 验证 `.keyguard.toml` 配置文件。 ``` keyguard config check keyguard config check --config /path/to/.keyguard.toml ``` ## 配置 在项目根目录创建 `.keyguard.toml`： ``` [scan] paths = ["."] exclude = ["tests/fixtures/", "**/*.example"] scan_git_history = true [output] format = ["terminal", "json"] redact = true [notify] slack_webhook = "https://hooks.slack.com/services/..." [rules] disabled = [] # CI 平台认证和范围 [ci] github_token = "ghp_xxxxxxxxxxxxxxxxxxxx" circleci_token = "CCIPAT_xxxxxxxxxxxxxxxx" gitlab_token = "glpat-xxxxxxxxxxxxxxxxxxxx" gitlab_url = "https://gitlab.com" # override for self-hosted GitLab max_runs = 10 # recent runs/pipelines per repo [ci.github] orgs = ["my-org"] repos = ["my-org/specific-repo"] # optional: scan specific repos only [ci.circleci] orgs = ["my-org"] [ci.gitlab] groups = ["my-group"] ``` ## 检测 Keyguard 使用 **正则 + Shannon 熵** 方法。每个规则定义： - 匹配凭证结构的模式（例如，`AIza[0-9A-Za-z\-_]{35}` 用于 Google API 密钥） - 过滤低熵占位符的最小熵阈值 内置规则检测： | 规则 ID | 检测内容 | |---|---| | `google-api-key` | Google API 密钥（`AIza...`）— 包括静默获得 Gemini 访问权限的 Maps 密钥 | | `gcp-service-account-key` | GCP 服务账户 RSA 私钥 | | `google-oauth-client-secret` | Google OAuth2 客户端密钥（`GOCSPX-...`） | 您可以在 `.keyguard.toml` 中添加自定义规则： ``` [[rules.extra]] id = "my-internal-token" description = "Internal service token" pattern = "tok-[0-9a-f]{32}" entropy_min = 3.5 severity = "high" tags = ["internal"] ``` ## CI 集成 ### GitHub Actions ``` name: keyguard scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # full history for git scan - run: pip install keyguard-scan - run: keyguard scan . ``` ### Pre-commit 钩子 ``` # .pre-commit-config.yaml repos: - repo: local hooks: - id: keyguard name: keyguard credential scan entry: keyguard scan --no-git-history language: system pass_filenames: false ``` ### Docker ``` docker run --rm -v $(pwd):/repo ghcr.io/arzaan789/keyguard scan /repo ``` ## 输出格式 **终端**（默认）— 按严重性分组的彩色表格。 **JSON** — 机器可读的结果数组： ``` keyguard scan . --output json --out-file findings.json ``` **SARIF** — 与 GitHub 的 Security 选项卡和其他 SAST 工具集成： ``` keyguard scan . --output sarif --out-file findings.sarif ``` **Slack webhook** — 检测到结果时发布摘要： ``` [notify] slack_webhook = "https://hooks.slack.com/services/..." ``` ## 开发 ``` git clone https://github.com/arzaan789/keyguard.git cd keyguard pip install -e ".[dev]" pytest ``` **143 个测试，0 个失败。** 项目结构： ``` keyguard/ scanner/ # file + git history scanners engine/ # regex + entropy detection (rules, matcher) output/ # terminal, JSON/SARIF, webhook auditor/ # GCP API client + audit logic ci/ # GitHub Actions, CircleCI, GitLab CI scanners cli.py # Click CLI entry point config.py # .keyguard.toml loader ``` ## 路线图 - [x] v1 — 文件扫描器（源代码 + git 历史） - [x] v2 — GCP API 审计器（通过 GCP API 进行实时项目审计） - [x] v3 — CI 平台集成（GitHub Actions、CircleCI、GitLab CI） ## 许可证 MIT

标签：AMSI绕过, API密钥安全, CI/CD安全, DevSecOps, GCP安全, Gemini API, JSON导出, Llama, Pre-commit钩子, SARIF报告, StruQ, USENIX Security 2025, 上游代理, 云安全监控, 代码安全审计, 凭证扫描, 凭证泄露, 多平台, 威胁检测, 安全助手, 密钥Guard, 密钥保护, 密钥轮换, 对抗攻击, 敏感信息检测, 正则匹配, 泄露检测, 熵检测, 谷歌云平台, 逆向工具, 静态分析