Credactor

비밀을 찾아라. 고쳐라. 깨끗하게 커밋하라.

대부분의 시크릿 스캐너는 경고에서 멈춥니다. 유출된 자격 증명 목록을 받고 정리는 여러분 몫입니다. Credactor는 하드코딩된 시크릿을 찾아 제자리에서 다시 작성하므로, 작업 트리의 유출이 한 번의 명령으로 발견에서 수정까지 이어집니다. 로컬 머신에서, pre-commit 훅으로, 또는 CI 게이트로 실행되며, Gitleaks, TruffleHog, Betterleaks가 찾은 것도 수정할 수 있습니다.

# Before
db_password = "h8Tq2vKp9mRz4Wd"

# credactor --fix-all .   (default: a sentinel that fails loudly at runtime)
db_password = "REDACTED_BY_CREDACTOR"

# credactor --replace-with env --fix-all .   (read it from the environment)
db_password = os.environ["DB_PASSWORD"]

리대션은 작업 트리를 정리합니다. 자격 증명을 폐기하지 않으며 git 기록을 건드리지도 않습니다. 비밀이 한 번이라도 커밋되었거나 공유되었다면 이를 교체하고, 해당 기록에서도 완전히 제거해야 한다면 기록을 다시 작성하세요 (예: git filter-repo 사용).

Credactor를 사용하는 이유

단순히 표시하는 것이 아니라 수정합니다. 각 발견 항목은 해당 파일의 언어에 맞게 센티널, 사용자 지정 마커 또는 환경 변수 조회로 제자리에서 대체됩니다.
신중한 쓰기. 각 편집은 메모리에서 계획되고, 먼저 백업된 후(모드 0600), 임시 파일에 기록되어 제자리로 이름이 변경됩니다. 실행 중에 변경된 파일, 스캔 루트를 벗어나는 경로 또는 개인 키 블록은 경고와 함께 건너뛰며, 해당 발견 항목은 계속 보고됩니다.
이미 실행 중인 스캐너와 함께 작동합니다. Gitleaks, TruffleHog 또는 Betterleaks 보고서를 제공하면 중복 제거된 한 번의 패스로 해당 발견 항목과 자체 발견 항목을 모두 수정합니다.
파이프라인을 위해 설계되었습니다. 명확한 종료 코드를 가진 읽기 전용 --ci 게이트, GitHub Code Scanning용 줄 및 열 위치가 포함된 SARIF 2.1.0, GitHub Action 및 pre-commit 훅. 모든 보고서 형식에서 비밀이 마스킹되며, 텍스트 출력이 정리되어 스캔된 파일이 터미널이나 로그에 이스케이프 시퀀스나 CI 워크플로 명령을 주입할 수 없습니다.
릴리스는 소스와 대조하여 검증됩니다. 런타임 종속성이 없는 순수 Python 3.11+ 표준 라이브러리입니다. 릴리스가 PyPI에 도달하기 전에 wheel 및 sdist의 모든 Credactor 파일이 태그된 소스와 바이트 단위로 비교되며, 패키지 메타데이터는 pyproject.toml과 일치해야 합니다(공급망 강화 참조).

단독으로 사용하기에 적합하지 않은 경우: 내장 규칙은 수백 개의 공급자가 아닌 가장 자주 유출되는 자격 증명 형식을 다루며, 비밀이 활성 상태인지 확인하지 않습니다. 깨끗한 실행은 규칙에 일치하는 항목이 없었다는 의미일 뿐, 코드에 비밀이 없다는 의미는 아닙니다. 폭넓은 범위를 위해 전용 스캐너와 함께 사용하세요(자체 스캐너 가져오기 참조).

설치

pip install credactor

uv를 사용하여 도구로 설치하거나, 설치하지 않고 한 번만 실행할 수 있습니다:

uv tool install credactor
uvx credactor --dry-run .

또는 macOS와 Linux에서 Homebrew를 사용하는 경우:

brew install rxb06/tap/credactor

Python 3.11 이상이 필요합니다. Linux 및 Windows의 CI에서 Python 3.11부터 3.13까지 테스트되었습니다. UTF-8, Latin-1 또는 단순 UTF-16 이외의 인코딩 파일의 경우 선택적 추가 기능을 설치하세요: pip install 'credactor[encoding]' 또는 uv tool install 'credactor[encoding]' (Homebrew formula에 포함되어 있음).

빠른 시작

1. 발견 항목 확인. 아무것도 변경되지 않습니다.

credactor --dry-run .

======================================================================
  CREDENTIAL SCAN REPORT  --  2 finding(s) in 1 file(s)
======================================================================

  FILE: config.py
  ────────────────────────────────────────────────────────────
  Line    3  [HIGH]  [variable:db_password]
           db_password = "h8Tq[REDACTED]"
  Line    4  [CRITICAL]  [pattern:AWS access key]
           aws_key = "AKIA[REDACTED]"

보고서에는 각 시크릿의 처음 네 문자만 표시됩니다.

2. 수정하기. 먼저 발견 사항을 검토하세요. --fix-all은 오탐을 포함한 모든 항목을 다시 작성합니다. 하나를 유지하려면 해당 줄에 # credactor:ignore를 추가하거나(오탐 억제 참조) 대화형으로 수정하면서 n으로 답하세요. 각 파일이 변경되기 전에 실행 취소할 수 있도록 해당 파일 옆에 .bak 사본이 작성됩니다.

credactor .                          # ask y/N for each finding (needs a terminal)
credactor --fix-all .                # fix all after one confirmation
credactor --fix-all --yes .          # fix all, no prompt (scripts)
credactor --replace-with env --fix-all .   # environment lookups instead of the sentinel

