Credactor

비밀을 찾고, 수정하고, 깨끗하게 커밋하세요.

시크릿 스캐너는 경보를 울리는 데는 능숙하지만, 불을 끄는 데는 별로 도움이 되지 않습니다. 유출된 자격 증명 목록을 건네주고 정리는 사용자의 몫으로 남겨 둡니다. Credactor는 이 루프를 닫아 줍니다. 하드코딩된 비밀을 찾아 그 자리에서 다시 작성하므로, 유출이 감지부터 수정까지 단일 명령으로 처리됩니다.

소스 코드에 자격 증명을 넣지 않는 것은 선택이 아닌 기본 보안 관행입니다. Credactor는 커밋 전에 사용자의 머신에서, 또는 병합 전에 CI에서 그 기본을 저렴하게 유지할 수 있게 해 줍니다. 단독으로 실행하거나, 이미 신뢰하는 스캐너와 함께 실행하세요.

# Credactor finds this:
db_password = "h8Tq2vKp9mRz4Wd"

# By default it rewrites the secret as a sentinel that fails loudly at runtime:
db_password = "REDACTED_BY_CREDACTOR"

# With --replace-with env, it writes a reference that reads from the environment:
db_password = os.environ["DB_PASSWORD"]

Redaction(재작성)은 작업 트리의 파일을 다시 씁니다. 비밀이 이미 커밋된 경우 키를 교체하고 이력도 정리하세요(예: git filter-repo 사용). 파일을 다시 쓰는 것은 유출된 자격 증명을 해지하는 것을 대신하지 못합니다.

왜 Credactor인가?

• 탐지만이 아니라 재작성(Redaction)입니다. 대부분의 스캐너는 발견 단계에서 멈춥니다. Credactor는 비밀을 그 자리에서 교체합니다. 기본적으로 런타임에 실패하도록 하는 명확한 REDACTED_BY_CREDACTOR 센티널이거나, 언어를 인식하는 환경 변수 참조(Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP 및 shell) 예: os.environ["KEY"]로 교체합니다. 교체 결과는 유효한 코드입니다. 파일에 해당 import(예: import os)가 이미 포함되어 있지 않으면 추가하세요.
• 기본적으로 안전합니다. 원자적 쓰기, 자동 .bak 백업, 심링크 경계 및 파일 권한 가드, 모든 출력에서 비밀 전체 마스킹을 제공합니다. 안전한 백업을 쓸 수 없으면 Credactor는 무작정 다시 쓰는 대신 파일을 건너뛰며, 쓰기 도중 크래시가 발생해도 원본은 그대로 유지됩니다.
• 런타임 의존성 제로. 순수 Python 3.11+ 표준 라이브러리만 사용하며, 비-UTF-8 인코딩을 위한 선택적 추가 기능이 있습니다.
• 파이프라인에 맞게 설계되었습니다. GitHub Code Scanning용 SARIF 출력, 정확한 종료 코드를 제공하는 읽기 전용 --ci 게이트, pre-commit 훅(베타), Gitleaks 또는 TruffleHog 리포트 수집(BETA, 더 많은 기능 준비 중)을 지원합니다. Gitleaks나 TruffleHog로 탐지하고, Credactor로 수정하세요.

설치

pip install credactor

Python 3.11+가 필요합니다. 다른 의존성은 없습니다. Linux, macOS, Windows에서 실행됩니다(CI는 Linux 및 Windows에서 테스트됨).

소스에서 설치:

git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .

그러면 어떤 디렉터리에서도 credactor를 사용할 수 있습니다.

빠른 시작

재작성 전에 먼저 --dry-run을 실행하고 결과를 검토하세요. 오탐(false positive)이 발생할 수 있으며, --fix-all에서는 오탐도 다시 작성됩니다. 알려진 안전한 값은 # credactor:ignore 또는 .credactorignore 항목으로 제외하세요.

credactor --dry-run .                 # scan, change nothing
credactor .                           # scan, then redact interactively (y/n per finding)
credactor --fix-all .                 # redact everything after one confirmation
credactor --fix-all --yes .           # redact non-interactively (CI / scripts)
credactor --ci .                      # read-only gate: exit 1 on findings
credactor --replace-with env .        # redact to env-var references instead of the sentinel

Pre-commit 훅 (베타)

훅 통합은 베타입니다. 이 기능만으로 의존하기 전에 수동으로 credactor --dry-run .을 실행하세요.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.5.0   # pin to the latest release tag
    hooks:
      - id: credactor

탐지

Credactor는 가장 자주 유출되는 자격 증명 유형을 탐지하고, 각각에 심각도를 부여하여 한눈에 분류할 수 있게 합니다.

