gitguardian/ggshield하드코딩된 500종 이상의 비밀 정보를 고급 검사로 탐지하고 검증합니다. 사전 커밋 훅, GitHub Action 또는 CLI로 사용하여 사전 예방적인 비밀 탐지와 보안을 실현하세요.
ggshield는 로컬 환경 또는 CI 환경에서 실행되어 500개 이상의 유형의 비밀(secret)을 탐지하는 데 도움을 주는 CLI 애플리케이션입니다.
ggshield는 py-gitguardian을 통해 공개 API를 사용하여 파일 및 기타 텍스트 콘텐츠에서 잠재적인 취약점을 스캔하고 탐지합니다.
ggshield를 사용한 스캔에서는 호출 시간, 요청 크기, 스캔 모드와 같은 메타데이터만 저장됩니다. 따라서 비밀(secret)이 대시보드에 표시되지 않으며 파일과 비밀이 저장되지 않습니다.
ggshield를 설치하는 가장 빠른 방법입니다.
Linux / macOS:
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
또는 curl(Windows 10+에 내장)을 선호하는 경우:
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
이 스크립트는 --instance 및 --plugin (플러그인 설치)과 같은 옵션을 지원합니다. EU 워크스페이스 또는 자체 호스팅 인스턴스의 경우, 실행 전에 GITGUARDIAN_INSTANCE 환경 변수를 설정(또는 --instance <URL> 전달)하세요.
전체 옵션 목록, 다른 설치 방법 및 제거 방법은 scripts/install/README.md를 참조하세요.
아래 방법들은 CLI를 수동으로 설치합니다.
Homebrew를 사용하여 ggshield를 설치할 수 있습니다:
brew install ggshield
업그레이드는 Homebrew에서 처리합니다.
또는 ggshield 릴리스 페이지에서 독립 실행형 .pkg 패키지를 다운로드하여 설치할 수 있습니다.
이 패키지는 Python 설치가 필요하지 않지만, 새 버전을 수동으로 다운로드해야 합니다.
Deb 및 RPM 패키지는 Cloudsmith에서 사용할 수 있습니다.
설정 방법:
업그레이드는 패키지 관리자가 처리합니다.
ggshield는 Chocolatey 패키지 관리자를 통해 사용할 수 있습니다:
choco install ggshield
ggshield 릴리스 페이지에서 MSI 설치 프로그램을 다운로드하여 설치하세요:
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
ggshield 릴리스 페이지에서 독립 실행형 .zip 아카이브를 제공합니다.
아카이브를 디스크에 압축 풀고 ggshield.exe 파일이 포함된 디렉터리를 %PATH%에 추가하세요.
이 아카이브는 Python 설치가 필요하지 않지만, 새 버전을 수동으로 다운로드해야 합니다.
ggshield는 모든 지원 운영 체제에서 PyPI 패키지를 통해 설치할 수 있습니다.
(독립 실행형 패키지 제외) 지원되는 Python 버전(수명 종료되지 않은 버전) 및 git이 필요합니다.
ggshield의 패키지 버전을 사용하지 않는 경우, Python 릴리스 주기를 따르며 수명 종료(EOL)에 도달한 버전은 지원하지 않습니다.
PyPI에서 ggshield를 설치하는 권장 방법은 pipx를 사용하는 것입니다. pipx는 격리된 환경에 설치합니다:
pipx install ggshield
설치를 업그레이드하려면 다음을 실행하세요:
pipx upgrade ggshield
pip를 사용하여 PyPI에서 ggshield를 설치할 수도 있지만, 설치가 격리되지 않아 다른 애플리케이션이나 패키지가 ggshield 설치에 영향을 줄 수 있으므로 권장되지 않습니다. 또한 Python 설치가 외부 관리 대상으로 선언된 경우(예: Debian 12와 같은 운영 체제에서 시스템 Python을 사용하는 경우) 이 방법은 작동하지 않습니다:
pip install --user ggshield
설치를 업그레이드하려면 다음을 실행하세요:
pip install --user --upgrade ggshield
ggshield auth login 사용ggshield를 사용하려면 GitGuardian 서버에 인증해야 합니다. 이를 위해 ggshield auth login 명령을 사용합니다. 이 명령은 개인 액세스 토큰을 프로비저닝하고 로컬 워크스테이션에 구성하는 과정을 자동화합니다.
자세한 내용은 ggshield auth login 문서를 참조하세요.
개인 액세스 토큰을 수동으로 생성하고 GITGUARDIAN_API_KEY 환경 변수에 저장하여 설정을 완료할 수도 있습니다.
이제 ggshield를 사용하여 비밀(secret)을 검색할 수 있습니다:
ggshield secret scan path -r .ggshield secret scan repo .docker 명령이 가능해야 함): ggshield secret scan docker ubuntu:22.04pip 명령이 가능해야 함): ggshield secret scan pypi flaskggshield secret scan --help 출력을 확인하세요.ggshield가 .gitguardian.yaml(또는 .gitguardian.yml) 설정 파일이 더 이상 사용되지 않는 형식을 사용한다고 보고하는 경우, 다음 명령으로 최신 버전으로 마이그레이션하세요:
ggshield config migrate
기본적으로 현재 디렉터리에서 설정 파일을 찾으므로 파일이 있는 디렉터리에서 실행하세요. 어디서든 실행하려면 ggshield에 파일을 명시적으로 지정하세요:
ggshield --config-path path/to/.gitguardian.yaml config migrate
이전 버전의 파일은 .old 백업으로 그 옆에 유지됩니다.
ggshield를 CI/CD 워크플로우에 통합할 수 있습니다.
오류를 더 일찍 발견하려면 ggshield를 pre-commit, pre-push 또는 pre-receive Git 훅으로 사용하세요.
ggshield는 AI 코딩 어시스턴트와의 상호작용을 실시간으로 스캔하여 비밀이 포함된 동작이 실행되기 전에 차단할 수 있습니다.
ggshield install 명령으로 훅을 설치할 수 있습니다.
지원 도구: Cursor, Claude Code, Copilot Chat, Codex.
자세한 내용은 문서를 참조하세요.
비밀(secret)이 발견되지 않으면 종료 코드는 0입니다:
ggshield secret scan pre-commit
스테이징된 코드 또는 CI에서 비밀이 발견되면, 비밀이 발견된 파일 이름을 알려주는 알림과 파일 내 비밀 위치를 보여주는 패치가 표시됩니다:
ggshield secret scan pre-commit
2 incidents have been found in file production.rb
11 | config.paperclip_defaults = {
12 | :s3_credentials => {
13 | :bucket => "XXX",
14 | :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
|_____AWS Keys_____|
15 | :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|_______________AWS Keys_______________|
16 | }
17 | }
너무 긴 줄은 터미널 크기에 맞게 잘리며, verbose 모드(-v 또는 --verbose)를 사용하면 잘리지 않습니다.
ggshield는 MIT 라이선스입니다.