vault-radar scan git pre-receive 명령어

scan git pre-receive 명령어는 Git pre-receive 훅에서 콘텐츠를 스캔할 수 있게 해 주는 기능이에요. 서버 쪽에서 실행되기 때문에 정책을 중앙에서 강제하는 데 유용해요.

출처: 문서

본문

scan git pre-receive 명령어는 Git pre-receive 훅에서 콘텐츠를 스캔할 수 있게 해 주는 데 사용돼요.

Pre-receive 훅은 일부 Git 호스팅 서비스에서만 사용할 수 있어요. 여러분의 Git 호스팅 서비스에서 pre-receive 훅을 지원하는지 확인해 주세요. 예를 들어 GitHub Cloud는 pre-receive 훅을 지원하지 않지만, 셀프 호스팅 버전인 GitHub Enterprise는 pre-receive 훅을 지원해요.

Pre-receive 훅은 서버 쪽에서 실행되기 때문에 정책을 중앙에서 강제하는 데 사용할 수 있어요. 예를 들어 모든 코드 변경이 저장소에 수락되기 전에 비밀(secrets)을 스캔하도록 pre-receive 훅을 사용할 수 있어요.

대부분의 pre-receive 훅 구현에는 훅 실행이 Git 작업을 너무 오래 막지 않도록 타임아웃이 있어요. 훅 실행이 너무 오래 걸리면 작업이 중단되고 커밋이 서버에서 거부될 가능성이 높아요. scan git pre-receive 명령어는 사용자가 스캔하고자 하는 정확한 위험(risks) 집합을 설정하도록 설계됐어요. 위험 집합을 여러분의 사용 사례에 관련된 소수의 패턴으로 제한하는 것을 권장해요. 기본적으로 스캔은 비밀이 활성 상태인지 확인하지 않아요. 대부분의 활성 검사는 네트워크 호출을 필요로 해 전체 평가 시간을 크게 늘릴 수 있기 때문에, 스캔 실행이 너무 오래 걸리지 않도록 하기 위한 거예요.

더 큰 규모의 스캔에는 vault-radar CLI와 함께 pre-commit 훅을 사용하는 것을 고려해 보세요.

사전 요구사항(Prerequisites)

scan git pre-receive 명령어는 유효한 라이선스가 필요해요. 라이선스 생성에 대한 도움은 고객 지원 담당자에게 문의해 주세요.

라이선스는 다음의 방법으로 저장할 수 있어요:

환경 변수 VAULT_RADAR_LICENSE로 저장
VAULT_RADAR_LICENSE_PATH에 정의된 파일에 저장
기본 경로 $HOME/.hashicorp/vault-radar/vault-radar.hclic의 파일에 저장

추가로, vault-radar가 Git 저장소가 호스팅되는 서버에 설치되어 있어야 해요. 설치 지침은 여기에서 확인할 수 있어요.

설정(Configuration)

scan git pre-receive 명령어는 설정 파일을 사용해 구성돼요. 기본적으로 Vault Radar는 $HOME/.hashicorp/vault-radar/config.json 파일을 찾아요. 이 경로는 VAULT_RADAR_CONFIG_PATH 환경 변수를 설정 파일의 경로로 지정해 덮어쓸 수 있어요.

설정 파일 내용의 예시는 기본값을 사용해 아래와 같아요:

{
  "pre_receive_skip_activeness": true,
  "pre_receive_fail_severity":"medium",
  "pre_receive_risk_allowlist": []
}

메모: 이 명령어는 pre_receive_risk_allowlist가 스캔할 위험 유형의 비어 있지 않은 목록으로 설정되어야 해요. 위 예시는 결과적으로 0이 아닌 종료 코드로 종료될 거예요.

pre_receive_risk_allowlist 옵션의 값은 위험 유형(risk type) 또는 위험 설명(risk description)이 될 수 있어요. 예를 들어:

{
    "pre_receive_risk_allowlist": [
        "jwt_token",
        "GitHub personal access token"
    ]
}

설정에서 사용할 수 있는 지원 유형과 설명 목록은 Vault Radar 비밀 유형(secret types) 문서를 참조해 주세요.

설정 옵션

