rxb06/credactor스캔. 삭제. 깨끗한 커밋.
[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**비밀을 찾아라. 고쳐라. 깨끗하게 커밋하라.**
비밀 스캐너는 경보를 울리는 데는 능하지만, 문제를 해결하는 데는 별 도움이 되지 않습니다. 유출된 자격 증명 목록을 건네주고 정리는 당신에게 맡깁니다. Credactor는 이 순환을 완성합니다. 하드코딩된 비밀을 찾아 그 자리에서 다시 작성하여, 유출이 탐지에서 수정까지 단 하나의 명령으로 이루어집니다.
<img alt="Credactor: 스캔, 삭제, 깨끗한 커밋" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
자격 증명을 소스 코드 밖에 두는 것은 선택이 아닌 기본 보안 관행입니다. Credactor는 커밋 전 로컬 머신에서든, 병합 전 CI에서든 이 기본을 저렴하게 유지할 수 있게 해줍니다. 단독으로 실행하거나, 이미 신뢰하는 스캐너와 함께 실행하세요.
```python
# 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"]
```
> 삭제는 **작업 트리**의 파일을 다시 작성합니다. 비밀이 이미 커밋되었다면, 키를 교체하고 기록도 정리하세요 (예: `git filter-repo` 사용). 파일을 다시 작성하는 것은 유출된 자격 증명을 폐기하는 것의 대체물이 아닙니다.
---
## Credactor를 사용하는 이유
- **탐지가 아닌 삭제.** 대부분의 스캐너는 발견에서 멈춥니다. 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 또는 Betterleaks 보고서 수집. 이미 실행 중인 스캐너로 탐지하고, Credactor로 수정하세요.
## 설치
```bash
pip install credactor
```
Python 3.11+가 필요합니다. 다른 의존성은 없습니다. Linux, macOS, Windows에서 실행됩니다 (CI는 Linux와 Windows에서 테스트됨).
macOS와 Linux에서는 대신 Homebrew로 설치할 수 있습니다:
```bash
brew install rxb06/tap/credactor
```
이 formula는 자체 virtualenv에 설치하며 선택적 `[encoding]` 추가 기능을 포함하므로, Homebrew 설치도 비UTF-8 파일에서 비밀을 탐지합니다. 일반 `pip install credactor`는 이 추가 기능을 제외합니다. 동일한 범위를 원하면 `pip install 'credactor[encoding]'`으로 추가하세요.
소스에서:
```bash
git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .
```
그러면 `credactor`는 어느 디렉터리에서든 작동합니다.
## 빠른 시작
> 먼저 `--dry-run`을 실행하고 삭제하기 전에 발견 사항을 검토하세요. 오탐이 가능하며, `--fix-all`에서는 오탐이 다시 작성됩니다. 알려진 안전한 값은 `# credactor:ignore` 또는 `.credactorignore` 항목으로 억제하세요.
```bash
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 --scan-history .`를 사용하세요.
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.4 # pin to the latest release tag
hooks:
- id: credactor
```
### GitHub Action
```yaml
- uses: rxb06/[email protected]
```
이 action은 항상 `--ci`를 전달하므로 보고하고 게이트하지만 체크아웃을 다시 작성하지 않습니다. 발견 사항은 단계를 실패시킵니다. 게이트 없이 보고하려면 `fail-on-findings: false`를 설정하세요. 오류는 어느 경우든 단계를 실패시킵니다.
발견 사항에서 실패하는 대신 Code Scanning에 업로드:
```yaml
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
업로드를 위해 작업에는 `permissions: security-events: write`가 필요합니다. Gitleaks, TruffleHog 및 Betterleaks 보고서 수집을 포함한 모든 입력은 [CI 통합 가이드](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action)를 참조하세요.
## 탐지
Credactor는 가장 자주 유출되는 자격 증명 유형을 탐지하고, 각각에 심각도를 할당하여 한눈에 분류할 수 있게 합니다.
| 카테고리 | 예시 | 심각도 |
|---|---|---|
| 클라우드 제공자 키 | AWS (`AKIA…`), GCP (`AIza…`), Stripe (`sk_live_…`), Slack (`xoxb-…`) | Critical |
| 플랫폼 토큰 | GitHub (`ghp_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Critical |
| 개인 키 | PEM 블록 (`-----BEGIN … PRIVATE KEY-----`) | 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 |
| 고엔트로피 문자열 | 따옴표로 묶인 hex (32–64자) / Base64 (60자 이상) | Medium/Low |
결정적 제공자 토큰 (위의 접두사)은 엔트로피와 관계없이 플래그됩니다. 휴리스틱 탐지기 (JWT, 연결 문자열, hex, Base64)는 엔트로피 하한을 통과해야 합니다. 독립형 hex 또는 Base64는 따옴표로 묶인 경우에만 플래그됩니다. 따옴표 없는 고엔트로피 값은 자격 증명 이름이 지정된 변수에서만 잡히므로 git SHA와 체크섬은 제외됩니다. 전체 탐지 및 심각도 규칙은 [매뉴얼](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity)을 참조하세요.
> Credactor의 기본 규칙 세트는 전용 스캐너보다 좁으며, 일부 제공자 형식 (예: SendGrid, Twilio, Slack 웹훅)은 탐지되지 않습니다. 강점은 수정입니다. 가장 광범위한 탐지를 위해 Gitleaks, TruffleHog 또는 Betterleaks와 함께 사용하거나 단독으로 실행하세요.
## 다른 스캐너와 함께 사용하고 전부 삭제하세요
Credactor는 단독으로도 충분하며, 함께 사용하면 더 강력해집니다. 이미 Gitleaks, TruffleHog 또는 Betterleaks를 실행 중이신가요? 그들의 보고서를 Credactor에 전달하면 결합된 세트를 삭제하고, 자체 발견 사항과 중복 제거합니다 (중복 시 더 높은 심각도가 우선). 한 번의 수정 패스로 귀하의 스캔과 그들의 스캔을 모두 커버합니다:
```bash
gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .
betterleaks dir . -f json -r betterleaks.json
credactor --from-betterleaks betterleaks.json --fix-all --yes .
```
`--from-gitleaks` / `--from-trufflehog` / `--from-betterleaks` (또는 `.credactor.toml`의 `[ingest]` 테이블)는 디렉터리 대상을 요구합니다. 스캐너가 실행된 동일한 루트로 Credactor를 지정하세요. 보고서 경로는 작업 디렉터리를 기준으로 해석되며, 보고서는 스냅샷입니다. 삭제하거나 트리를 변경한 후에는 다시 생성하세요. [CI 통합 가이드](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md)를 참조하세요.
## 더 많은 기능
- 대화형 또는 일괄 삭제; `--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` `.php` `.cs` `.kt` `.tf` `.hcl` `.conf` `.config` `.properties` `.xml` `.pem` `.key` `.crt` `.txt`
추가로 `.env.*` / `.env-*` 변형 (`.env.local`, `.env.production`) 및 SSH / 개인 키 파일 (`id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`)이 있으며, 모두 확장자가 아닌 파일 이름으로 매칭됩니다. JSON은 API 응답이 높은 오탐률을 생성하므로 기본적으로 제외됩니다. 포함하려면 `--scan-json`을 추가하세요. 명령줄에 직접 지정된 파일은 확장자가 이 목록에 없어도 스캔됩니다.
## 종료 코드
| 코드 | 의미 |
|---|---|
| `0` | 발견 사항 없음, 또는 모두 해결됨 |
| `1` | 해결되지 않은 발견 사항 |
| `2` | 오류 (예: 잘못된 경로, 위험한 `--replacement`, `--ci --fix-all`, 누락되거나 유효하지 않은 수집 보고서, 또는 읽을 수 없는 파일과 함께 `--fail-on-error`) |
## 공급망 강화
보안 도구는 실행하기에 안전할 뿐만 아니라 설치하기에도 안전해야 합니다. Credactor의 빌드 및 릴리스 파이프라인은 처음부터 끝까지 강화되어 있습니다. 전체 세부 사항은 [보안 문서](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening)를 참조하세요.
- **런타임 의존성 제로.** 기본 `pip install credactor`는 타사 패키지를 전혀 가져오지 않으므로 (선택적 `[encoding]` 추가 기능만), 설치 시 검증할 것이 없습니다.
- **해시 고정 툴체인.** CI 및 릴리스 빌드는 `--require-hashes` 잠금 파일에서 설치하며, 빌드 백엔드도 포함됩니다 (고정된 setuptools에 대해 `python -m build --no-isolation`). 따라서 변조된 의존성은 빌드를 실패시킵니다.
- **소스에 대해 바이트 검사된 아티팩트.** 모든 푸시와 모든 게시 전에 `scripts/audit_wheel.py`가 wheel과 sdist를 커밋된 소스와 바이트 단위로 비교합니다 (sha256 vs `git HEAD`). 추가, 누락 또는 변경된 파일은 게이트를 실패시켜, 빌드 단계가 몰래 코드를 주입할 수 없습니다.
- **SHA 고정, 최소 권한 CI.** GitHub Actions는 커밋 SHA에 고정되며, 워크플로 토큰은 좁게 유지됩니다 — 기본적으로 `contents: read`, 게시 작업에만 `id-token: write`.
## 문서
| 문서 | 설명 |
|----------|-------------|
| [설정 가이드](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | 설치, 구성, CI/CD 통합 |
| [매뉴얼](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | 완전한 참조: 모든 플래그, 모드 및 조합, 교체 및 백업 동작, 탐지 및 심각도, 종료 코드, 제한 사항 (동작 테스트 검증됨) |
| [예제](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | 출력이 포함된 일반적인 워크플로 |
| [CI 통합](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-commit 훅, CI 파이프라인 |
| [보안](https://github.com/rxb06/credactor/blob/main/docs/security.md) | 위협 모델, 강화 조치, 알려진 제한 사항 |
| [변경 로그](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | 버전 기록 |
| [기여](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | 개발 설정, 코드 스타일, PR 프로세스 |
| [면책 조항](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | 제한 사항, 안전한 사용, 보증 |
## 라이선스
Apache 2.0. [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE)를 참조하세요.