결정적 공급자 토큰(위 접두사)은 엔트로피와 관계없이 플래그됩니다. 휴리스틱 탐지기(JWT, 연결 문자열, hex, Base64)는 엔트로피 하한을 통과해야 합니다. 독립된 hex 또는 Base64는 인용 부호가 있을 때만 플래그됩니다. 인용 부호가 없는 고엔트로피 값은 자격 증명 이름의 변수에서만 감지되므로, git SHA 및 체크섬은 제외됩니다. 전체 탐지 및 심각도 규칙은 설명서를 참조하세요.

Credactor의 기본 규칙 세트는 전용 스캐너보다 범위가 좁으며 일부 공급자 형식(예: SendGrid, Twilio, Slack 웹훅)은 탐지되지 않습니다. Credactor의 강점은 수정(remediation)에 있습니다. 가장 넓은 탐지를 위해 Gitleaks 또는 TruffleHog와 함께 사용하거나 단독으로 실행하세요.

다른 스캐너와 함께 사용하여 모두 재작성 (BETA)

Credactor는 단독으로도 훌륭하지만, 함께 사용하면 더 강력해집니다. 이미 Gitleaks나 TruffleHog를 실행하고 있나요? 그 리포트를 Credactor에 전달하면 자체 발견 사항과 중복 제거된 통합 세트를 재작성합니다(겹치는 경우 더 높은 심각도가 우선). 한 번의 수정 패스로 자체 스캔과 다른 스캐너의 스캔을 모두 처리합니다:

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

--from-gitleaks / --from-trufflehog(또는 .credactor.toml의 [ingest] 테이블)는 디렉터리 대상을 필요로 합니다. CI 통합 가이드를 참조하세요.

추가 기능

• 대화형 또는 일괄 재작성; --replacement을 통한 사용자 정의 교체 문자열; git 커밋 이력을 스캔하는 --scan-history
• 안전한 백업: --secure-delete(.bak을 덮어쓰고 제거, 우연한 복구에 대한 기준을 높이지만 포렌식 보장은 아님) 또는 저장소 외부에 백업을 저장하는 --secure-backup-dir
• 인라인 # credactor:ignore 및 .credactorignore 허용 목록(glob, file:line, 값 리터럴)
• .credactor.toml을 통한 저장소별 구성
• 기본 제공 29가지 소스/설정/메모 파일 형식(.txt 포함); JSON을 포함하려면 --scan-json; 파일을 읽을 수 없을 때 실패하려면 --fail-on-error

스캔 파일 형식

.py .js .ts .jsx .tsx .sh .bash .env .cfg .ini .toml .yaml .yml .rb .go .java

또한 .env.* / .env-* 변형(.env.local, .env.production)과 SSH/개인 키 파일(id_rsa, id_dsa, id_ecdsa, id_ed25519)을 포함하며, 모두 확장자가 아닌 파일 이름으로 매칭됩니다. JSON은 API 응답에서 오탐률이 높기 때문에 기본적으로 제외됩니다. 포함하려면 --scan-json을 추가하세요. 명령줄에서 직접 지정한 파일은 이 목록에 없는 확장자라도 스캔됩니다.

종료 코드

공급망 강화

보안 도구는 실행할 때 안전할 뿐만 아니라 설치할 때도 안전해야 합니다. Credactor의 빌드 및 릴리스 파이프라인은 전 과정이 강화되어 있습니다. 자세한 내용은 보안 문서를 참조하세요.

• 런타임 의존성 제로. 기본 pip install credactor는 서드파티 패키지를 가져오지 않으므로(선택적 [encoding] 확장만 제외) 설치 시 검토할 것이 없습니다.
• 해시 고정 툴체인. CI 및 릴리스 빌드는 빌드 백엔드를 포함해 --require-hashes 잠금 파일에서 설치합니다(고정된 setuptools 기준 python -m build --no-isolation). 따라서 변조된 의존성은 빌드를 실패시킵니다.
• 아티팩트를 소스와 바이트 단위로 검증. 모든 푸시 시와 모든 게시 전에 scripts/audit_wheel.py가 휠(wheel)과 sdist를 커밋된 소스와 바이트 단위로 비교합니다(sha256 대 git HEAD). 추가, 누락 또는 변경된 파일이 있으면 게이트를 통과하지 못하므로 빌드 단계가 눈에 띄지 않게 코드를 주입할 수 없습니다.
• SHA 고정, 최소 권한 CI. GitHub Actions는 커밋 SHA에 고정되며, 워크플로 토큰도 좁게 유지됩니다. 기본적으로 contents: read, id-token: write는 게시 작업에서만 사용됩니다.

문서

라이선스

Apache 2.0. LICENSE를 참조하세요.