keyguard

扫描代码库、GCP 项目和 CI 流水线中暴露的 Google API 凭据——在它们被利用之前。

问题： Google 在已有的 API 密钥（Maps、Places 等）上回溯启用了 Gemini API 访问，这些密钥本来设计为公开并嵌入客户端代码。当团队中有人在同一个 GCP 项目中启用 Gemini 时，那些本已公开的密钥会悄悄变成 Gemini 凭据——导致项目面临未经授权的 AI 使用风险，并可能产生超过 8 万美元的账单事故（背景）。

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 在项目中已启用的密钥。

认证默认使用应用默认凭据——请先运行 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

发现等级：

严重 —— 密钥没有 API 限制 + Gemini 已启用（静默的 Maps → Gemini 升级场景）
高 —— 密钥明确允许 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"   # 覆盖自托管 GitLab URL
max_runs        = 10                     # 每个仓库的最近运行/流水线数

[ci.github]
orgs  = ["my-org"]
repos = ["my-org/specific-repo"]         # 可选：仅扫描特定仓库

[ci.circleci]
orgs = ["my-org"]

[ci.gitlab]
groups = ["my-group"]

检测

Keyguard 使用 正则表达式 + Shannon 熵 方法。每条规则定义：

匹配凭据结构的模式（例如 Google API 密钥的 AIza[0-9A-Za-z\-_]{35}）
一个最小熵阈值，用于过滤掉低熵占位符

内置规则检测：

规则 ID	检测内容
`google-api-key`	Google API 密钥（`AIza...`）——包括被静默授予 Gemini 访问权限的 Maps 密钥
`gcp-service-account-key`	GCP 服务账号 RSA 私钥

你可以在 .keyguard.toml 中添加自定义规则：

[[rules.extra]]
id = "my-internal-token"
description = "内部服务令牌"
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          # 获取完整历史以支持 Git 扫描
      - 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 安全标签页及其他 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/      # 文件 + Git 历史扫描器
  engine/       # 正则 + 熵检测（规则、匹配器）
  output/       # 终端、JSON/SARIF、Webhook
  auditor/      # GCP API 客户端 + 审计逻辑
  ci/           # GitHub Actions、CircleCI、GitLab CI 扫描器
  cli.py        # Click CLI 入口点
  config.py     # .keyguard.toml 加载器

路线图

v1 —— 文件扫描器（源代码 + Git 历史）
v2 —— GCP API 审计器（通过 GCP API 对运行中的项目进行审计）
v3 —— CI 平台集成（GitHub Actions、CircleCI、GitLab CI）

许可证

MIT

keyguard

最受欢迎

keyguard

安装

快速开始

命令

keyguard scan

keyguard audit

keyguard ci

keyguard watch

keyguard rules list

keyguard config check

配置

检测

CI 集成

GitHub Actions

Pre-commit 钩子

Docker

输出格式

开发

路线图

许可证

`keyguard scan`

`keyguard audit`

`keyguard ci`

`keyguard watch`

`keyguard rules list`

`keyguard config check`