dragon-lady/push-guard로컬 Git pre-push 훅 및 파일시스템 스캐너로, 유출 가능성이 있는 시크릿을 탐지하고 일치하는 값을 마스킹하며, 텔레메트리나 네트워크 접근 없이 푸시를 차단합니다.
Push Guard는 잠재적인 시크릿 유출을 방지하기 위한 로컬 Git pre-push 가드입니다.
푸시되는 콘텐츠를 스캔하고, 잠재적인 시크릿 패턴을 보고하며, 일치하는 모든 값을 마스킹 처리하고, 0이 아닌 값으로 종료하여 Git이 푸시를 차단하도록 합니다.
Dragon Lady가 개발 및 유지 관리합니다 - github.com/Dragon-Lady - X: @answerislove2
버전 0.4.3에서는 인라인 # push-guard: ignore 예외가 제거되었습니다. 업그레이드하면 이전에 통과했던 푸시와 패키지가 차단되기 시작할 수 있습니다. 공유 훅이나 CI 설치를 업그레이드하기 전에, 각 사용 중인 저장소를 점검하십시오:
git grep -n -i 'push-guard:[[:space:]]*ignore'
각 일치 항목을 검토하십시오. 시크릿과 비공개 자료는 제거해야 하며, 어느 것도 예외로 둘 수 없습니다.
정당한 워크플로/IOC 픽스처의 경우, 검토된 정확한 저장소
경로와 정확한 workflow.* 규칙 ID만 .push-guard-allow에 추가하십시오. 인라인 마커는 이제
테스트나 문서에 있는 것을 포함하여 일반 텍스트입니다. 모든 마커 줄을
자동으로 허용 항목으로 변환하지 마십시오. 새로운 허용 항목은
보안에 민감한 변경으로 검토하십시오.
pre-push 훅은 작업 복사본이나 후보 커밋이 아닌, 대상의 광고된 베이스 커밋에서 예외를 읽습니다. 새로 추가되거나 확장된 허용 항목은 이후 푸시를 면제할 수 있기 전에 별도로 검토되고 설정되어야 합니다. 다중 ref 푸시의 경우, 모든 대상 베이스가 공유하는 예외만 적용됩니다. 광고된 베이스가 없는 새 ref는 예외를 받지 않습니다.
scan 역시 --base에서 정책을 읽습니다. 별도로 검토된 정책 스냅샷에 대해
더 큰 과거 범위를 감사할 때는 명시적으로
--allow-list-ref <reviewed-40-character-commit-SHA>를 전달하십시오. 이는 호출자의 명시적 신뢰
결정입니다. 검토되지 않은 후보의 정책으로 절대 대체하지 마십시오.
scan-package는 아티팩트 외부에서 호출자가 선택한 --repo 정책을 계속 사용합니다. 신뢰할 수 없는 빌드를 스캔할 때는 검토된 정책 디렉터리를 제공하십시오.
설치된 훅을 업그레이드하기 전에 새 버전의 push-guard scan --base <trusted-base> --head HEAD와
push-guard scan-package dist/*를 실제 발신 변경 사항과 빌드된
아티팩트에 대해 실행하십시오. 아카이브 멤버 경로는 소스 경로와 다를 수 있으므로, 해당 정확한 경로를
별도로 검토하십시오. 영향을 받는 저장소가 이 마이그레이션을 완료할 때까지
기존에 설치된 버전을 유지하십시오.
공개 랜딩 페이지: push-guard.netlify.app
정적 프로젝트 랜딩 페이지는 docs/에 있으며 런타임
의존성, 외부 스크립트, 분석, 원격 자산이 없습니다. docs/ 디렉터리에서 GitHub Pages로
제공하거나, 포함된 netlify.toml을 사용하여 Netlify에 배포할 수 있습니다(빌드 명령 없음, 게시 디렉터리 docs).
현재 Netlify 프로젝트는 수동 배포를 사용합니다. Git 푸시만으로는
공개 페이지가 업데이트되지 않습니다. 각 릴리스 후 docs/의 내용을 게시하고
라이브 버전, 소셜 이미지, 응답 헤더를 확인하십시오. docs/_headers
파일은 해당 디렉터리를 직접 배포할 때 보안 헤더를 유지합니다.
--send 옵션만 구성된 대상으로 집계
알림을 활성화합니다. Git 가드는 오프라인 상태를 유지합니다.git 하위 프로세스를 사용합니다. 기존 훅 진입점은
유지되며, 원시 콘텐츠와 발신 이력 검사가 강화되었습니다.$HOME 내부의 선택된 파일을 읽으며, Git을 포함한
하위 프로세스를 실행하지 않습니다.$XDG_STATE_HOME/push-guard-sweep/fp.key(기본값
~/.local/state/push-guard-sweep/fp.key)에 무작위 32바이트 HMAC 키를 하나 생성합니다.
이 키는 "기본적으로 데이터를 저장하지 않음"에 대한 명시적 예외입니다. 스캔된 데이터는 포함하지 않습니다. 상태 디렉터리는 0700이며 파일은 0600으로 생성됩니다.--baseline 및 --output 파일에는 마스킹된 로컬 메타데이터가 포함됩니다.
--send는 키 기반 중복 제거 영수증을 저장하며, 알림 자격 증명이나 시크릿은 절대 저장하지 않습니다.푸시 차단은 권고에 대한 Git의 응답입니다. Push Guard는 읽기 전용으로
유지되며 파일을 변경하지 않습니다. 일치한 값이 시크릿이 아님을 알고 있는 경우
git push --no-verify로 재정의할 수 있습니다.
push-guard sweep 명령과 push-guard-sweep 별칭은 동일한 로컬 검사를 제공합니다. 이들은 기존 패키지의 Python 3.11 이상을 요구하며 추가 런타임 의존성이 없습니다. 개발 테스트는 선택적 test 추가 기능을 사용합니다(python -m pip install ".[test]", 그런 다음 저장소 루트에서 PYTHONPATH=src python -m pytest -q). 0.4.0 릴리스에서는 Sweep이 추가됩니다. CI는 해당 개발 추가 기능을 설치하고 레거시 unittest 케이스를 포함한 전체 pytest 스위트를 실행합니다. 릴리스 테스트는 별도의 작업에서 실행되며, 해당 작업은 배포 아티팩트를 게시에 절대 제공하지 않습니다. 아티팩트 빌드 작업은 테스트 의존성을 설치하지 않습니다. Sweep은 스케줄러를 설치하거나 활성화하지 않습니다.
push-guard sweep --list-targets
push-guard sweep --roots ~/projects --class stray
push-guard-sweep --format json --output ~/sweep-report.json
push-guard-sweep --baseline ~/sweep-baseline.json
push-guard-sweep report --format html --output ~/sweep-report.html
push-guard-sweep print-timer --interval 7d
모든 스캔은 아래의 기본 히스토리, 닷파일, 구성 및 로그 위치도 함께 고려합니다. --roots는 .env* 및 사용자 지정 포함 검색 루트를 변경하며, --exclude를 사용하여 다른 기본 집합을 좁힐 수 있습니다. 반복된 --include GLOB은 기존의 제한된 검색 범위 내에 파일을 추가하고, 반복된 --exclude GLOB은 경로를 제거합니다. Glob은 베이스 이름, HOME 기준 상대 경로 또는 절대 경로와 일치합니다. 제외가 우선하며, 포함은 안전 제외나 깊이 제한을 무시할 수 없습니다. CLI 경로 인수의 ~는 확장됩니다. 스캔된 경로는 $HOME 내부에 있어야 합니다.
.lesshst. SQLite 셸 히스토리 텍스트는 데이터베이스 파일과 별개입니다..bashrc, .zshrc, .profile, .bash_profile, .npmrc, .docker/config.json; .config 아래 최대 4개 디렉터리 수준의 선택된 JSON, TOML, YAML, INI 및 CONF 파일..env* 파일: 선택된 루트(기본 HOME) 아래 최대 6개 디렉터리 수준. 의존성 트리, 가상 환경, Git 메타데이터 및 캐시는 이 검색에서 제외됩니다..log 파일 및 logs/ 내 파일, .local/state, .cache, .codex, .config/Cursor/logs 및 구성된 log_dirs 아래 최대 4개 디렉터리 수준.알려진 자격 증명 저장소(.git-credentials, .aws/credentials, .netrc, .pypirc, .config/gh/hosts.yml, .config/rclone/rclone.conf, .codex/auth.json)는 메타데이터 전용 검사입니다. 해당 내용은 절대 열리지 않습니다. 각각은 expected-store로 보고되며, 비공개 모드의 경우 info 심각도, 실행/그룹/기타 권한의 경우 warn 심각도입니다. line은 null이고 fp_kind=path는 토큰 지문이 아닌 키가 지정된 경로 지문임을 명시적으로 나타냅니다. Reach Ward는 이러한 저장소의 자격 증명 인벤토리를 소유합니다. 이는 모드 검사에 대해 비밀 값이나 줄 번호를 만들어내는 것을 방지합니다. 다른 모든 일치 항목은 stray로 분류되며 일반적으로 warn입니다. Google 액세스 토큰은 낮은 심각도이며 단기 수명으로 표시되어 만료되었을 가능성이 높습니다. 어떤 토큰도 제공자에 대해 검사되지 않습니다.
Sweep은 Push Guard의 제공자 정의와 일반 할당 매처를 재사용하고, Slack, Google, npm, PyPI, JWT 및 자격 증명이 포함된 URL 형태를 추가하며, 확장된 OpenAI 토큰 형태를 감지합니다. 일반 할당은 추가로 문자당 최소 3.5비트의 엔트로피를 요구합니다. 명백한 채우기 값과 변수 참조는 무시되며, test와 같은 단어를 포함하는 무작위 제공자 토큰은 여전히 보고됩니다. # push-guard: ignore는 Sweep 일치 항목을 억제할 수 없습니다. 완전한 개인 키 블록은 전체가 지문 처리되며, 불완전한 블록은 헤더 이후의 제한된 나머지 부분이 지문 처리됩니다. 개인 키 자료는 저장되지 않습니다.
발견 항목에는 로컬 경로, 줄, 규칙, 유형, 클래스, 심각도, 모드, fp:와 16개의 HMAC-SHA256 16진수 문자, 그리고 리터럴 <redacted>가 포함됩니다. .git 디렉터리 또는 파일은 메타데이터만으로 가능한 Git 소속을 설정합니다. 추적 상태는 항상 unknown입니다: Sweep은 Git을 실행하거나 인덱스를 파싱하지 않습니다. 경로는 발견된 비밀 값이나 토큰 형태를 포함하는 경우 마스킹됩니다. 인코딩된 경로 레이블은 보수적으로 전체가 대체됩니다. 보고서에는 소스 줄이 절대 포함되지 않습니다. 힌트는 인쇄된 조언일 뿐이며, Sweep은 히스토리를 삭제하거나, 자격 증명을 교체하거나, .gitignore를 편집하거나, 파일의 모드를 변경하지 않습니다.
--list-targets는 스캔 대상이나 구성 내용을 전혀 읽지 않으며 지문 키나 기타 파일을 생성하지 않습니다. 기본값과 CLI 대상 옵션만 사용하며, 기본 구성 파일을 읽지 않습니다. 이를 --config, --baseline, --output 또는 --send와 결합하면 거부됩니다. 의도된 텍스트 읽기를 나열하고 예상 저장소를 메타데이터 전용으로 명시적으로 표시합니다. 바이너리 내용은 읽지 않고는 식별할 수 없으므로, 이름이 없는 바이너리 파일이 이 미리보기에 나타나고 스캔 중에 건너뛰어질 수 있습니다.
모든 심볼릭 링크, 하드 링크, FIFO, 디바이스, 소켓, 알려진 브라우저 프로필/키링 경로, 데이터베이스 파일명 및 압축/바이너리 확장자는 건너뜁니다. 디렉터리 구성 요소는 no-follow 디스크립터로 열리므로, 심볼릭 링크된 상위 디렉터리가 읽기를 다른 곳으로 리다이렉트할 수 없습니다. 텍스트 읽기는 파일당 최대 10 MiB로 제한되며, 데이터베이스/압축 매직, NUL 바이트, 바이너리 제어 바이트 또는 잘못된 UTF-8은 건너뛰기를 유발합니다. 식별 가능한 바이너리/데이터베이스/압축 콘텐츠는 최대 8 KiB의 헤더 읽기 후 거부됩니다. 설정/상태 읽기는 별개이며 변경되지 않습니다. 예상치 못한 바이너리/데이터베이스 이름을 가진 파일은 콘텐츠를 식별하기 위해 제한된 읽기가 필요합니다. SQLite 라이브러리는 사용되지 않습니다. 탐색은 250,000개의 디렉터리 항목, 10,000개의 대상 파일 및 10,000개의 발견 항목으로 제한되며, 베이스라인은 10 MiB로 제한됩니다. 한 번의 실행에는 100 MiB의 텍스트 읽기 예산과 하나의 공유된 45초 검사 기한이 있습니다. 예산 소진 시 부분적이고 불완전한 보고서를 반환하며 종료 코드 2로 종료됩니다. 느린 스토리지는 중단 불가능한 커널 시스템 호출 중에 여전히 기한을 초과할 수 있습니다.
종료 코드: 0 발견 항목 없음, 1 발견 항목 있음(정보성 저장소 검사 포함), 2 사용법, 런타임, 불완전 검사 또는 경고 전달 오류. 의도적인 정책 건너뛰기는 별도로 요약되며 검사 실패를 의미하지 않습니다. 표준 선택적 소스 파일이 없는 것은 정상입니다. 텍스트, JSON, Markdown 및 자체 포함 이스케이프 HTML은 --format을 통해 사용할 수 있습니다.
첫 --baseline FILE 실행은 모든 것을 보고하고 지문, 경로, 줄, 규칙 ID 및 모드를 저장합니다. 이후 실행은 이전 성공적인 스캔에 없는 항목만 보고한 다음 해당 베이스라인을 원자적으로 교체합니다. 변경된 모드나 줄은 새 항목입니다. 제거된 항목은 삭제됩니다. 불완전한 스캔은 베이스라인을 절대 업데이트하지 않습니다. 베이스라인은 비공개이며 검증된 파일이고 동일한 지문 키를 사용해야 합니다. 키가 없거나 변경된 경우 비교 전에 원래 키를 복원해야 합니다. 출력 보고서는 기존 파일을 절대 덮어쓰지 않습니다. 모든 출력 및 베이스라인 파일은 생성 시 0600이며, 대상 상위 디렉터리는 이미 존재해야 합니다. 소스 파일은 상태로 재용도화되지 않습니다.
report는 기본적으로 과거 스캔 결과가 보관되지 않으므로 새로운 로컬 스캔을 수행합니다. print-timer는 별도의 systemd 사용자 서비스/타이머 텍스트를 stdout으로 출력하며 아무것도 설치하지 않습니다. 타이머는 기본값 또는 저장된 설정을 사용합니다. 의도한 머신에서 도구를 검증한 후 직접 검토하고 저장하십시오.