aflock 딥다이브
— AI 에이전트에게 "여기까지만 해"라고 못 박고, 그걸 어겼는지 암호로 증명하는 디지털 계약서

aflock-ai/aflock. package-lock.json이 의존성 버전을 잠그듯, .aflock 파일은 "이 에이전트가 무엇을 할 수 있는지"를 잠급니다. 요즘 AI 에이전트는 스스로 명령을 실행하고, API를 호출하고, 파일을 고치고, 심지어 하위 에이전트(sub-agent)까지 만들어 냅니다. aflock은 사람이 암호로 서명한 정책 파일로 에이전트의 행동에 울타리(지출 한도·도구 제한·파일 접근 범위)를 치고, 에이전트가 그 울타리 안에서만 움직였다는 증거(서명된 증언, attestation)를 행동마다 남깁니다. 핵심은 에이전트가 자기 정체성을 속일 수 없고, 서명 키에는 절대 손댈 수 없다는 점입니다. Claude Code의 훅(hook) 시스템에 끼워 넣는 Go 플러그인이며, 공급망 보안 회사 TestifySec이 만들었습니다. (저장소: aflock-ai/aflock · Go · ★251 · Apache-2.0)

1프로젝트 한줄 요약

"AI 직원에게 회사 법인카드를 쥐여 주되, 한도·사용처를 적은 계약서에 사장이 직접 도장을 찍고, 모든 결제 영수증에 위조 불가 도장을 남기는 시스템."

이 프로젝트의 진짜 코드는 모두 Go 언어로 cmd/와 internal/ 아래에 있습니다. aflock이라는 명령줄 도구 하나가 Claude Code의 훅(hook)에 연결되어, 도구를 쓰기 전(PreToolUse)에 정책을 검사하고, 쓴 뒤(PostToolUse)에 증언을 남기며, 세션이 끝날 때 전체가 규칙을 지켰는지 검증(verify)합니다. README가 "현재는 비공개 개발·명세 단계(Specification phase)"라고 밝히듯 아직 초기 단계지만, 그 안에 담긴 보안 설계는 실무에서 검증된 표준들(SPIFFE/SPIRE·in-toto·OPA)을 조합한 견고한 교본입니다.

이 문서가 파고드는 건 "어떻게 설치하나"가 아니라 그 안의 보안 설계입니다 — "에이전트가 어떻게 자기 신분을 못 속이게 만드는가", "왜 신분증(JWT)과 도장(서명 키)을 굳이 분리하는가", "하위 에이전트에게 권한을 어떻게 더 좁혀서 물려주는가", "행동 순서를 빠뜨리거나 뒤바꾸지 않았음을 머클 트리로 어떻게 증명하는가". AI 에이전트 보안과 공급망 신뢰(supply-chain trust)를 동시에 공부하려는 사람에게 밀도 높은 실전 교본입니다.

2왜 주목받는가

"신뢰하지 말고 검증하라"를 AI 에이전트에 처음으로 제대로 적용한, 검증된 보안 표준 위에 세운 설계.

'AI 에이전트 가드레일'을 표방하는 도구는 점점 늘고 있지만, aflock이 라이브 멘션을 타고 주목받은 이유는 대부분이 "프롬프트로 부탁하는" 수준에 머무를 때, 이쪽은 암호학으로 강제하고 증명하기 때문입니다. 다섯 가지로 정리하면:

① "프롬프트 부탁"이 아니라 암호학적 강제

흔한 가드레일은 시스템 프롬프트에 "위험한 일은 하지 마"라고 적는 식입니다. 하지만 그건 에이전트가 마음만 먹으면 무시할 수 있는 부탁입니다. aflock은 Claude Code 훅을 가로채 도구 실행 자체를 코드 레벨에서 차단(deny)하고, 정책 파일은 사람이 서명해서 에이전트가 못 고치게 만듭니다.

② 에이전트가 신분을 속일 수 없다 (PID 내성검사)

보통 시스템은 "내가 GPT야"라고 스스로 주장하는 값을 믿습니다. aflock은 반대로, MCP 소켓에서 운영체제 PID(프로세스 번호)를 얻어 그 프로세스를 직접 들여다봅니다(UID·컨테이너 ID·실행 파일 경로). 신분은 주장이 아니라 설정으로부터 계산되는 값이라, 거짓말이 원천 봉쇄됩니다.

