에이전트형 저장소(Agentic Repositories)를 위한 AI 에이전트 리스크 감사 도구를 만들었습니다

GitHub repo: https://github.com/jbridges82/hermes-guard
Live demo: https://hermes-guard.vercel.app

내가 만든 것
나는 AI 에이전트가 접근하는 저장소(repositories)를 위한 로컬 우선(local-first) 리스크 감사 도구인 Hermes Guard를 만들었습니다. 이 프로젝트의 핵심 질문은 간단합니다: AI 에이전트가 실제 저장소를 다루기 시작할 때, 누가 그 에이전트들을 감사할 것인가? Hermes Guard는 로컬 저장소를 스캔하여 위험한 AI 에이전트 자동화 패턴을 찾아내고, 증거 기반의 Markdown 및 JSON 보고서를 생성합니다. 또한 스캔 결과를 검토할 수 있도록 세련된 React/Vite 대시보드도 포함되어 있습니다.

MVP(Minimum Viable Product)는 에이전트의 행동을 결정짓는 경우가 많은 저장소 수준의 파일들에 집중합니다:

• AGENTS.md 지침(instructions)
• 프롬프트(Prompt) 파일
• GitHub Actions 워크플로(workflows)
• MCP 서버 및 도구 권한 설정(tool permission config)
• 에이전트가 생성한 명령어를 실행하는 셸 스크립트(Shell scripts)
• 안전하지 않은 비밀 정보(secret) 처리를 정규화하는 예시 환경 파일(environment files)

이는 Hermes Guard가 애플리케이션 로직(application logic)만을 검사하려는 것이 아님을 의미합니다. 에이전트 주변의 자동화 계층(automation layer)을 살펴보고 있는 것입니다. 예를 들어:

approval_mode : none
allow : " *"

이 두 줄은 애플리케이션 버그가 아닙니다. 이는 자동화 리스크(automation risk)입니다. 이들은 검토자에게 해당 저장소의 에이전트 태세(agent posture)에 관한 중요한 정보를 알려줍니다.

데모
Live demo: https://hermes-guard.vercel.app
대시보드는 스캔 결과를 보안 검토 작업 공간(security review workspace)으로 제시합니다:

• 스캔된 저장소 트리를 보여주는 왼쪽 패널
• Hermes 스타일의 활동을 보여주는 중앙 패널
• 리스크 태세(risk posture), 심각도 수치(severity counts), 그리고 발견 사항 카드(finding cards)를 보여주는 메인 패널

데모용 저장소는 의도적으로 합성된(synthetic) 안전한 상태입니다. 가짜 플레이스홀더(placeholders)로 명확히 표시된 가짜 자격 증명(credentials)만을 포함하고 있습니다.

코드
GitHub repo: https://github.com/jbridges82/hermes-guard
스캐너는 다음을 작성합니다:

• reports/hermes-guard-report.json
• reports/hermes-guard-report.md

전형적인 발견 사항(finding)에는 다음이 포함됩니다:

• ID 및 제목
• 심각도(Severity)
• 파일 경로 및 줄 번호
• 증거 스니펫(Evidence snippet)
• 중요성(Why it matters)
• 권장 수정 사항(Recommended fix)

이러한 증거 우선(evidence-first) 설계는 중요합니다. 검토자는 도구를 신뢰할 필요가 없어야 합니다. 발견 사항을 즉시 검증할 수 있어야 합니다.

나의 기술 스택(Tech Stack)

• React + Vite 프론트엔드

• Tailwind CSS

• Node.js 스캐너 로직 (scanner logic)

• 규칙 기반 리스크 엔진 (Rule-based risk engine)

• 로컬 파일 시스템 스캐닝 (Local filesystem scanning)

• Markdown 및 JSON 보고서 출력

• 대시보드를 위한 Vercel 배포

