OpenClaw ggshield Scanner 스킬 가이드

OpenClaw ggshield Scanner 스킬 개요

ggshield Scanner 스킬은 GitGuardian의 강력한 시크릿 탐지 엔진을 OpenClaw 워크플로우에 통합합니다. ggshield CLI 플래그와 출력 형식을 외울 필요 없이, 자연어로 OpenClaw에 코드의 유출된 시크릿 스캔을 요청할 수 있습니다.

ggshield는 500가지 이상의 하드코딩된 시크릿을 탐지합니다 — API 키, 데이터베이스 자격 증명, 클라우드 토큰, 개인 키 등. OpenClaw ggshield scanner 스킬은 이러한 기능을 대화형 인터페이스로 래핑하여, 온디맨드 스캔 실행, pre-commit 훅 설정, 결과 해석을 개발 플로우를 벗어나지 않고 수행할 수 있습니다.

일반적인 워크플로우:

1. OpenClaw에 프로젝트의 시크릿 유출 스캔을 요청합니다.
2. 에이전트가 코드베이스 또는 지정된 파일에 대해 ggshield secret scan을 실행합니다.
3. 탐지된 시크릿, 유형, 위치를 하이라이트한 읽기 쉬운 요약이 반환됩니다 — CLI 출력을 수동으로 파싱할 필요가 없습니다.

기존 리포지토리 감사든 개발 프로세스에 시크릿 스캔 추가든, 이 스킬이 무거운 작업을 처리합니다. 1Password 스킬과 함께 사용하여 완전한 시크릿 관리 워크플로우를 구축하세요.

ggshield Scanner 스킬 사전 요구 사항

ggshield Scanner 스킬을 설치하기 전에 다음을 확인하세요:

• OpenClaw가 설치되어 실행 중 (v1.0+)
• ggshield가 설치됨 — 공식 설치 가이드
• Python 3.9+ (pip/pipx로 설치하는 경우) 또는 독립 실행형 패키지 사용
• Git이 설치됨 (리포지토리 스캔용)
• clawhub CLI가 설치됨 — 설치 가이드

선호하는 방법으로 ggshield를 설치하세요:

# macOS (Homebrew)
brew install gitguardian/tap/ggshield

# 모든 플랫폼 (pipx — 권장)
pipx install ggshield

# 모든 플랫폼 (pip)
pip install --user ggshield

설정 확인:

ggshield --version

ggshield Scanner 스킬 설치 방법

ggshield Scanner 스킬을 한 줄의 명령으로 설치합니다:

npx clawhub@latest install ggshield-scanner

설치 확인:

clawhub list

설치된 스킬 목록에 ggshield-scanner가 표시되어야 합니다. 이 스킬은 ggshield가 PATH에서 사용 가능해야 합니다.

ggshield Scanner 스킬 구성

GitGuardian 인증

ggshield Scanner 스킬은 시크릿 탐지를 위해 GitGuardian API 키가 필요합니다. 두 가지 방법으로 인증할 수 있습니다:

대화형 로그인 (로컬 개발에 권장):

ggshield auth login

브라우저가 열리고 개인 액세스 토큰(PAT)이 자동으로 생성됩니다.

환경 변수 (CI/CD에 권장):

export GITGUARDIAN_API_KEY="your-api-key-here"

환경 변수 설정

| 변수 | 필수 여부 | 설명 | |------|----------|------| | GITGUARDIAN_API_KEY | 예 | GitGuardian 개인 액세스 토큰 | | GITGUARDIAN_INSTANCE | 아니오 | 온프레미스 GitGuardian 인스턴스 URL |

중요: API 키를 설정 파일에 하드코딩하지 마세요. 환경 변수 또는 1Password나 Bitwarden 같은 시크릿 매니저를 사용하세요.

Pre-commit 훅 설정

시크릿이 커밋되기 전에 차단합니다:

# 현재 리포지토리에 훅 설치
ggshield install --mode local

# 모든 리포지토리에 전역적으로 훅 설치
ggshield install --mode global

