하네스 엔지니어링 Vol.4 — 닿을 수 없으면, 뚫릴 수도 없다

에이전트가 닿을 수 있는 범위가 곧 공격 표면이다. 5개의 제어축으로 도구의 경계를 설계하면, 실수든 공격이든 침투할 경로 자체가 사라진다.

01 — Vol.1-3 리캡: 지금까지 뭘 제어했나

Vol.2에서 tools: Read, Write로 내장 도구를 제한했어요. 하지만 에이전트가 Bash를 통해 서버에 SSH하거나, MCP로 데이터베이스에 접근하거나, 다른 에이전트를 스폰해서 배포하는 것까지는 제어하지 못했거든요. Vol.4에서는 에이전트가 외부 세계와 접촉하는 모든 경로의 경계를 설계합니다 — 그리고 이건 자연스럽게 에이전트 보안이 돼요.

02 — 공격 표면: 경계 없는 에이전트가 만드는 사고

**공격 표면(Attack Surface)**이란 외부에서 시스템에 침투할 수 있는 모든 경로를 말해요. 에이전트에게 권한이 많을수록 공격 표면이 넓어져요.

Bash 무제한: editor 에이전트가 git push --force를 실행해서 main 브랜치를 덮어씀. 보안 위협으로는 프롬프트 인젝션으로 악성 셸 명령 실행이 가능해요.

MCP 무제한: researcher 에이전트가 Slack MCP로 "#general 채널"에 미완성 초안을 전송함. 악성 MCP 서버가 민감 데이터를 외부로 유출할 수 있어요.

Agent 스폰 무제한: creator 에이전트가 자체적으로 deployer를 스폰해서 프로덕션에 배포함. 권한 에스컬레이션 — 낮은 권한이 높은 권한을 획득하는 공격이에요.

