Agent Governance Auditor

다른 AI 에이전트의 규정 준수를 감사하는 ADK 에이전트 — GCP 프로젝트에서 실행 중인 AI 워크로드를 찾아내고, 아무도 등록하지 않은 것까지 포함하여, 버전 관리되는 정책 팩에 대해 11가지 결정적 거버넌스 검사를 실행하며, EU AI Act (Art. 6, 9, 11, 12, 13, 15, 50) 및 SOC 2 Trust Services Criteria에 매핑된 감사자용 증거 패키지를 생성합니다. 모든 발견 사항은 변경 불가능한 증거 인용(GCS + SHA-256)을 수반합니다. 모든 쓰기 작업은 사람의 승인을 거칩니다.

각 정책은 주장하는 조항에 매핑되는 이유를 명시합니다 — 그리고 두 개의 매핑은 검토 중 제거되었는데, 그 이유는 과도한 매핑이 규정 준수 보고서의 신뢰도를 가장 빠르게 떨어뜨리기 때문입니다. 이 도구는 추론된 법적 위반이 아닌 필수 선언의 부재만 감사합니다. "문서화된 위험 분류 없음"은 확인 가능하며 감사자가 지적하는 사항입니다. "이 에이전트는 Annex III에 따라 고위험이다"는 이 도구가 내릴 자격이 없는 법적 판단입니다.

Gemini Enterprise 해커톤을 위해 제작 — Stream 2 (High-Code: ADK + 커스텀 MCP 서버 + Gemini Enterprise Agent Platform의 Agent Runtime).

왜 필요한가

EU AI Act 일정이 변경되었고, 그로 인해 문제는 더 시급해졌습니다. Regulation (EU) 2026/1744 ("AI에 관한 Digital Omnibus", 2026년 7월 27일 발효) 는 Annex III 고위험 의무를 2027년 12월 2일로 연기했습니다. 취소가 아니라 연기입니다 — 그리고 그 사이 제50조 투명성 의무, 제5조 금지 관행, GPAI 제공자 의무는 현재 모두 유효하며, 벌금은 €35M 또는 글로벌 매출의 7%에 달합니다.

따라서 기업은 고위험 시스템에 대한 증거 기록을 구축할 약 16개월의 시간이 있으면서도, 현재 실행 중인 에이전트에 대한 의무를 이미 부담하고 있습니다. 두 가지 모두 감사자가 항상 묻는 한 가지 질문에 답하는 데 달려 있습니다 — "어떤 AI 시스템을 보유하고 있으며, 그것들이 거버넌스되고 있음을 증명할 수 있습니까?" — 이에 대한 정직한 답은 대개 "정확히 확신할 수 없습니다." 입니다.

이 도구는 증거와 함께 답을 제시합니다.

Related MCP server: EU AI Act Compliance MCP Server

작동 방식

위 다이어그램은 존재하는 것을 보여줍니다. 핵심 설계 원칙(전체 아키텍처):

• LLM은 규정 준수를 결정하지 않습니다 — 코드가 결정합니다. 통과/실패는 MCP 도구 코드에서 계산됩니다. 에이전트는 조정, 우선순위 지정, 설명을 담당합니다. 변이 가드(mutation guard)는 트리아지가 상태를 뒤집으려는 모든 실행을 중단합니다.

• 구성에 의한 근거 확보. evidence_ref 없는 발견 사항은 데이터 모델에 존재할 수 없습니다 — 스키마가 거부합니다.

• 기본적으로 읽기 전용. 유일한 쓰기 경로(시정 명령)는 사람이 발행한 일회용 승인 토큰이 필요하며, 서버 측에서 강제되므로 서버는 에이전트의 "사람이 승인했다"는 주장을 신뢰하지 않습니다.

• 감사자는 스스로를 감사합니다 — 자체 Agent Identity로 배포되어 자체 스캔에 발견되며, 자체 11개 검사 중 6개를 통과합니다.

하나의 감사, 처음부터 끝까지