Hermes Agent 활용 방식
Hermes Guard는 Hermes에서 영감을 받았으며 Hermes를 사용할 준비가 되어 있지만, MVP(Minimum Viable Product) 단계에서 실시간 Hermes Agent 실행을 지원한다고 주장하지는 않습니다. 저는 에이전트형 시스템(agentic system)이 계획을 세우고, 도구를 사용하며, 실제 코드에 접근할 수 있을 때 중요하게 작용하는 저장소 리스크 유형을 중심으로 스캐너를 설계했습니다. 이 프로젝트는 scanner/hermesAdapter.js에 깔끔한 어댑터 경계(adapter boundary)를 포함하고 있습니다. 현재 이 어댑터는 스텁 모드(stub mode)임을 명확히 보고합니다: "Hermes Agent 런타임이 연결되지 않았습니다. Hermes Guard는 결정론적(deterministic) 로컬 규칙만 실행 중입니다." 이는 의도된 사항입니다. 저는 제출물이 정직함을 유지하기를 원했습니다. 즉, 현재는 결정론적 로컬 스캐닝이 작동하며, 향후 Hermes 런타임이 스캐너/보고 파이프라인을 변경하지 않고도 어댑터를 통해 연결될 수 있다는 점을 보여주고자 했습니다.

설계 단계부터 안전함 (Safe By Design)
Hermes Guard는 선택적인 에이전트 런타임이 연결되기 전에 저장소를 대상으로 안전하게 실행되도록 설계되었습니다. Hermes Guard는 저장소 코드를 절대 실행하지 않습니다. 스캐너는 읽기 전용(read-only)입니다. 파일을 탐색하고, 텍스트를 읽고, 결정론적 규칙을 적용하며, 보고서를 작성합니다. 아키텍처는 로컬 우선(local-first) 방식이므로 저장소 콘텐츠가 개발자의 컴퓨터를 떠날 필요가 없습니다. MVP를 위해 클라우드 의존성은 필요하지 않습니다. 포함된 데모 저장소에는 의도적으로 조작된 가짜 자격 증명(credentials)만 포함되어 있습니다.

탐지 항목
현재의 결정론적 규칙 엔진은 다음 사항을 탐지합니다:

• 가짜 또는 노출된 API 키 형태의 문자열
• "ignore previous instructions"와 같은 프롬프트 인젝션 (prompt-injection) 텍스트
• 제한 없는 셸 실행 (unrestricted shell execution)
• approval_mode: none
• allow: "*" 와일드카드 액세스
• 셸로 파이프 연결된 curl 또는 wget
• 광범위한 에이전트 자동화에 사용되는 GitHub Actions secrets
• 과도하게 광범위해 보이는 MCP 또는 도구 권한 설정

배운 점
이 프로젝트에서 흥미로웠던 점은 정규 표현식 (regular expressions)을 작성하는 것이 아니었습니다. 그것은 바로 "에이전트형 저장소 (agentic repository)"가 실제로 무엇을 의미하는지 결정하는 것이었습니다. 저장소는 더 이상 단순한 소스 코드만이 아닙니다. 그것은 권한, 프롬프트, 도구, 그리고 자동화 경로의 집합이 될 수도 있습니다.

일단 에이전트가 해당 저장소(repo)에서 동작할 수 있게 되면, 그 파일들은 시스템의 보안 경계(security boundary)의 일부가 됩니다. 그 경계는 검토가 필요합니다.

다음에 구축할 내용
Hermes Guard의 다음 버전에는 다음과 같은 기능이 추가될 것입니다:

• GitHub 코드 스캐닝을 위한 SARIF 출력
• 풀 리퀘스트(Pull request) 차이(diff) 스캐닝
• 검토자 정당화(justification)를 포함한 규칙 억제(Rule suppressions)
• 로컬 스캐너 출력과 연결되는 라이브 대시보드
• 엄격(strict), 균형(balanced), 권고(advisory) 스캔을 위한 정책 프로필(Policy profiles)
• 런타임(runtime)이 준비되면 기존 어댑터를 통한 실제 Hermes Agent 통합

폐쇄형 AI 에이전트는 저장소를 더 유능하게 만듭니다. 또한 저장소를 더 복잡하게 만듭니다. Hermes Guard는 그 복잡성을 감사(auditable) 가능하게 만들기 위한 작고 로컬 우선(local-first)인 첫걸음입니다. 이는 개발자들에게 에이전트가 동작하기 전에 다음과 같이 물을 수 있는 방법을 제공합니다: "이 저장소는 AI 에이전트에게 무엇을 허용하고 있는가?" 이것이 모든 에이전트형 저장소(agentic repo)가 답해야 할 질문이라고 생각합니다.