③ 검증된 보안 표준의 조합 (바퀴를 새로 만들지 않음)

가장 신뢰가 가는 대목입니다. 정체성은 SPIFFE/SPIRE(클라우드 워크로드 신분 표준), 증언은 in-toto / DSSE(소프트웨어 공급망 보안 표준)와 Rookery(witness 프로젝트의 보안 강화 포크), 정책 평가는 OPA/Rego(쿠버네티스 업계 표준 정책 엔진)에 기댑니다. "검증된 것에 맡기고, 에이전트에 맞는 접착제만 새로 짠다"는 철학입니다.

④ 하위 에이전트까지 재귀적으로 통제 (sublayouts)

에이전트가 하위 에이전트를 만들 때, 자식의 권한은 부모보다 반드시 더 좁아야 하고, 자식이 쓴 비용은 부모 총액에 합산됩니다. 검증은 하위 계층으로 재귀적으로 파고듭니다. in-toto의 sublayout 개념을 에이전트 위임에 그대로 적용한 흔치 않은 구현입니다.

⑤ 적대적 테스트가 풍부 (공격자 시점으로 자기 검증)

저장소에는 handler_adversarial_test.go·handler_forgery_test.go·matcher_security_test.go·fuzz_test.go 같은 "내 시스템을 어떻게 뚫을까"를 검증하는 테스트가 잔뜩 있습니다(증언 위조·신분 충돌·경로 탈출·Bash 우회 등). 보안 도구가 스스로를 적대적으로 공격해 보는 자세는 드문 신뢰 신호입니다.

다른 접근과의 비교

3기술 스택 전체 지도

단일 Go 바이너리 + 검증된 보안 라이브러리들. 웹 서버가 아니라 '정책 강제 엔진'이라 층 구분이 조금 다르다.

aflock은 화면이 있는 앱이 아니라 명령줄 도구이자 MCP 서버입니다. 그래서 백엔드/프론트엔드 대신 ① 진입·통합 층 ② 보안 코어(신분·서명·정책) ③ 인프라·배포로 나눠 보는 게 자연스럽습니다. 언어는 Go 1.26 단일 구성입니다(메모리 안전 + 단일 정적 바이너리 + 강력한 표준 암호 라이브러리라 보안 도구에 잘 맞습니다).

① 진입 · 통합 층

② 보안 코어 (신분 · 서명 · 정책)

③ 인프라 · 배포

실제 시연 환경은 docker-compose.yml에 담겨 있습니다. SPIRE 서버 + SPIRE 에이전트 + aflock 테스트 워크로드 세 컨테이너가 뜨고, SPIRE 에이전트가 pid: "host"로 호스트 프로세스를 들여다볼 수 있게 설정됩니다(앞서 말한 PID 내성검사의 토대). 문서 사이트(docs-website/, Docusaurus)는 wrangler.toml을 통해 Cloudflare Pages로 배포되며(빌드는 GitHub Actions에서 수행), 빌드/테스트는 Makefile이 묶습니다(make build·make test·make lint). 코드 품질은 .golangci.yml의 엄격한 린트 규칙으로 강제합니다.

4아키텍처 심화 분석

정책 한 줄이 어떻게 "신분 확인 → 차단 결정 → 서명된 증언 → 사후 검증"으로 흐르는가.

전체 구조의 핵심은 "에이전트는 신분증(JWT)만 받고, 진짜 도장(서명 키)은 서버가 쥔다. 모든 행동은 훅을 거치며 정책으로 걸러지고, 통과한 행동에는 위조 불가능한 증언이 남는다"입니다. 먼저 숲(전체 그림)을 보고, 그다음 대표 흐름 한 줄기를 끝까지 따라가 보겠습니다.

독수리 시점 — 전체 그림 한 장

대표 흐름 한 줄기 — "에이전트가 Bash: rm config.json을 실행하려 할 때"

가장 흔한 동작 하나를 입력부터 결과까지 손으로 따라가 봅니다. 어느 패키지·파일이 어떤 순서로 일하는지에 집중하세요(핵심 단계만; 곁가지는 생략).