그 안의 두 가지는 장식이 아니라 설계입니다. 트리아지는 MCP 도구를 전혀 호출하지 않습니다 — 실제 추론을 수행하는 유일한 단계는 프로세스 외부에 대한 접근이 차단됩니다. 그리고 실행은 아무것도 기록되기 전에 중단됩니다: 아직 토큰이 없으므로, 에이전트가 쓰기를 시도하더라도 서버는 거부합니다.

발견은 이름 매칭이 아닌 행동 기반

이 제품의 성패를 좌우하는 질문은 "agent-something이라는 이름이 아닌 에이전트를 찾을 수 있습니까?" 입니다. 이름 매칭은 "아니오"라고 답합니다 — customer-insights-api를 놓치고 agent-proxy라는 nginx를 플래그합니다. 따라서 워크로드는 다섯 가지 신호로 분류되며, 각 후보에 대해 신뢰도와 이유가 보고됩니다:

첫 번째가 핵심입니다: 모델과 통신하는 워크로드는 평범한 이름 뒤에 숨을 수 없습니다. 데모 플릿에는 customer-insights-api — 에이전트 같은 이름도 라벨도 없는 실제 ADK 에이전트 — 가 포함되어 있어, 이 주장이 단언이 아니라 검증 가능하도록 합니다.

적용 범위와 적용되지 않는 범위

발견은 감사보다 더 넓게 도달하며, 보고서는 어느 것이 어느 것인지 명시합니다:

마지막 행이 정직한 행입니다. 외부 제공자를 호출하는 워크로드는 Google의 로그에 전혀 닿지 않으며, 규정 준수 감사자는 이를 잡아내지 못합니다 — 대신 그것을 막았을 제어 장치가 켜져 있는지 확인하고, 꺼져 있으면 보고합니다. GOV-NET-007이 바로 그 검사입니다.

최소 보장: 모델을 사용하려면 인증이 필요하고, 인증은 로깅됩니다. 따라서 최악의 경우는 "여기 귀속할 수 없는 것이 하나 있습니다 — 직접 확인하십시오" 이지, 침묵이 아닙니다.

빠른 시작

모든 개발은 컨테이너 내부에서 이루어집니다 — gcloud, Terraform, Node 및 고정된 Python 3.12가 포함된 Ubuntu 26.04 LTS. 사용자 머신에는 아무것도 설치되지 않으며, 환경은 macOS, Windows(Docker Desktop 또는 WSL2) 및 Linux에서 동일합니다.

사전 요구 사항: Docker 실행 중(OrbStack, Docker Desktop 또는 WSL2) 및 이 저장소 클론. 그 외에는 없습니다.

1. 이미지 빌드 및 셸 진입

저장소 루트 — 이 README와 gov_mcp/ auditor/ infra/ 폴더가 있는 폴더 — 에서 터미널을 엽니다:

cd path/to/agent-governance-auditor      # wherever you cloned it

# Build. First time ~3-5 min; afterwards it's instant (layer cache), so it's
# safe to just always run it.
docker build -t agv-dev docker/

# Start a shell inside the container.
docker run -it --rm \
  -v "$PWD":/workspace \
  -v agv-gcloud:/home/ubuntu/.config/gcloud \
  -v agv-venv:/opt/venv \
  -p 8080:8080 -p 8000:8000 -p 6274:6274 -p 6277:6277 \
  agv-dev bash

