AI 에이전트 코딩 점검 도구 4가지: gitleaks와 zizmor부터

 ・ 8분

photo by John Lee(https://unsplash.com/@john_artifexfilm?utm_source=templater_proxy&utm_medium=referral) on Unsplash

AI 에이전트에게 코딩을 맡기면 커밋도, GitHub Actions 워크플로도, 셸 스크립트도 에이전트가 쓰게 되죠. 이 글에서는 그런 환경에서 제가 쓰는 AI 에이전트 코딩 점검 도구 4가지(gitleaks, zizmor, actionlint, ShellCheck)가 각각 무엇을 잡는지, 어떻게 설정했는지, 붙이다가 겪은 실패까지 정리했어요.

저는 에이전트 여러 개가 동시에 PR을 올리는 환경에서 일해요. 목표만 주고 에이전트가 알아서 일하게 하다 보니, 사람이 모든 줄을 읽고 푸시하던 때와는 사정이 달라졌어요. 사람 눈 대신 매번 같은 기준으로 도는 검사가 필요해졌거든요.

에이전트 코딩에 점검 도구가 필요한 이유#

네 도구는 잡는 대상이 서로 달라요. 겹치는 부분이 거의 없어서 하나로 나머지를 대신할 수 없어요.

도구 잡는 것 제가 돌리는 곳
gitleaks 커밋에 들어간 키, 토큰 같은 시크릿 푸시 전 훅, PR, 매일
zizmor GitHub Actions 워크플로의 보안 문제 워크플로 저장소의 PR
actionlint 워크플로 문법과 표현식 오류 워크플로 저장소의 PR
ShellCheck 셸 스크립트의 따옴표, 변수 같은 실수 PR에서 바뀐 스크립트만

네 개 모두 내 컴퓨터에서 도는 명령줄 도구예요. 로그인도 API 키도 필요 없고 호출 횟수 제한도 없어요. 이 점이 왜 중요한지는 gitleaks 이야기에서 나와요.

설치는 Homebrew로 한 번에 돼요. 이 글은 gitleaks 8.30.1, zizmor 1.32.0, actionlint 1.7.12, ShellCheck 0.11.0 기준이에요.

brew install gitleaks zizmor actionlint shellcheck

gitleaks: 푸시 전과 CI에서 시크릿 스캔하기#

gitleaks는 git 커밋을 훑어서 API 키나 토큰처럼 보이는 문자열을 찾아요. 저는 두 군데에서 돌려요. 푸시 직전의 pre-push 훅과 CI예요.

pre-push 훅으로 푸시 전에 막기#

전역 pre-push 훅이 이번에 푸시하는 커밋만 검사해요. 핵심은 이 한 줄이에요.

# origin/main에 없는 커밋만 검사하고, 값은 가려서 출력해요
gitleaks git --log-opts="origin/main..HEAD" --redact --verbose --exit-code 42 .
  • --redact는 찾은 값을 가려요. 터미널 로그에 시크릿이 다시 찍히면 안 되니까요.
  • --exit-code 42는 "시크릿을 찾았다"는 종료 코드를 따로 정해요. 기본값은 1인데, gitleaks가 그냥 죽었을 때도 1이라 둘을 구분할 수 없거든요.

훅은 시크릿을 찾았을 때만 푸시를 막아요. gitleaks가 설치돼 있지 않거나 죽으면 경고만 하고 통과시켜요. 도구 문제로 푸시 전체가 멈추는 것보다 낫다고 봤어요.

대신 한계는 알고 써야 해요.

  • git push --no-verify를 쓰면 훅을 건너뛰어요.
  • 저장소가 자체 core.hooksPath를 쓰면(husky 등) 전역 훅이 아예 돌지 않아요.
  • 도구가 죽어서 통과한 푸시는 검사받지 않은 푸시예요.

그래서 훅은 실수를 잡아주는 안전망이지 보장이 아니에요. 그래서 CI에서 한 번 더 검사해요.

ggshield에서 gitleaks로 바꾼 이유#

처음에는 훅이 GitGuardian의 ggshield를 먼저 부르고, 응답이 없을 때만 gitleaks를 썼어요. 그런데 GitGuardian 무료 한도는 30일에 10,000번 호출이에요. 이 한도를 다 쓴 뒤로는 푸시할 때마다 이 문구만 찍혔어요.

no more API calls available

어차피 매번 gitleaks가 대신 검사하고 있었던 거예요. 그래서 훅에서 ggshield 호출을 빼고 gitleaks만 남겼어요. 로컬에서 도는 gitleaks는 로그인도 호출 한도도 없어요.

CI에서는 PR 커밋과 전체 히스토리를 따로 검사하기#

CI에서는 검사 범위를 둘로 나눴어요.

  1. PR — PR에 든 커밋(base..HEAD)을 검사해요. 커밋 단위로 보기 때문에 PR 안에서 넣었다가 지운 시크릿도 잡혀요.
  2. 매일 한 번 — 기본 브랜치와 태그의 전체 히스토리를 검사해요.

훅과 반대로 CI는 실패 쪽으로 닫아요. 시크릿이 나오거나, gitleaks 버전이 다르거나, 도구가 죽거나, 결과 파일이 없으면 전부 실패예요. "검사를 못 했다"가 "깨끗하다"로 읽히면 안 되니까요.

오탐은 한 줄짜리 지문(fingerprint)으로만 예외 처리해요. 경로나 규칙을 통째로 빼지 않아요.

# 형식: <커밋>:<파일>:<규칙>:<줄>
echo '<commit>:<file>:<rule>:<line>' >> .gitleaksignore

여기서 한 번 걸렸어요. squash merge를 하면 줄은 그대로인데 커밋 SHA가 바뀌어요. PR에서 등록한 지문은 기본 브랜치의 커밋에는 맞지 않아서, 같은 오탐을 두 번 등록해야 했어요.

진짜 시크릿이 잡혔을 때#

에이전트에게 정해둔 규칙은 세 가지예요.

  • 값을 PR, 이슈, 로그 어디에도 붙여넣지 않아요. 키 이름만 알려요.
  • 파일에서 지웠다고 끝이 아니에요. 히스토리에 남은 키는 여전히 살아 있어요.
  • 키 교체(rotation)와 히스토리 수정은 사람이 해요. 에이전트가 하지 않아요.

zizmor: GitHub Actions 워크플로 보안 점검#

zizmor는 GitHub Actions 워크플로 파일을 읽어서 보안 문제를 찾아주는 정적 분석 도구예요.

이 블로그 저장소에 돌려보면 이런 결과가 나와요. 가장 많이 나온 지적은 액션을 태그로 참조한 것이에요.

zizmor --offline .github/workflows
error[unpinned-uses]: unpinned action reference
  --> .github/workflows/ci.yml:19:15
   |
19 |         uses: pnpm/action-setup@v6
   |               ^^^^^^^^^^^^^^^^^^^^ action is not pinned to a hash (required by blanket policy)
 
...
 
28 findings (9 suppressed, 1 safe fixes, 2 unsafe fixes): 0 informational, 2 low, 0 medium, 17 high

워크플로 세 개에서 high가 17건이에요. unpinned-uses 말고도 pull_request_target 같은 위험한 트리거(dangerous-triggers), checkout이 남기는 자격 증명(artipacked)을 짚어줘요. --offline을 붙이면 네트워크와 토큰 없이 로컬 파일만 봐요.

서드파티 액션을 커밋 SHA로 고정하는 이유#

@v6 같은 태그는 나중에 다른 커밋으로 옮겨질 수 있어요. 제 경우에는 CI 러너가 개발 머신이기도 해서, 오염된 액션이 실행되면 그 머신의 자격 증명에 닿을 수 있어요. 그래서 최근에 워크플로 저장소의 점검에 zizmor를 넣고 정책을 이렇게 정했어요.

# .github/zizmor.yml
rules:
  unpinned-uses:
    config:
      policies:
        '*': hash-pin # 서드파티 액션은 40자 커밋 SHA로 고정
        actions/*: ref-pin # GitHub 소유 액션은 태그 허용 (Dependabot이 갱신)

고정한 액션은 이렇게 써요. 뒤의 주석으로 어떤 버전인지 남겨둬요.

- uses: subosito/flutter-action@1a449444c387b1966244ae4d4f8c696479add0b2 # v2.23.0

기존 지적은 기준선으로 두고 새 파일부터 막기#

처음 돌리면 지적이 쏟아져요. 전부 고칠 때까지 기다리면 영영 못 켜요. 그래서 CI에서는 medium 이상만 실패시키고, 이미 있던 지적은 파일 단위 ignore로 적어뒀어요.

zizmor --offline --no-progress --min-severity medium --config .github/zizmor.yml .github

ignore에 적힌 파일은 고칠 때 그 줄을 지워요. 새로 만든 파일은 예외 없이 검사받아요.

actionlint: 워크플로 문법과 표현식 오류 잡기#

actionlint는 워크플로 YAML의 문법, 표현식, 러너 라벨 오류를 잡아요. zizmor가 "위험한가"를 본다면 actionlint는 "돌아가긴 하는가"를 봐요.

인자 없이 실행하면 가장 가까운 .github/workflows를 찾아 전부 검사해요. ShellCheck이 설치돼 있으면 run: 안의 셸 스크립트까지 같이 봐줘요. 이 블로그 저장소에서는 이게 나왔어요.

.github/workflows/next.yml:47:9: shellcheck reported issue in this script: SC2086:info:1:41: Double quote to prevent globbing and word splitting [shellcheck]
   |
47 |         run: echo "store-path=$(pnpm store path)" >> $GITHUB_OUTPUT

$GITHUB_OUTPUT에 따옴표가 없다는 지적이에요.

설정하면서 알아둘 게 두 가지 있었어요.

  • self-hosted 러너 라벨 — 직접 붙인 라벨은 actionlint가 몰라서 오류로 봐요. .github/actionlint.yaml에 알려줘야 해요.
  • ShellCheck 스타일 지적 — 기존 워크플로에 SC2086 같은 지적이 많으면 켜는 순간 전부 실패해요. 저는 CI에서 actionlint -shellcheck=로 ShellCheck 연동을 끄고, 워크플로 오류만 막아요.
# .github/actionlint.yaml
self-hosted-runner:
  labels:
    - my-runner

그리고 actionlint가 통과했다고 워크플로가 맞게 동작하는 건 아니에요. 문법이 맞아도 실행 시점에야 드러나는 오류는 actionlint와 ShellCheck 둘 다 못 잡아요. 그런 부분은 따로 테스트를 둬요.

ShellCheck: 바뀐 셸 스크립트만 엄격하게 검사하기#

ShellCheck은 셸 스크립트의 따옴표 누락, 안 쓰는 변수 같은 실수를 찾아요. 에이전트는 자동화 스크립트를 많이 쓰니까 효과가 커요.

저는 actionlint와 반대 전략을 썼어요. 전체를 느슨하게 보는 대신 PR에서 바뀐 파일만 보고, 경고가 하나라도 있으면 실패예요. 예외 목록도 기준선도 없어요. 경고가 있는 파일을 건드리면 그 경고를 고쳐야 통과해요.

# 파일마다 따로 실행해요
shellcheck --norc --format=json -- scripts/deploy.sh

붙이면서 배운 것들이에요.

  • 파일을 하나씩 넘겨요. 여러 스크립트를 한 번에 넘기면 다른 입력에 따라 source나 안 쓰는 변수 진단이 빠질 수 있어요.
  • 확장자가 없는 파일도 봐요. .sh, .bash뿐 아니라 셔뱅(shebang)이 셸인 파일도 대상이에요.
  • zsh는 명시적으로 빼요. ShellCheck은 zsh를 지원하지 않아서, 경로와 이유를 적은 제외 목록을 따로 둬요.
  • 대상 목록은 git ls-files로 만들어요. 기본 검색 도구는 ignore 규칙에 걸린 파일을 숨겨서, 추적 중인 파일이 목록에서 빠질 수 있어요.

점검 도구를 붙이다 겪은 실패 세 가지#

검사가 "통과"로 보이는데 사실은 돌지 않은 경우가 제일 위험했어요.

gitignore의 secret* 패턴에 스캐너 파일이 빠졌어요#

스캐너 스크립트 이름에 secret을 넣었더니, 전역 gitignore의 secret* 패턴에 걸려서 git add에서 조용히 빠졌어요. 워크플로는 없는 파일을 부르게 됐죠.

지금은 파일 이름을 gitleaks_scan.py처럼 도구 이름으로 짓고, 커밋 직후 git ls-files로 새 파일이 들어갔는지 확인해요.

PR head를 checkout해서 "Start directory is not importable"#

보안 워크플로가 PR의 head 커밋을 checkout하게 했더니, 스캐너를 추가하기 전에 갈라진 브랜치에는 스캐너 디렉터리 자체가 없었어요. 테스트 단계가 이 오류로 죽고, ShellCheck과 gitleaks 단계는 실행되지 않았어요.

Start directory is not importable

해결은 checkout에 ref를 지정하지 않는 거였어요. pull_request 이벤트는 기본으로 베이스와 합친 merge 커밋을 받아요. 그러면 베이스에 있는 스캐너와 PR의 변경이 함께 들어와요.

테스트용 가짜 키가 탐지되지 않았어요#

gitleaks가 제대로 잡는지 확인하는 회귀 테스트에 공식 문서의 예제 키를 썼어요. 그런데 그런 예제 키는 gitleaks 기본 규칙에서 예외라 탐지되지 않았어요. 테스트가 처음부터 아무것도 확인하지 못한 거예요.

지금은 규칙이 요구하는 문자 집합에 맞춘 합성 키를 만들고, 먼저 탐지되는지(실패하는지) 확인한 뒤에 테스트로 써요.

네 도구에 똑같이 적용한 원칙#

  1. 버전을 고정해요. 러너에 정해진 버전이 없거나 다르면 건너뛰지 않고 실패시켜요.
  2. 로컬은 열고, CI는 닫아요. 푸시 전 훅은 도구가 죽으면 통과시키고, CI는 도구가 죽으면 실패시켜요.
  3. 기존 지적을 다루는 방법을 먼저 정해요. 바뀐 파일만 보기(ShellCheck), 심각도 기준과 파일 단위 기준선(zizmor), 정확한 지문(gitleaks) 중에서 골라요.
  4. 출력에 시크릿을 남기지 않아요. 값은 가리고, 규칙 이름과 파일, 줄, 커밋만 남겨요.
  5. 외부 API 한도에 기대지 않아요. 한도를 다 쓰면 검사 대신 경고 문구만 남아요.

에이전트에게 일을 완료 조건이 있는 이슈로 쪼개서 맡기는 것만큼, 그 결과물을 매번 같은 기준으로 걸러주는 장치도 필요해요. 네 개를 한 번에 붙이기 부담스럽다면 gitleaks pre-push 훅 하나부터 시작해보세요. gitleaks를 설치하고, 전역 pre-push 훅에서 위 명령을 부르게 하는 것부터 해볼 수 있어요.


You can do it if you believe you can!

— Napoleon Hill


다른 글
AI 에이전트 워크플로우: 아이디어를 완료 조건 있는 이슈로 쪼개기 커버 이미지
 ・ 6분

AI 에이전트 워크플로우: 아이디어를 완료 조건 있는 이슈로 쪼개기

AI 에이전트 자동화 사례 4가지, 대화 대신 목표 맡기기 커버 이미지
 ・ 7분

AI 에이전트 자동화 사례 4가지, 대화 대신 목표 맡기기

프론트엔드 개발환경 기초 6가지, 2026년 기준으로 다시 정리 커버 이미지
 ・ 11분

프론트엔드 개발환경 기초 6가지, 2026년 기준으로 다시 정리