흐름을 한 문장으로 요약하면: "세션이 열리면 신분을 유도해 JWT를 쥐여 주고(①), 도구를 쓸 때마다 정책으로 거르고(②), 통과한 행동엔 서명 도장을 찍어 순서대로 쌓고(③), 끝에 전부 규칙을 지켰는지 검증한다(④)." 이 레포에서 'PreToolUse'는 막는 단계, 'PostToolUse'는 증거를 남기는 단계라는 한 쌍의 패턴을 알면 코드가 훨씬 잘 읽힙니다.

핵심 설계 패턴 5가지

① 신분 유도 (Derived, not Asserted Identity)

가장 근본적인 패턴입니다. 에이전트가 "내가 누구다"라고 주장하는 값을 믿지 않고, 설정·실행 환경에서 신분을 계산합니다. internal/identity/agent.go의 DeriveIdentity()는 모델·바이너리·환경·도구·정책 다이제스트·부모를 이어 붙여 SHA256 해시 하나로 만듭니다. 도구 순서가 바뀌어도 같은 해시가 나오도록 정렬하는 등(테스트 ToolOrderDoesNotMatter), "같은 에이전트면 항상 같은 신분, 다르면 반드시 다른 신분"을 보장합니다.

② JWT와 서명 키의 분리 (권한과 증명의 분리)

에이전트는 JWT(인가 토큰)는 받지만, 증언을 만드는 서명 키는 절대 못 만집니다. JWT로 "나 이거 해도 돼?"를 제시할 뿐, 도장은 항상 aflock 서버를 거쳐 찍힙니다. 신분증을 위조해도 공증 도장은 못 찍게 만든 셈입니다(§6에서 코드).

③ Fail-Open vs Fail-Closed의 의도적 비대칭

정책 파일이 없으면 전부 허용(opt-in, fail-open)하지만, 정책 파일이 있는데 깨졌으면 전부 거부합니다(fail-closed). "보호를 켜는 건 사용자 선택이되, 한번 켠 보호는 고장 시 안전한 쪽(차단)으로 닫힌다"는 보안 설계의 정석입니다. 신분 확인이 필요한 정책인데 SessionStart가 생략됐다면 역시 차단합니다.

④ 다층 정책 평가 (도구 → 권한 → 데이터 흐름)

handlePreToolUse는 한 번에 끝내지 않고 세 겹으로 거릅니다: ⓐ 도구/파일 접근(EvaluatePreToolUse) → ⓑ 자원 권한(EvaluateGrants: 비밀·API·저장소) → ⓒ 데이터 흐름(EvaluateDataFlow: 민감 데이터가 외부로 새는지). 한 겹이라도 거부면 거부입니다.

⑤ 하위 에이전트 위임 (Sublayouts + Propagation)

에이전트가 하위 에이전트를 만들면(isSubagentSpawn 감지), state/propagation.go가 부모의 자료(materials)와 한도를 자식에게 더 좁혀(attenuate) 전달합니다. "자식은 부모보다 빡빡해야 한다"는 규칙을 강제하고, 검증 때 자식 지출을 부모 총액에 합산합니다.

5디렉토리 구조 해부

진짜 로직은 전부 internal/ 아래. Go의 관례상 internal/은 "이 모듈 안에서만 쓰는 비공개 코드"라는 뜻이다.

읽는 순서를 추천하자면: ① pkg/aflock/types.go(데이터 모양 = 정책 스키마) → ② README.md의 정책 예시(무엇을 표현하는지) → ③ internal/hooks/handler.go(전체 흐름의 심장) → ④ internal/identity/agent.go + internal/auth/jwt.go(신분과 토큰) → ⑤ internal/attestation/signer.go(서명) 순입니다. paper/aflock.pdf는 전체 설계를 글로 정리한 보너스 자료라 개념을 한 번에 잡기 좋습니다.

6학습 포인트 (기술별)

이 저장소의 진짜 가치는 "AI 에이전트 보안 + 공급망 신뢰 표준"을 한곳에서 코드로 볼 수 있다는 것.