docker run -it --rm `
  -v "${PWD}:/workspace" `
  -v agv-gcloud:/home/ubuntu/.config/gcloud `
  -v agv-venv:/opt/venv `
  -p 8080:8080 -p 8000:8000 -p 6274:6274 -p 6277:6277 `
  agv-dev bash

해당 플래그의 용도:

프롬프트가 ubuntu@…:/workspace$로 바뀝니다. 진입했습니다.

여기부터의 모든 것은 컨테이너 내부에서 실행됩니다.

2. 일회성 설정 및 인증

bash docker/post-create.sh    # creates the python env, installs deps, runs the tests

# BOTH logins are required and they are NOT interchangeable:
#   the first authenticates the gcloud CLI
#   the second writes Application Default Credentials, which Terraform and
#   every google-cloud-* python client read instead
gcloud auth login --no-launch-browser
gcloud auth application-default login --no-launch-browser

gcloud auth application-default print-access-token >/dev/null && echo "ADC OK"

각 로그인은 브라우저에서 열 URL을 출력하고 코드를 다시 붙여넣도록 요청합니다. 두 번째 동의 화면에서 모든 권한 상자를 체크하세요 ("Select all") — 부분 동의는 혼란스러운 Scope has changed 크래시로 실패하며, 무엇이든 작동하려면 cloud-platform 범위가 필요합니다. ADC OK가 출력될 때까지 진행하지 마세요.

→ 동의 화면에서 오류가 발생하면: gotcha 0b

3. 샌드박스 GCP 프로젝트 생성

export PROJECT_ID="agent-gov-auditor-$(date +%y%m%d)"   # must be globally unique
gcloud projects create "$PROJECT_ID" --name="agent-governance-auditor"
gcloud config set project "$PROJECT_ID"

gcloud billing accounts list                             # copy your account id
gcloud billing projects link "$PROJECT_ID" --billing-account=XXXXXX-XXXXXX-XXXXXX

# REQUIRED: attribute ADC API calls to your project. User credentials carry no
# project of their own, so without this Terraform gets a 403 SERVICE_DISABLED
# blaming Google's shared ADC client project (764086051850).
gcloud auth application-default set-quota-project "$PROJECT_ID"

gcloud config set run/region us-central1

Terraform이 실행되기 전에 결제가 연결되어야 합니다 — API 활성화에 필요합니다.

→ 프로젝트 764086051850 명명에서 403이 발생하면: gotcha 0c

4. 인프라 프로비저닝

활성화된 API, 서비스 계정(의도적으로 과도한 권한이 부여된 rogue 계정 포함), 증거 버킷, 예산, 감사 로그 싱크 및 Artifact Registry 저장소를 생성합니다.

cd infra
cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars: project_id, billing_account_id, region
terraform init
terraform plan
terraform apply

apply가 결제 예산에서 실패한다면, 일부 계정에서는 예상된 동작입니다. 예산은 프로젝트 수준이 아닌 결제 계정 수준 권한이 필요하기 때문입니다. Console에서 한 번 생성하고 terraform import로 가져오거나, 해당 리소스를 주석 처리하세요. 밤새 고생하지 마세요.

→ 첫 apply가 SERVICE_DISABLED 오류 벽과 함께 실패한다면: gotcha 0e — 보통 그냥 다시 실행하면 됩니다

5. 모든 것 배포하기

단일 명령으로 Terraform 기반 위에 전체 에스테이트를 종속성 순서대로 빌드하고 배포하며, 단계별 경과 시간을 출력합니다. 측정 결과: 전체 4개 에이전트 플릿 기준 6분 57초.

./scripts/deploy-all.sh

그런 다음 등록된 Gemini Enterprise 앱(Agents → 3-dot → Preview)을 열고 다음을 보냅니다:

이 프로젝트에 대한 거버넌스 감사를 실행하세요.

실행은 승인 게이트에서 멈춥니다. 수정을 승인하려면 APPROVE 를 답장하거나, 일부만 승인하려면 APPROVE <finding id>, 거부하려면 DECLINE을 입력하세요. (GE와 Agent Runtime Playground는 ADK의 실험적 확인 프리미티브에 대한 확인 버튼을 렌더링하지 않으므로, 게이트는 입력된 답장도 수락합니다.)

터미널을 선호하거나 브라우저 없이 구동하고 싶다면:

python scripts/query_agent_runtime.py        # multi-turn chat against the deployed agent

→ 배포된 에이전트가 401을 반환하거나 게이트에서 멈춘다면: gotchas 0q 및 0r

6. 철거, 재구축, 반복

소프트 철거는 배포 스크립트가 만든 모든 것을 제거하고 Terraform이 소유한 모든 것은 유지합니다. 따라서 20분짜리 프로젝트 부트스트랩 없이 몇 분 안에 전체 배포 경로를 실행할 수 있습니다. 또한 데모를 위한 최상의 리허설이기도 합니다. 동일한 시퀀스이기 때문입니다.

./scripts/teardown-workloads.sh     # prompts first; --yes to skip
terraform -chdir=infra plan         # expect NO changes — proves the split is clean
./scripts/deploy-all.sh             # back up in ~6 minutes

증거는 의도적으로 삭제되지 않습니다: 버킷은 30일 보존 정책을 가지며 삭제를 거부합니다. 이것이 설계가 주장하는 불변성이며, 삭제가 거부되는 것을 보는 것이 어떤 주장보다 잘 입증합니다.

배포 체인

무언가 실패했을 때 어떤 링크를 다시 실행해야 하는지 알아야 할 때 유용합니다:

scripts/deploy-all.sh
├─ 1. auditee fleet
│      auditees/deploy-{compliant,legacy,rogue,insights}.sh
│        └─ each sources auditees/common.sh → build_image()
│             └─ gcloud builds submit  (Dockerfile + main.py + requirements.txt)
│                  └─ Artifact Registry
│           then gcloud run deploy, with posture set by FLAGS only
├─ 2. gov_mcp/deploy.sh                  → Cloud Build → Cloud Run (MCP server)
├─ 3. auditor/deploy.sh                  → Agent Runtime + its two IAM bindings
└─ 4. scripts/setup-gemini-enterprise.sh → GE app + agent registration + sharing

그 체인에 대해 알아둘 세 가지:

• common.sh는 스크립트가 아니라 소스 라이브러리입니다. PROJECT_ID, REGION, IMAGE 및 build_image()를 정의합니다. 직접 실행하면 아무것도 하지 않습니다.

• 하나의 이미지, 네 개의 배포. 네 개의 감사 대상은 모두 동일한 컨테이너를 실행합니다. 거버넌스 자세는 전적으로 gcloud run deploy 플래그(레이블, 서비스 계정, 환경 변수)에 있으며, 이는 감사자가 검사하는 바로 그 것입니다. 따라서 첫 번째 스크립트가 빌드하고 나머지는 재사용합니다.

• build_image()는 이미지가 이미 존재하면 빌드를 건너뜁니다. auditees/main.py를 편집한 후 일반 재배포는 이전 이미지를 전달하며 변경 사항이 조용히 반영되지 않습니다. 한 번 강제 실행: FORCE_BUILD=1 ./auditees/deploy-compliant.sh.

2단계와 3단계는 독립적으로도 작동하며(./auditor/deploy.sh는 에이전트만 재배포), 모든 스크립트는 멱등적입니다 — 재실행해도 안전합니다.

떠나고 돌아오기: exit는 세션을 종료하고 컨테이너를 제거합니다. 동일한 docker run … 명령을 다시 실행하면 돌아옵니다. gcloud 로그인과 설치된 패키지는 컨테이너가 아닌 agv-gcloud 및 agv-venv 볼륨에 있기 때문에 그대로 유지됩니다. 모든 것을 지우고 새로 시작하려면: docker volume rm agv-gcloud agv-venv.

무언가 깨졌을 때, 디버깅 전에 gotchas & sharp edges를 확인하세요. 이미 겪은 실패를 다룹니다 — Scope has changed 인증 크래시, mcp.shared.session 가져오기 오류, gcloud virtualenv/VPN 실패, 그리고 개인 프로젝트에서 여러 검사가 합법적으로 SKIPPED를 보고하는 이유를 포함합니다.

위 단계는 행복한 경로입니다. **docs/build-plan.md**에는 나머지가 있습니다: 운영 규칙, 실제로 겪은 모든 gotcha, 그리고 왜 이런 방식인지 설명하는 결정 로그.

저장소

scripts/

테스트

pytest evals/ -q              # 171 offline, no GCP needed, free
pytest evals/agent -m live    # 8 end-to-end agent evals (~100s, ~$0.02, needs ADC)

라이브 스위트는 실제 파이프라인을 구동하고 단위 테스트가 구조적으로 할 수 없는 것을 주장합니다: 실행이 게이트에 도달하는지, 인간이 승인하기 전에는 아무것도 수정되지 않는지, 승인 토큰이 채팅에 도달하지 않는지, 그리고 모든 실패한 finding이 유효한 증거 해시를 갖는지.