gitguardian/ggshield하드코딩된 500종 이상의 비밀 정보를 고급 검사로 탐지하고 검증합니다. 사전 커밋 훅, GitHub Action 또는 CLI로 사용하여 사전 예방적인 비밀 탐지와 보안을 실현하세요.
# [ggshield](https://github.com/GitGuardian/ggshield): GitGuardian으로 코드를 보호하세요
[](https://pypi.org/project/ggshield/)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
[](https://github.com/GitGuardian/ggshield/stargazers)
[](https://github.com/GitGuardian/ggshield/actions)
[](https://codecov.io/gh/GitGuardian/ggshield/)
> [!IMPORTANT]
> **macOS: 1.54.0으로 업그레이드하면 `ggshield-py`에 대한 Keychain 프롬프트가 표시됩니다.** 이는 성능 개선의 일환으로 저장된 토큰을 읽는 두 번째 바이너리입니다. **Always Allow**를 클릭하세요. 다시 묻지 않습니다.
`ggshield`는 로컬 환경이나 CI 환경에서 실행되어 500가지 이상의 유형의 시크릿을 탐지하는 데 도움을 주는 CLI 애플리케이션입니다.
`ggshield`는 [py-gitguardian](https://github.com/GitGuardian/py-gitguardian)을 통해 [공개 API](https://api.gitguardian.com/docs)를 사용하여 파일 및 기타 텍스트 콘텐츠에서 잠재적인 취약점을 스캔하고 탐지합니다.
`ggshield`를 사용한 스캔에서는 호출 시간, 요청 크기, 스캔 모드와 같은 메타데이터만 저장되므로, 시크릿은 대시보드에 표시되지 않으며 **파일과 시크릿은 저장되지 않습니다**.
# 목차
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [설치](#설치)
- [설치 스크립트 (권장)](#설치-스크립트-권장)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [독립 실행형 .pkg 패키지](#독립-실행형-pkg-패키지)
- [Linux](#linux)
- [Deb 및 RPM 패키지](#deb-및-rpm-패키지)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [MSI 설치 프로그램](#msi-설치-프로그램)
- [독립 실행형 .zip 아카이브](#독립-실행형-zip-아카이브)
- [모든 운영 체제](#모든-운영-체제)
- [pipx 사용](#pipx-사용)
- [pip 사용](#pip-사용)
- [초기 설정](#초기-설정)
- [`ggshield auth login` 사용](#ggshield-auth-login-사용)
- [수동 설정](#수동-설정)
- [시작하기](#시작하기)
- [시크릿](#시크릿)
- [레거시 구성 파일 마이그레이션](#레거시-구성-파일-마이그레이션)
- [통합](#통합)
- [AI 코딩 어시스턴트](#ai-코딩-어시스턴트)
- [더 알아보기](#더-알아보기)
- [출력](#출력)
- [관련 오픈 소스 프로젝트](#관련-오픈-소스-프로젝트)
- [라이선스](#라이선스)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# 설치
<!--
Any change made in this section must be replicated in the "Step 1: Install
ggshield" section of the "Getting started" page of ggshield public
documentation.
-->
## 설치 스크립트 (권장)
`ggshield`를 설치하는 가장 빠른 방법입니다.
Linux / macOS:
```shell
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
```
Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
```
또는 `curl`(Windows 10 이상에 포함)을 선호하는 경우:
```powershell
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`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md)를 참조하세요.
아래 방법들은 대신 CLI를 수동으로 설치합니다.
## macOS
### Homebrew
Homebrew를 사용하여 `ggshield`를 설치할 수 있습니다:
```shell
brew install ggshield
```
업그레이드는 Homebrew에서 처리합니다.
### 독립 실행형 .pkg 패키지
또는 [`ggshield` 릴리스 페이지](https://github.com/GitGuardian/ggshield/releases)에서 독립 실행형 .pkg 패키지를 다운로드하여 설치할 수 있습니다.
이 패키지는 Python 설치가 _필요하지 않지만_, 새 버전을 수동으로 다운로드해야 합니다.
## Linux
### Deb 및 RPM 패키지
Deb 및 RPM 패키지는 [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/)에서 사용할 수 있습니다.
설정 지침:
- [Deb 패키지](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [RPM 패키지](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
업그레이드는 패키지 관리자에서 처리합니다.
## Windows
### Chocolatey
`ggshield`는 [Chocolatey 패키지 관리자](https://chocolatey.org/packages/ggshield)를 통해 사용할 수 있습니다:
```shell
choco install ggshield
```
### MSI 설치 프로그램
[`ggshield` 릴리스 페이지](https://github.com/GitGuardian/ggshield/releases)에서 MSI 설치 프로그램을 다운로드하여 설치하세요:
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### 독립 실행형 .zip 아카이브
[`ggshield` 릴리스 페이지](https://github.com/GitGuardian/ggshield/releases)에서 독립 실행형 .zip 아카이브를 제공합니다.
아카이브를 디스크에 압축 해제한 다음, `ggshield.exe` 파일이 포함된 디렉터리를 `%PATH%`에 추가하세요.
이 아카이브는 Python 설치가 _필요하지 않지만_, 새 버전을 수동으로 다운로드해야 합니다.
## 모든 운영 체제
`ggshield`는 [PyPI 패키지](https://pypi.org/project/ggshield)를 통해 모든 지원 운영 체제에 설치할 수 있습니다.
**지원되는 Python 버전(EOL 아님)**(독립 실행형 패키지 제외)과 git이 필요합니다.
`ggshield`의 패키지 버전을 사용하지 않는 경우, [Python 릴리스 주기](https://devguide.python.org/versions/)를 따르며 EOL에 도달한 버전은 지원하지 않는다는 점을 유의하세요.
### pipx 사용
PyPI에서 `ggshield`를 설치하는 권장 방법은 [pipx](https://pypa.github.io/pipx/)를 사용하는 것이며, 이는 격리된 환경에 설치합니다:
```shell
pipx install ggshield
```
설치를 업그레이드하려면 다음을 실행하세요:
```shell
pipx upgrade ggshield
```
### pip 사용
pip를 사용하여 PyPI에서 `ggshield`를 설치할 수도 있지만, 설치는 격리되지 않으므로 이 방법으로 설치된 다른 애플리케이션이나 패키지가 `ggshield` 설치에 영향을 미칠 수 있으므로 권장하지 않습니다. 이 방법은 Python 설치가 외부 관리로 선언된 경우(예: Debian 12와 같은 운영 체제에서 시스템 Python을 사용하는 경우)에도 작동하지 않습니다:
```shell
pip install --user ggshield
```
설치를 업그레이드하려면 다음을 실행하세요:
```shell
pip install --user --upgrade ggshield
```
# 초기 설정
## `ggshield auth login` 사용
`ggshield`를 사용하려면 GitGuardian 서버에 대해 인증해야 합니다. 이를 위해 `ggshield auth login` 명령을 사용하세요. 이 명령은 개인 액세스 토큰의 프로비저닝과 로컬 워크스테이션에서의 구성을 자동화합니다.
자세한 내용은 [`ggshield auth login` 문서](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login)에서 확인할 수 있습니다.
인증 후, 첫 스캔 전에 `ggshield machine setup`을 실행하여 AI 및 git 훅을 구성하고, 허니토큰을 심고, Endpoints 페이지에 머신을 등록하세요. 등록에는 현재 사용자 또는 root로 실행할 때 모든 허니토큰 대상 사용자가 포함됩니다. 이는 최선의 노력으로 수행되며 최대 5초가 걸리고 명령의 종료 코드에 영향을 주지 않습니다.
`ggshield secret scan pre-commit`, `pre-push` 및 `ai-hook`의 스캔은 머신 호스트 이름도 전송하며, GitGuardian은 이를 통해 이러한 훅의 사용자를 등록합니다. 다른 스캔 명령은 이를 전송하지 않으며, 독립 실행형 및 플랫폼별 `pip` 설치가 실행하는 네이티브 AI 훅도 전송하지 않습니다.
CI에서는 ggshield가 머신을 등록하지도, 호스트 이름을 전송하지도 않습니다. 다른 곳에서 둘 다 끄려면 `.gitguardian.yaml`에 `endpoint_registration: false`를 설정하거나 `GGSHIELD_NO_ENDPOINT_REGISTRATION`을 비어 있지 않은 값으로 설정하세요.
## 수동 설정
개인 액세스 토큰을 수동으로 생성하고 `GITGUARDIAN_API_KEY` 환경 변수에 저장하여 설정을 완료할 수도 있습니다.
# 시작하기
## 시크릿
이제 `ggshield`를 사용하여 시크릿을 검색할 수 있습니다:
- 파일에서: `ggshield secret scan path -r .`
- 저장소에서: `ggshield secret scan repo .`
- Docker 이미지에서 (`docker` 명령을 사용할 수 있어야 함): `ggshield secret scan docker ubuntu:22.04`
- Pypi 패키지에서 (`pip` 명령을 사용할 수 있어야 함): `ggshield secret scan pypi flask`
- 그 외 더 많은 기능은 `ggshield secret scan --help` 출력에서 자세히 확인하세요.
## 레거시 구성 파일 마이그레이션
`ggshield`가 `.gitguardian.yaml`(또는 `.gitguardian.yml`) 구성 파일이 더 이상 사용되지 않는 형식을 사용한다고 보고하면, 다음으로 최신 버전으로 마이그레이션하세요:
```shell
ggshield config migrate
```
기본적으로 현재 디렉터리에서 구성 파일을 찾으므로, 파일이 포함된 디렉터리에서 실행하세요. 어디서나 실행하려면 `ggshield`에 파일을 명시적으로 지정하세요:
```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```
이전 버전의 파일은 옆에 `.old` 백업으로 유지됩니다.
# 통합
`ggshield`를 [CI/CD 워크플로](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow)에 통합할 수 있습니다.
오류를 더 일찍 잡으려면 `ggshield`를 [pre-commit, pre-push 또는 pre-receive Git 훅](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs)으로 사용하세요.
## AI 코딩 어시스턴트
`ggshield`는 사용자와 AI 코딩 어시스턴트 간의 [상호작용을 실시간으로 스캔](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools)하여 시크릿이 포함된 작업이 실행되기 전에 차단할 수 있습니다.
`ggshield install` 명령으로 훅을 설치할 수 있습니다.
지원 도구: **Cursor**, **Claude Code**, **Copilot Chat**, **Codex**, **Mistral Vibe 2.21+**.
# 더 알아보기
자세한 내용은 [문서](https://docs.gitguardian.com/ggshield-docs/getting-started)를 참조하세요.
# 출력
시크릿이 발견되지 않으면 종료 코드는 0입니다:
```bash
ggshield secret scan pre-commit
```
스테이징된 코드나 CI에서 시크릿이 발견되면, 시크릿이 발견된 파일 이름과 파일 내 시크릿의 위치를 알려주는 패치가 포함된 경고가 표시됩니다:
```shell
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 | }
```
너무 긴 줄은 상세 모드(`-v` 또는 `--verbose`)를 사용하지 않는 한 터미널 크기에 맞게 잘립니다.
# 관련 오픈 소스 프로젝트
- [truffleHog](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
# 라이선스
`ggshield`는 MIT 라이선스입니다.