ggshield Scanner 스킬 사용 예시

1. 프로젝트 디렉토리에서 시크릿 스캔

사용자: "프로젝트 디렉토리에서 하드코딩된 시크릿이 있는지 스캔해줘"

에이전트가 ggshield secret scan path -r .을 실행하여 작업 디렉토리를 스캔하고, 탐지된 시크릿의 요약(파일 경로, 줄 번호, 시크릿 유형)을 반환합니다. 시크릿이 발견되지 않으면 코드가 안전함을 확인하는 보고서를 받습니다.

2. Git 리포지토리 히스토리 감사

사용자: "전체 git 히스토리에서 유출된 시크릿이 있는지 확인해줘"

에이전트가 ggshield secret scan repo .을 실행하여 리포지토리의 모든 커밋을 스캔합니다. 레거시 코드베이스 감사 또는 이전에 커밋된 시크릿이 적절히 로테이션 및 제거되었는지 확인하는 데 유용합니다.

3. 배포 전 Docker 이미지 스캔

사용자: "nginx:latest Docker 이미지에 시크릿이 있는지 스캔해줘"

에이전트가 ggshield secret scan docker nginx:latest를 실행하여 Docker 이미지의 모든 레이어를 검사합니다. 빌드 과정에서 컨테이너 이미지에 포함된 시크릿을 잡아냅니다 — 이는 프로덕션 환경에서 자격 증명 유출의 일반적인 원인입니다.

4. Pre-commit 보호 설정

사용자: "시크릿 커밋을 차단하는 pre-commit 훅을 설치해줘"

에이전트가 ggshield install --mode local을 실행하여 리포지토리에 git pre-commit 훅을 추가합니다. 이후 모든 커밋이 자동으로 스캔되며, 시크릿을 포함한 커밋은 리포지토리에 들어가기 전에 차단됩니다.

보안 및 모범 사례

ggshield Scanner 스킬 사용 시 다음 가이드라인을 따르세요:

• 기본적으로 읽기 전용 스캔을 사용하세요. 스킬은 스캔과 보고만 해야 합니다 — 각 발견 사항을 신중히 검토하지 않고 자동 수정을 하지 마세요.
• 확인 전에 검토하세요. 에이전트가 탐지된 시크릿의 제거 또는 로테이션을 제안할 때, 조치를 취하기 전에 발견 사항이 진양성인지 확인하세요.
• 노출된 시크릿은 즉시 로테이션하세요. ggshield가 리포지토리 히스토리에서 실제 시크릿을 탐지하면, 즉시 자격 증명을 로테이션하세요 — 커밋 삭제만으로는 충분하지 않습니다.
• pre-commit 훅을 활성화하세요. 탐지보다 예방이 중요합니다. ggshield install로 훅을 설정하여 시크릿이 버전 관리에 들어가기 전에 잡으세요.
• ggshield를 최신 상태로 유지하세요. 새로운 시크릿 패턴이 정기적으로 추가됩니다. pipx upgrade ggshield 또는 brew upgrade ggshield를 실행하세요.

일반적인 오류 해결

"Error: Invalid API key"

GitGuardian API 키가 없거나 만료되었습니다. ggshield auth login으로 재인증하거나 GITGUARDIAN_API_KEY 환경 변수가 올바르게 설정되어 있는지 확인하세요. GitGuardian 대시보드에서 토큰이 취소되지 않았는지 확인하세요.

"Error: ggshield command not found"

ggshield가 설치되지 않았거나 PATH에 없습니다. pipx install ggshield 또는 brew install gitguardian/tap/ggshield로 설치하세요. pip로 설치한 경우 Python 스크립트 디렉토리가 PATH에 포함되어 있는지 확인하세요.

"Error: Docker is not available"

Docker 이미지 스캔에는 실행 중인 Docker 데몬이 필요합니다. Docker Desktop 또는 Docker 서비스를 시작한 후 다시 시도하세요. 소스 코드만 스캔하려면 ggshield secret scan path 또는 ggshield secret scan repo를 사용하세요.