keyguard

코드베이스, GCP 프로젝트, CI 파이프라인에서 노출된 Google API 자격 증명을 악용되기 전에 스캔하세요.

문제: Google은 클라이언트 측 코드에 포함되도록 설계된 기존 API 키(Maps, Places 등)에 대해 Gemini API 액세스를 소급하여 활성화했습니다. 팀원이 동일한 GCP 프로젝트에서 Gemini를 활성화하면, 이미 공개된 키가 조용히 Gemini 자격 증명이 되어 프로젝트가 승인되지 않은 AI 사용 및 $80,000 이상의 청구 사고에 노출됩니다 (컨텍스트).

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 액세스) Gemini가 프로젝트에서 활성화된 상태에서 generativelanguage.googleapis.com을 명시적으로 허용하는 키를 플래그합니다.

인증은 기본적으로 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"   # 자체 호스팅 GitLab의 경우 재정의
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 웹훅 — 발견 사항이 감지되면 요약을 게시:

[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, 웹훅
  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`