Claude Code로 실무형 보안 감사를 하는 방법

보안 감사를 AI에게 통째로 맡기지 않는다

Claude Code는 보안 감사 속도를 높여 줍니다. route, PR diff, dependency, log, 환경 변수, CI 설정을 읽고 반복되는 review 항목을 checklist로 정리할 수 있습니다. 실제 보안 위험은 한 파일에 모여 있지 않고 인증 middleware, 권한 검사, 결제 job, webhook, secret, log에 흩어져 있기 때문에 이런 정리가 큰 도움이 됩니다.

하지만 “보안 확인해 줘”라고만 묻고 답을 그대로 믿으면 위험합니다. 보안 감사는 범위, 자산, 위협, 통제, 증거, 남은 위험을 명확히 하는 작업입니다. Claude Code는 조사와 정리를 도와주는 reviewer이지, 비즈니스 위험과 공개 범위를 최종 결정하는 책임자가 아닙니다.

이 글에서는 Claude Code로 실무에 쓸 수 있는 보안 감사를 진행하는 흐름을 정리합니다. 범위 정의, 자산 inventory, threat model, dependency review, auth/session review, secrets review, input validation, logging/PII, CI gate, evidence receipt를 다룹니다. 외부 기준으로는 OWASP Top 10, OWASP ASVS, NIST SSDF, GitHub secret scanning을 함께 보면 좋습니다.

먼저 범위를 고정한다

첫 산출물은 수정 코드가 아니라 감사 brief입니다. 범위는 Claude Code가 무엇을 볼지, 무엇을 바꾸지 말아야 할지, 어떤 command를 실행할 수 있는지, 완료 기준이 무엇인지를 정합니다. 범위가 없으면 눈에 띄는 파일만 보고 admin route, billing flow, background job, deploy script, CI secret를 놓치기 쉽습니다.

아래 template을 그대로 붙여 넣고 빈칸을 채운 뒤 시작하세요.

# Security Audit Brief

## Goal
- Release 전에 authentication, authorization, secrets, input validation, logging, dependency의 큰 위험을 찾는다
- 수정 제안뿐 아니라 증거와 남은 위험을 남긴다

## Scope
- Repository:
- Branch or PR:
- Feature or workflow:
- Claude Code가 읽어도 되는 directory:
- Claude Code가 바꾸면 안 되는 directory:
- 실행 가능한 command:

## Priority areas
- Authentication and session handling
- Authorization and roles
- Input validation and output encoding
- Secrets and environment variables
- Dependencies and licenses
- Logs, PII, and audit events
- Release를 막아야 하는 CI 조건

## Completion criteria
- Findings를 risk register에 기록한다
- 재현에 필요한 최소 정보만 남긴다
- 실제 secret, customer data, 위험한 exploit 절차를 쓰지 않는다
- command, 결과, 제외 범위, human-review 항목을 evidence receipt에 기록한다

brief를 준 뒤에는 바로 수정시키지 말고 먼저 지도를 만들게 합니다. 예를 들어 “route, auth middleware, external API, environment variable, logging point, CI job, high-risk file을 나열하고 아직 코드는 수정하지 마세요”라고 요청합니다. 이 단계가 있어야 사람이 누락된 영역을 발견할 수 있습니다.

자산 inventory와 threat model을 만든다

보안은 보호할 자산을 알아야 의미가 있습니다. 자산은 사용자 데이터, 결제 상태, API key, admin console, audit log, uploaded file, support message, analytics data처럼 유출, 변조, 중단되면 곤란한 것입니다. Threat model은 누가 어떤 entry point로 들어와 무엇을 노리는지, 어떤 control이 막아야 하는지 정리한 작은 지도입니다.

| Asset | Stored in | Entry point | Likely threat | Required control | Owner |
| --- | --- | --- | --- | --- | --- |
| User email address | users table | signup, admin | unauthorized access, log leakage | authorization, PII masking, audit log | backend |
| Billing status | billing table, Stripe | webhook, admin | tampering, duplicate processing | signature verification, idempotency, role checks | backend |
| API keys | env, secret manager | CI, runtime | repository leak, log exposure | secret scanning, rotation, least privilege | platform |
| Admin console | /admin | browser | privilege escalation | MFA, admin role, operation logs | product |

이 표를 Claude Code에 주고 trust boundary와 test를 추가하게 합니다. Trust boundary는 믿을 수 있는 영역과 믿으면 안 되는 입력의 경계입니다. Browser input, webhook, uploaded CSV, Markdown, filename, third-party API response는 모두 검증 전까지 신뢰하지 않는 값으로 봅니다.

Claude Code에 구체적인 review lane을 준다

