Terraform 레포에 pre-commit과 Trivy를 붙이는 방법 (macOS / zsh)

Terraform 레포에 pre-commit과 Trivy를 붙이는 방법 (macOS / zsh)

Terraform으로 인프라를 관리하다 보면, PR마다 같은 실수가 반복됩니다. 포맷이 어긋나 있거나, validate를 안 돌린 채 올라오거나, 보안 설정 오류를 나중에야 발견하는 경우죠.

이 글에서는 macOS + zsh 환경에서 pre-commit으로 Terraform 품질 검사를 자동화하고, Trivy로 IaC 보안 스캔까지 로컬에서 돌리는 방법을 정리합니다.

---

왜 pre-commit + Trivy인가

도구	역할
pre-commit	git commit 직전에 훅(hook)을 실행해 공통 규칙을 강제
pre-commit-terraform	fmt, validate, docs, tflint, trivy 등 Terraform 전용 훅 묶음
Trivy	Terraform 설정의 misconfiguration(보안 설정 오류) 스캔

로컬에서 1차로 걸러두면 리뷰어 부담이 줄고, CI에서 같은 검사를 다시 돌릴 때도 diff가 작아집니다.

---

사전 준비 (zsh / macOS)

echo $SHELL    # /bin/zsh
which brew     # Homebrew 필요

Homebrew로 필요한 CLI를 설치합니다.

brew install pre-commit trivy tflint terraform-docs terraform

Apple Silicon Mac에서 brew를 찾지 못하면 ~/.zshrc에 아래를 추가합니다.

eval "$(/opt/homebrew/bin/brew shellenv)"

설치 확인:

pre-commit --version
trivy --version
tflint --version
terraform-docs --version
terraform version

---

1. .pre-commit-config.yaml 작성

레포 루트에 설정 파일을 둡니다. Terraform 훅은 pre-commit-terraform을 사용합니다.

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.99.5
    hooks:
      - id: terraform_fmt
      - id: terraform_validate
      - id: terraform_docs
      - id: terraform_tflint
      - id: terraform_trivy
        args:
          - --args=--format
          - --args=json
          - --args=--output
          - --args=trivy-results.json
          - --args=--severity
          - --args=HIGH,CRITICAL
          - --args=--exit-code
          - --args=0

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
        args: [--allow-multiple-documents]
      - id: check-added-large-files

훅별 역할

• terraform_fmt — terraform fmt로 코드 스타일 통일
• terraform_validate — 문법·구조 검증
• terraform_docs — README 등 문서 자동 생성/갱신
• terraform_tflint — Terraform 린트 (모범 사례·오류 패턴)
• terraform_trivy — Terraform 보안 misconfiguration 스캔

특정 디렉터리(예: 자동 생성 코드)를 빼려면 훅에 exclude: ^path/to/skip/를 추가하면 됩니다.

---

2. 훅 등록

레포 루트에서 한 번만 실행합니다.

cd /path/to/your-terraform-repo
pre-commit install

이후 git commit할 때마다 설정된 훅이 자동 실행됩니다.

---

3. 수동 실행

커밋 전에 전체 검사를 돌리고 싶을 때:

pre-commit run --all-files

특정 훅만:

pre-commit run terraform_fmt --all-files
pre-commit run terraform_validate --all-files
pre-commit run terraform_trivy --all-files

훅 버전 업데이트:

pre-commit autoupdate

---

4. Trivy 결과 확인

위 설정대로라면 스캔 결과가 레포 루트의 trivy-results.json에 저장됩니다. 이 파일은 보통 .gitignore에 넣어 커밋하지 않습니다.

trivy-results.json

jq로 HIGH/CRITICAL 항목만 빠르게 볼 수 있습니다.

jq '.Results[]?.Misconfigurations[]?
  | select(.Severity=="CRITICAL" or .Severity=="HIGH")
  | {Severity, Title, Resource: .CauseMetadata.Resource}' \
  trivy-results.json 2>/dev/null | head

macOS에서는 Finder로 열어도 됩니다.

open trivy-results.json

---

5. 설계 포인트: --exit-code 0 vs 1

예시 설정에서 Trivy는 --exit-code 0입니다. 취약점이 있어도 커밋 훅 자체는 실패하지 않고, 결과만 파일로 남깁니다.

정책	--exit-code	적합한 상황
알림만 (로컬 개발)	0	기존 레거시가 많을 때, 점진적 개선
커밋 차단	1	팀이 HIGH/CRITICAL zero-tolerance일 때

PR/CI에서 강하게 막고 싶다면:

1. .pre-commit-config.yaml에서 --exit-code를 1로 변경하거나
2. GitHub Actions 등 CI job에서 trivy config를 별도 실행

로컬은 부드럽게, CI는 엄격하게 — 이런 이중 구조도 흔합니다.

---

6. 팀에 도입할 때 체크리스트

• pre-commit install을 README 빠른 시작에 포함
• terraform_docs가 README를 바꾸므로, 문서 diff도 리뷰 대상인지 합의
• trivy-results.json을 .gitignore에 추가
• CI에서 pre-commit run --all-files 또는 동등한 검사 실행
• Trivy 실패 시 조치 기준(HIGH/CRITICAL SLA) 문서화

---

7. 자주 겪는 이슈

terraform_validate가 provider를 못 찾는다

terraform init이 선행되어야 합니다. CI에서는 init 후 validate를 돌리세요.

Trivy가 느리다

처음 실행은 DB 다운로드 때문에 시간이 걸립니다. 이후에는 캐시가 쌓여 빨라집니다.

pre-commit이 특정 YAML만 실패한다

Kubernetes manifest처럼 multi-document YAML은 check-yaml에 --allow-multiple-documents가 필요합니다. 해당 경로만 exclude하는 것도 방법입니다.

---

마무리

Terraform 레포에 pre-commit을 붙이면 포맷·검증·린트·문서·보안 스캔을 커밋 직전에 한 번에 돌릴 수 있습니다. macOS/zsh에서는 Homebrew로 도구를 설치하고, 레포 루트에 .pre-commit-config.yaml 하나 두면 팀 온보딩도 단순해집니다.

Trivy는 “완벽한 보안”을 대신해 주지는 않지만, 알려진 misconfiguration을 일찍 보여 주는 1차 방어선으로는 충분히 가치가 있습니다. 로컬에서는 결과를 수집하고, CI에서 정책을 강화하는 조합을 추천합니다.

---

작성 환경: macOS, zsh, Homebrew. pre-commit-terraform v1.99.5, pre-commit-hooks v5.0.0 기준.