{
  "limits": {
    "maxSpendUSD":  { "value": 10.00, "enforcement": "fail-fast" },  // 넘으면 즉시 중단
    "maxTurns":     { "value": 50,    "enforcement": "post-hoc"  }   // 끝에 확인
  },
  "tools": {
    "allow": ["Read", "Edit", "Bash", "Glob", "Grep"],
    "deny":  ["Task"],
    "requireApproval": ["Bash:rm -rf *", "Bash:git push --force"]    // 사람 승인 필요
  },
  "files": { "allow": ["src/**"], "deny": ["**/.env", "**/secrets/**"] }
}

// 개념(README): 신분 = 구성요소들의 해시
AgentIdentity = SHA256(model ‖ environment ‖ tools ‖ policyDigest ‖ parent)

// 서명은 ECDSA P-256(ES256)만 사용 → "알고리즘 혼동(alg confusion)" 공격 차단
type AflockClaims struct {
    jwt.RegisteredClaims
    AgentID      string   // 누구인가
    IdentityHash string   // 신분 해시(②에서 계산한 값)
    AllowedTools []string // 허용 도구(정책에서 범위 좁힘)
    PolicyDigest string   // 이 정책에 한해서만 유효
}
// 발급 키는 메모리에만 살고 프로세스 종료 시 사라짐(ephemeral)

// 개념: 위험 명령은 "패턴 매칭 + 정규화"로 우회까지 잡는다
" Bash: rm -rf *"      → requireApproval 매치  ⇒ ASK   // 승인 요구
" Read: src/.env"      → files.deny "**/.env"  ⇒ DENY  // 차단
" Read: ../../etc/pwd" → 경로 탈출(path traversal) 탐지 ⇒ DENY

# Rego: deny 규칙(쿠버네티스 업계에서 검증된 정책 엔진)
deny contains msg if {
    sum_spend > input.limits.maxSpendUSD.value     # > 는 비교 연산
    msg := "spend limit exceeded"
}

func (h *Handler) Handle(hookName string) error {
    data, _ := io.ReadAll(io.LimitReader(os.Stdin, maxStdinSize+1)) // OOM 방지(10MB 제한)
    var input aflock.HookInput
    json.Unmarshal(data, &input)
    switch aflock.HookEventName(hookName) {
    case aflock.HookPreToolUse:  return h.handlePreToolUse(&input)   // 막는 단계
    case aflock.HookPostToolUse: return h.handlePostToolUse(&input)  // 증거 남기는 단계
    // … SessionStart / Stop / SubagentStop / SessionEnd …
    }
}

7시스템 요구사항

순수 소프트웨어라 특별한 하드웨어는 없다. 다만 빌드·실행에 필요한 환경이 조금 까다롭다.

가볍게 코드만 읽고 개념을 익히려면 아무것도 설치할 필요 없습니다(GitHub에서 읽으면 됨). aflock 바이너리를 직접 빌드해 훅을 시험해 보려면 Go와 rookery가 필요하고, "서명된 증언이 진짜로 만들어지는" 전체 그림을 보려면 Docker로 SPIRE까지 띄우는 게 좋습니다.

8직접 해볼 수 있는 실습 과제

읽기만 하면 금방 잊는다. 난이도순으로 손을 움직여 보자.

9관련 기술 심화 학습 로드맵

aflock을 제대로 소화하려면 '에이전트 보안 + 공급망 신뢰'의 토대를 함께 쌓는 게 좋다. 4주 코스 제안.

10핵심 키워드 사전

문서·코드에서 자주 만나는 용어를 한 번에. 모르는 단어가 나오면 여기로.

11참고 링크

원문과 함께 보면 좋은 표준·문서들.

• aflock 저장소: github.com/aflock-ai/aflock (README + docs/reference/specification.md + paper/aflock.pdf)
• Rookery(증언 프레임워크): github.com/aflock-ai/rookery · 원조 witness.dev
• SPIFFE/SPIRE(워크로드 신분): spiffe.io · github.com/spiffe/spire
• in-toto(공급망 증언): in-toto.io · Sigstore/Fulcio(키리스 서명): sigstore.dev
• OPA/Rego(정책 엔진): openpolicyagent.org · Rego Playground
• Claude Code Hooks(통합 지점): docs.claude.com · MCP: modelcontextprotocol.io
• 만든 곳: TestifySec (Apache-2.0 · 보안 신고 cole@testifysec.com)