Permission 없음: fact-checker가 rm -rf /tmp/*로 임시 파일을 전부 삭제함. 파일시스템 파괴, 서비스 거부(DoS) 공격이에요.

이 모든 사고의 공통점은 에이전트에게 "필요 이상의 접근 권한"이 있었다는 거예요. 최소 권한 원칙(Principle of Least Privilege) — 꼭 필요한 것만 허용하고 나머지는 전부 막는다는 뜻이에요. 이게 하네스 보안의 본질이에요.

03 — 5개 축으로 보는 도구 제어 전체 지도

Claude Code에서 에이전트의 도구 접근을 제어하는 메커니즘은 정확히 5개예요. 보안 용어로는 이걸 **심층 방어(Defense in Depth)**라고 해요 — 여러 겹의 방어선을 쌓아서 하나가 뚫려도 다음 층이 막아주는 구조예요.

• 보너스: PreToolUse Hook은 런타임 조건부 차단으로, Vol.1에서 이미 다뤘어요.

04 — 축 1: tools / disallowedTools — 내장 도구 제어

Vol.2에서 배운 tools 화이트리스트의 반대편 — disallowedTools 블랙리스트도 있어요. "이것만 쓸 수 있다" vs "이것만 못 쓴다"의 차이예요.

화이트리스트(tools): 명시한 도구만 허용, 나머지 전부 차단. 보안 관점에서 더 안전해요.

tools: Read, Grep, Glob, WebSearch, WebFetch
# → Write, Edit, Bash, Agent 전부 사용 불가

블랙리스트(disallowedTools): 명시한 도구만 차단, 나머지 전부 허용. 편하지만 새 도구 추가 시 자동 허용되므로 보안이 느슨해요.

disallowedTools: Write, Bash
# → Read, Edit, Grep, Glob, WebSearch... 전부 사용 가능

보안 팁: 화이트리스트(tools)가 블랙리스트(disallowedTools)보다 안전해요. 새로운 도구가 추가돼도 명시적으로 허용하지 않으면 쓸 수 없으니까요.

05 — 축 2+3: 에이전트 스폰과 MCP 서버 스코핑

누구를 부를 수 있는지(축 2), 어떤 외부 서비스에 닿을 수 있는지(축 3)를 제어해요. 보안 용어로는 수평 이동(Lateral Movement) 차단이에요.

축 2 — Agent(...) 스코핑

tools: Agent(worker, researcher), Read, Bash
# → deployer 에이전트는 스폰 불가 → 프로덕션 배포 사고 원천 차단

보안 위협 차단: 권한 에스컬레이션(Privilege Escalation) — 낮은 권한의 에이전트가 높은 권한의 에이전트를 스폰해서 제한을 우회하는 공격

축 3 — mcpServers 스코핑

MCP(Model Context Protocol)는 에이전트가 외부 서비스(DB, 브라우저, Slack 등)에 접속하는 통로예요. 이 통로를 에이전트마다 다르게 열어줄 수 있어요.

mcpServers:
  - supabase
# → supabase MCP만 접근 가능, Slack/GitHub 등은 차단

보안 위협 차단: 데이터 유출(Data Exfiltration) — DB에서 읽은 민감 정보를 Slack이나 외부 API로 전송하는 공격

06 — 축 4+5: 승인 프로세스와 글로벌 정책

축 4 — permissionMode: 같은 도구라도 승인 방식을 에이전트마다 다르게 설정

축 5 — settings.json permissions: 프로젝트 전체에 "이건 누구도 못 한다"를 강제. 조직 정책(Organization Policy) — 개인이 아무리 바꾸려 해도 조직 규칙이 우선해요.

{
  "permissions": {
    "deny": ["Bash(git push *)", "Bash(rm -rf *)", "Agent(deployer)"],
    "allow": ["Bash(git status)", "Bash(git diff *)", "Bash(git commit *)"]
  }
}

평가 순서: deny → ask → allow. deny가 최우선이라, allow에 있어도 deny에 있으면 무조건 차단돼요.

07 — 실습: settings.json으로 git push 차단

축 5(settings.json)를 직접 설정하고, 에이전트가 git push를 시도할 때 차단되는 걸 확인해봐요.

프로젝트 구조

my-project/
├── .claude/
│   ├── settings.json    ← 거부 규칙 설정
│   └── agents/
│       └── writer.md    ← git push 시도하는 에이전트
└── (git init 필요)

settings.json

{
  "permissions": {
    "deny": ["Bash(git push *)", "Bash(rm -rf *)"],
    "allow": ["Bash(git status)", "Bash(git add *)", "Bash(git commit *)"]
  }
}

writer.md

---
name: writer
description: 파일을 작성하고 git에 커밋하는 에이전트
tools: Read, Write, Bash
---

요청받은 내용을 파일로 작성하고 git에 커밋한다.
커밋 후 git push origin master로 원격에 푸시한다.

실행 결과 (실제 테스트)

writer 에이전트에게 "hello.md를 작성하고, git 커밋하고, git push origin master로 푸시해줘"라고 요청했어요.

결과: 파일 생성 ✅ → git add ✅ → git commit ✅ → git push 차단 ⛔

Claude의 실제 응답: "git push가 권한 설정에 의해 차단되었습니다. 로컬 작업(파일 생성 + 커밋)은 모두 완료된 상태이니, 터미널에서 직접 실행해주세요."

이게 하네스의 힘이에요. writer 에이전트의 프롬프트에는 "git push로 푸시하라"고 분명히 적혀 있어요. 하지만 settings.json의 deny 규칙이 인프라 레벨에서 차단했어요. 프롬프트 인젝션으로 에이전트에게 git push --force를 실행시키려 해도, deny 규칙이 먼저 평가되기 때문에 실행 자체가 불가능해요.

08 — 하네스 아키텍처 전체 지도

최소 권한이 최강 보안이다

Vol.1~4를 관통하는 하나의 원칙이 있어요 — 에이전트에게 "필요한 만큼만" 허용하고, 나머지는 전부 차단하는 것. 이건 단순한 실수 방지가 아니라, 에이전트 시대의 보안 아키텍처예요. 프롬프트로 "조심해줘"라고 부탁하는 건 방화벽 없이 직원에게 "해커 조심해"라고 말하는 거랑 같아요. 인프라로 강제해야 보안이에요.

행동 차단(Hook) + 역할 분리(tools) + 평가 객관화(Evaluator) + 도구 경계(5개 제어축) = 에이전트 보안 하네스

인터랙티브 가이드

전체 인터랙티브 교육자료 보기

시리즈 링크

• Vol.1 — Hook으로 행동 제한하기
• Vol.2 — 서브에이전트로 역할 분리하기
• Vol.3 — 평가자 분리와 객관적 채점
• Vol.4 — 도구의 경계를 설계하다 (현재)

참고 자료

• Anthropic — Harness Design for Long-Running Apps
• Claude Code Permissions 공식 문서
• Claude Code Sub-agents 공식 문서