Env 모드는 import가 아니라 조회를 기록합니다: 파일에 해당 구문이 없으면 import os 또는 해당 언어의 동등한 구문을 추가하세요. Windows Git Bash에서는 대화형 모드를 winpty credactor .로 실행하세요.

3. 확인한 후 백업을 정리하세요. 각 .bak 파일에는 여전히 원본 시크릿이 들어 있고, Credactor는 .gitignore를 절대 수정하지 않으므로 단순한 git add . 명령은 이를 스테이징하게 됩니다.

diff config.py.bak config.py         # check what changed
cp config.py.bak config.py           # undo

.gitignore에 *.bak와 *.credactor.tmp를 추가하고, 만족스러우면 백업을 삭제하세요. 처음부터 백업이 트리에 남지 않도록 하려면 fix 실행 시 --secure-backup-dir DIR(저장소 외부의 디렉터리)을 전달하세요. --secure-delete는 대신 각 백업을 완전히 지우므로, git만이 유일한 되돌리기 수단으로 남습니다.

명령어 한눈에 보기

명령어	수행 작업	파일 변경 여부
`credactor --dry-run .`	발견 사항 보고	아니요
`credactor .`	한 번에 하나씩 발견 사항 검토 및 수정	`y` 입력 시 예
`credactor --fix-all .`	한 번의 확인 후 모든 발견 사항 수정	예
`credactor --ci .`	게이트: 발견 사항이 있으면 종료 코드 1	절대 안 함
`credactor --staged --ci .`	커밋을 위해 스테이징된 항목만 게이트	절대 안 함
`credactor --scan-history .`	파일을 변경한 최근 100개 커밋 스캔	절대 안 함
`credactor --ci -f sarif . > results.sarif`	Code Scanning용 SARIF 2.1.0	절대 안 함
`credactor --ci -f json . > findings.json`	기계 판독 가능한 보고서	절대 안 함

모든 플래그와 조합은 매뉴얼에 있습니다.

pre-commit 및 CI에서 사용하기

Pre-commit 훅

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.7.5
    hooks:
      - id: credactor

pre-commit install

이후 모든 git commit은 스테이징된 콘텐츠를 스캔하며, 자격 증명이 포함되어 있으면 차단됩니다. 이 훅은 파일을 절대 다시 작성하지 않습니다. pre-commit 3.2.0 이상이 필요하며, 프레임워크가 없는 경우 독립 실행형 훅을 참조하세요.

GitHub Action

steps:
  - uses: actions/checkout@v7
  - uses: rxb06/[email protected]

The Action은 항상 --ci로 실행되므로 체크아웃을 절대 다시 쓰지 않습니다. 발견 사항은 단계를 실패시키며, 어떤 오류든 마찬가지입니다. 실패하는 대신 Code Scanning에 보고하려면:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v7
  - uses: rxb06/[email protected]
    with:
      format: sarif
      upload-sarif: true
      fail-on-findings: false

CI 통합 가이드는 모든 Action 입력과 출력을 나열하며 GitLab CI와 일반 셸 단계를 다룹니다.

자체 스캐너 사용하기

이미 Gitleaks, TruffleHog 또는 Betterleaks를 실행하고 계신가요? Credactor에 보고서를 넘기면 자체 발견 사항과 함께 중복 제거된 상태로 수정합니다(중복인 경우 더 높은 심각도가 유지됨). 네이티브 스캔과 마찬가지로 먼저 --dry-run으로 미리 확인하세요.

gitleaks dir . -f json -r gl.json
credactor --from-gitleaks gl.json --fix-all --yes .

trufflehog filesystem . --no-verification --json > th.json
credactor --from-trufflehog th.json --fix-all --yes .

betterleaks dir . -f json -r bl.json
credactor --from-betterleaks bl.json --fix-all --yes .

Credactor를 스캐너가 실행된 동일한 디렉터리로 지정하고, 트리가 변경된 후에 보고서를 다시 생성하세요. 보고서는 발견한 모든 시크릿을 평문으로 보관하며 그 자체는 스캔되지 않으므로(.json은 --scan-json 필요), 저장소 외부에 작성하거나 실행 후 삭제하세요. Credactor가 안전하게 배치할 수 없는 발견 항목(유효한 줄 번호 없음, .git 하위 경로, 단독으로 매칭하기에 너무 짧은 값)은 보고된 상태로 남으며 절대 기록되지 않습니다. 세부 사항과 지원 버전은 Manual에 있습니다.

탐지 항목

카테고리	예시	심각도
클라우드 및 SaaS 키	AWS (`AKIA…`, `ASIA…`), GCP (`AIza…`), Stripe 라이브 (`sk_live_…`, `rk_live_…`), Slack (`xoxb-…`, `xoxp-…`)	Critical
플랫폼 토큰	GitHub (`ghp_`, `gho_`, `ghs_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`)	Critical
개인 키	PEM 블록 (`-----BEGIN … PRIVATE KEY-----`, 암호화된 것 포함), PGP 개인 키 블록	Critical
JWT	`eyJ…` 3세그먼트 토큰	High
연결 문자열	인라인 자격 증명이 포함된 URL (`scheme://user:pass@host`)	High
자격 증명 변수	`password = "…"`, `api_key = "…"`, `secret_key = "…"`	High, Medium 또는 Low
XML 속성	`<add key="Password" value="…" />`	High, Medium 또는 Low
Stripe 테스트 키	`sk_test_…`	Medium
고엔트로피 문자열	따옴표로 묶인 hex(32~64자) 또는 Base64(60자 이상)	Medium 또는 Low