pre_receive_skip_activeness: true면 활성 검사를 건너뜀. 기본값은 true예요. 활성 검사를 활성화하면 평가 시간이 늘어날 가능성이 높으므로 false로 설정할 때는 주의하세요.
pre_receive_fail_severity: 스캔을 실패하게 만드는 위험의 최소 심각도(severity)를 지정해요. 기본값은 medium이에요. 심각도에 대한 추가 문서는 여기에서 확인할 수 있어요.
pre_receive_risk_allowlist: 스캔할 위험 유형 또는 설명 목록을 지정해요. 스캔은 이 목록에 있는 위험만 스캔해요. 목록이 비어 있으면 명령어가 0이 아닌 종료 코드로 종료돼요.

사용법

이 명령어는 pre-receive 훅에서 호출될 것으로 예상돼요.

$ vault-radar scan git pre-receive

로컬에서 테스트하기

pre-receive 훅은 보통 중앙 Git 서버에서 실행되기 때문에, 프로젝트에서 작업하는 다른 사람들을 방해하지 않고 변경 사항이 잘 동작할지 확신을 갖는 것이 중요할 때가 많아요. 다행히 pre-receive 훅을 저장소에서 로컬로 테스트하는 것이 가능해요.

이 작업은 기존 저장소에서 하거나 새 bare 저장소를 만들어서 할 수 있어요. 예시에서는 pre-receieve-test라는 디렉터리 안에 저장소를 만들 거예요.

테스트할 디렉터리를 만든다. ``` $ mkdir pre-receieve-test && cd pre-receieve-test
새 bare 저장소를 만든다. ``` $ git init --bare repo.git
~/hashicorp/vault-radar/config.json이 없으면 만든다. 예시에서는 JWT 토큰만 확인하는 간단한 설정을 사용해요: ``` { "pre_receive_risk_allowlist": [ "jwt_token" ] }
프로젝트의 pre-receive 훅을 설정하고 vault-radar scan pre-receive 명령어를 호출하도록 만든다. ``` $ echo "exec vault-radar scan git pre-receive" > repo.git/hooks/pre-receive $ chmod +x repo.git/hooks/pre-receive
```
> 메모: 예시에서는 `vault-radar`가 PATH에 있다고 가정해요. 없다면 `vault-radar` 바이너리의 전체 경로를 지정할 수 있어요.
```
그런 다음 저장소를 클론한다. ``` $ git clone repo.git repo
클론에서 새 파일을 만들고 커밋한다. 예시에서는 jwt.io의 JWT 토큰이 담긴 jwt.txt라는 파일을 만들어요: ``` $ cd repo $ echo 'eyJhbG...sw5c' >> jwt.txt $ git add jwt.txt $ git commit -m "Add jwt token"
마지막으로 변경 사항을 원본 저장소로 다시 푸시한다. ``` $ git push origin main

모든 것이 올바르게 설정됐다면, JWT 토큰 때문에 커밋이 거부됐다는 vault-radar의 출력이 있어야 해요.

git push origin main
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 12 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 380 bytes | 380.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: error: HC001: Repository rule violations found
remote:
remote: - Hashicorp Vault Radar PUSH PROTECTION
remote:  —————————————————————————————————————————
remote:    Resolve the following violations before pushing again
remote:
remote:    - Push cannot contain secrets
remote:
remote:      (?) Learn how to resolve a blocked push
remote:      https://developer.hashicorp.com/hcp/docs/vault-radar/cli/scan/git/pre-receive
remote:
remote:
remote:     —— Generic JWT token ———————————————————————————————————————————
remote:        - ref:      refs/heads/main
remote:          commit:   94b08e4f24065b5c435199d363932d42014f247d
remote:          path:     jwt.txt:1
remote:          severity: medium
remote:
remote:
remote:
To /Users/someone/pre-receive-test/repo.git
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to '/Users/someone/pre-receive-test/repo.git'

Git 서버에서 pre-receive 훅을 정확히 구성하는 방법은 제공자마다 다릅니다. pre-receive 훅을 구성하는 방법에 대한 자세한 내용은 여러분이 사용하는 특정 Git 서버의 문서를 참조해 주세요.

더 알아보기 (Learn more)

GitHub pre-receive 훅 설정 — GitHub Enterprise Server에서 훅을 구성해요.
Bitbucket pre-receive 훅 — Bitbucket Server에서 훅을 구성해요.
GitLab pre-receive 훅 — GitLab에서 훅을 구성해요.
CLI 시작하기 — 주요 명령어 목록을 둘러봐요.