Dependency review는 package.json, lockfile, Docker image, GitHub Actions, runtime version, transitive dependency를 함께 봅니다. npm audit 결과만으로 끝내지 말고 production에서 실제로 도달 가능한 위험인지, dev dependency noise인지, upgrade가 breaking change를 만들지, 어떤 test가 통과해야 하는지 나누게 합니다.

Auth와 session review는 login, logout, password reset, MFA, OAuth, cookie flag, session expiration, CSRF protection, server-side authorization을 확인합니다. “로그인했는가”와 “이 작업을 해도 되는가”는 다른 질문입니다. Admin API, billing action, file download, route parameter의 user id, 재전송 가능한 webhook에서 authorization gap이 자주 생깁니다.

Secrets review는 .env, CI secrets, sample config, README snippet, log, screenshot, test fixture를 포함해야 합니다. Claude Code가 실제 secret 값을 chat에 쓰게 하면 안 됩니다. 의심되는 secret을 찾으면 file path, secret type, rotation 필요 여부, owner만 기록하고 값은 redaction합니다. GitHub를 쓰면 secret scanning과 push protection이 켜져 있는지도 확인합니다.

Input validation review는 데이터가 어디서 들어와 어디에 저장되고 렌더링되며 외부로 전송되는지 추적합니다. 위험한 payload 생성을 요청하지 말고 boundary validation, normalization, escaping, type check, test case를 제안하게 합니다. 초보자에게는 취약점 이름을 외우는 것보다 data flow를 따라가는 방식이 더 안전합니다.

Logging과 PII review는 email, name, address, token, cookie, auth header, payment ID, support text가 log에 들어가는지 확인합니다. 개발 중 console.log가 production log로 남으면 retention과 유출 위험이 됩니다. Log는 장애 조사와 audit event에 필요한 최소 필드만 남겨야 합니다.

실무에서 자주 쓰는 네 가지 use case

첫 번째는 release 전 SaaS 감사입니다. Billing, invite, organization setting, admin feature를 출시하기 전에 Claude Code에 PR diff, migration, route, webhook handler, test, CI를 읽게 합니다. 목적은 “안전하다”는 문장을 얻는 것이 아니라 release meeting에서 논의할 risk register를 만드는 것입니다.

두 번째는 GitHub repository handoff audit입니다. 인수한 repo에서 위험한 지식은 README보다 deploy script, CI secrets, environment name, manual runbook, owner 없는 directory에 남아 있습니다. Claude Code에게 첫 주 handoff checklist를 만들게 하면 어떤 key를 rotate할지, 어떤 CI gate가 없는지, 어느 부분에 human owner review가 필요한지 빨리 볼 수 있습니다.

세 번째는 incident follow-up audit입니다. 장애나 유출 의심 뒤에는 원인 한 줄만 고치고 끝내면 재발합니다. Claude Code에 유사 pattern 검색, log PII 확인, regression test, CI gate, 운영 문서 update를 요청합니다. 외부 공개 문서는 영향과 조치 중심으로 쓰고, 위험한 재현 절차는 제한된 장소에 둡니다.

네 번째는 AI-generated PR security review입니다. AI가 만든 코드는 보기 좋지만 authorization, audit log, error handling, test가 빠질 수 있습니다. Claude Code에 “이 diff의 attack surface, permission, secrets, personal data, dependency change, CI coverage만 보라”고 좁게 요청하면 generic review보다 실질적인 결과가 나옵니다.

Risk register와 evidence receipt를 남긴다

Finding은 severity만으로 부족합니다. 영향, 근거, 권장 조치, 담당자, 상태, 미확인 항목이 함께 있어야 release 판단에 쓸 수 있습니다.

| ID | Risk | Impact | Evidence | Recommended action | Priority | Status | Owner |
| --- | --- | --- | --- | --- | --- | --- | --- |
| SEC-001 | Missing authorization on admin API | Another user's data may be changed | routes/admin.ts has no role check | Add middleware and regression tests | High | Open | backend |
| SEC-002 | Webhook logs include email | Unnecessary PII retention | logs/webhook-sample.txt | Mask email and reduce retention | Medium | Open | platform |

Evidence receipt는 감사를 흩어진 chat log로 끝내지 않게 해 줍니다. 짧아도 무엇을 확인했고 무엇을 제외했는지 보여야 합니다.

# Security Audit Evidence Receipt

- Target:
- Date:
- Reviewer:
- Scope provided to Claude Code:
- Commands executed:
- Files or directories inspected:
- High-risk findings:
- Fixed items:
- Skipped or out-of-scope areas:
- Decisions requiring human review:
- Release recommendation:

PR review checklist

PR에서는 같은 항목을 짧게 붙여 넣을 수 있어야 합니다. AI-generated change를 볼 때 특히 유용합니다. Style 논쟁보다 위험과 evidence를 먼저 보게 만들기 때문입니다.

## Security PR Review

- [ ] Scope is clear and no unrelated files are changed
- [ ] Authenticated users cannot access another user's data
- [ ] Admin or billing actions require explicit authorization
- [ ] Inputs are validated at the boundary
- [ ] Outputs are escaped or rendered safely
- [ ] No secrets, tokens, cookies, or PII are printed to logs
- [ ] Dependency changes have a reason and test evidence
- [ ] Errors do not reveal internals
- [ ] CI includes lint, tests, typecheck, and security-relevant checks
- [ ] Risk register and evidence receipt are updated

Command checklist

Project마다 command는 다르지만 Node 또는 TypeScript repo라면 아래에서 시작할 수 있습니다. Claude Code에는 실행 전에 command 목적을 설명하고 실패하면 멈춰서 원인을 요약하라고 지시합니다.

git status --short
npm ci
npm audit --audit-level=moderate
npm run lint
npm run typecheck
npm test
rg -n "TODO|FIXME|console\\.log|process\\.env|localStorage|innerHTML|dangerouslySetInnerHTML" src
git diff --check

rg 결과는 단서이지 판정이 아닙니다. process.env는 올바른 사용일 수 있고, innerHTML도 sanitize되어 있으면 허용될 수 있습니다. Claude Code에는 evidence, assumption, confirmation step을 구분하라고 요청하세요.

흔한 실패와 함정

가장 흔한 실패는 prompt가 모호한 것입니다. “보안 봐줘”라고 쓰면 Claude Code가 얕은 일반론을 내놓기 쉽습니다. 좋은 prompt는 scope, asset, release deadline, allowed command, high-risk flow, output format을 포함합니다. 증거 없는 자신감보다 “검토하지 않은 영역”을 명확히 쓴 report가 더 가치 있습니다.

두 번째 실패는 증거가 없는 것입니다. 어떤 command를 실행했는지, 어떤 file을 봤는지, 어느 영역이 제외되었는지 모르면 audit는 release decision에 쓸 수 없습니다. Model의 말을 CI output, test, diff, log, config file로 다시 확인해야 합니다.

위험한 실패는 공개 문서에 너무 많은 세부 정보를 쓰는 것입니다. Public issue나 blog에 live URL, token, customer data, step-by-step exploit instruction을 넣지 않습니다. 공개 내용은 영향과 remediation 중심으로 쓰고 민감한 재현 정보는 제한된 tracker에 둡니다.

Secrets와 logs도 가볍게 보면 안 됩니다. Application code가 괜찮아도 CI log, debug screenshot, sample .env, verbose error에서 정보가 샐 수 있습니다. 마지막으로 auth, payment, personal data, admin tool의 high-risk change는 AI review만으로 통과시키지 말고 human review를 필수로 둡니다.

CI와 팀 습관으로 만든다

한 번의 audit는 오래가지 않습니다. lint, typecheck, test, dependency audit, secret scanning, dangerous API search, log policy check를 CI에 넣습니다. 모든 warning을 build blocker로 만들 필요는 없습니다. High는 block, Medium은 기한 있는 ticket, Low는 정기 점검으로 보내는 방식이 현실적입니다.

Claude Code 자체의 권한도 함께 점검해야 합니다. Claude Code permissions guide, secrets management, security failure cases, code review workflow를 같이 보면 좋습니다. 팀 repo에 audit brief, CI gate, review policy를 맞추고 싶다면 Claude Code training and consultation에서 실제 repository를 기준으로 정리할 수 있습니다.

정리

Claude Code를 보안 감사에 잘 쓰려면 AI에게 책임을 넘기는 대신, 사람이 audit system을 설계해야 합니다. Scope, asset inventory, threat model, review lane, risk register, evidence receipt, CI gate, human approval이 있으면 Claude Code는 강력한 조사 도구가 됩니다. 이것들이 없으면 report는 보기 좋아도 release risk를 설명하기 어렵습니다.

Masa가 ClaudeCodeLab의 release 전 review에 이 흐름을 적용했을 때 가장 효과가 컸던 것은 risk register와 evidence receipt였습니다. Claude Code가 route, log, environment variable, CI를 먼저 inventory하게 한 뒤 사람이 확인하니, 단순 취약점 찾기보다 남은 질문이 더 잘 보였습니다. 결과는 완벽한 안전 보장이 아니라, 팀이 납득할 수 있는 더 명확한 release 판단이었습니다.