에이전트 도구를 붙이기 전, 권한 매니페스트를 먼저 읽는 작은 검사기

어두운 배경에서 추상화된 권한 매니페스트를 사람 승인, 허용 호스트, 비밀 범위 표시로 점검하는 가로형 편집 이미지.

도구를 호출하는 에이전트는 설정이 짧아 보여도 실제 권한의 표면적은 넓다. 읽기 도구 하나와 외부 발송 도구 하나는 같은 JSON 배열 안에 있어도, 실패했을 때 남기는 결과가 다르다. 이번 작업의 질문은 단순했다. 복잡한 보안 플랫폼을 붙이기 전에, 선언 파일만 보고 놓치기 쉬운 경계를 빠르게 찾을 수 있을까?

그래서 의존성 없는 로컬 Python CLI를 만들었다. 에이전트의 도구 목록을 JSON으로 받아 Markdown 보고서를 만들고, 위험 신호가 있는 도구에 필요한 최소한의 선언이 빠졌는지 표시한다. 검사 자체는 네트워크를 호출하지 않고 입력도 기기 밖으로 보내지 않는다.

선언을 검사 대상으로 좁힌 이유

에이전트 보안은 프롬프트, 실제 IAM 권한, 실행 환경, 감사 로그까지 연결되는 넓은 문제다. 이 작은 도구가 그 전체를 보장한다고 말할 수는 없다. 대신 PR이나 설정 변경을 읽는 초기에 다음 질문을 빠뜨리지 않게 하는 데 범위를 한정했다.

사람 승인: 발송·배포·쓰기처럼 외부 효과를 낼 수 있는 도구에 승인 단계가 선언되어 있는가.
네트워크 경계: 네트워크를 쓰는 도구가 호출 가능한 호스트를 제한하는가. 외부로 나가는 데이터의 등급도 적혀 있는가.
비밀 범위: 토큰·자격증명 접근 신호가 있다면, 필요한 비밀의 값이 아니라 이름과 용도가 범위로 명시되어 있는가.
입력 경계와 목적: 어떤 입력을 받는지, 그리고 그 도구가 무엇 하나를 위해 존재하는지가 선언되어 있는가.

이 네 항목은 완전한 정책 엔진이 아니라 리뷰의 출발점이다. 예를 들어 human_approval: true가 있다고 해서 실제 승인 UI가 강제되는 것은 아니다. allowed_hosts도 런타임 방화벽을 대신하지 않는다. 하지만 선언에서조차 빠져 있다면, 구현과 운영에서 다시 확인해야 할 지점이 분명해진다.

결과는 경고가 아니라 다음 행동이어야 한다

검사기는 결과를 고·중·저 위험도로 나누고, 각 항목에 누락된 이유와 권장 조치를 함께 적는다. 예를 들어 외부 전송 성격의 도구가 승인 표시 없이 선언되면, 읽기 전용 도구로 분리하거나 사람 승인 단계를 추가하라고 안내한다. 네트워크 도구에 허용 호스트가 없으면 allowlist를 추가하라고 제안한다.

중요한 점은 단어만 보고 “안전하지 않다”고 판정하는 도구가 아니라는 것이다. 이름과 설명, 권한 선언에서 정적 신호를 찾는 휴리스틱이므로 오탐과 누락이 가능하다. 따라서 결과는 차단의 근거가 아니라, 사람이 매니페스트와 실제 실행 권한을 함께 다시 읽어야 한다는 표시로 다뤄야 한다.

작게 만들고 끝까지 확인한 범위

샘플 매니페스트에는 읽기 전용 지식 조회와 외부 답변 전송을 나란히 넣었다. 후자에는 사람 승인과 네트워크 경계가 빠진 상태를 의도적으로 만들고, 보고서가 해당 누락을 고위험·중간 위험으로 분리하는지 확인했다.

검증은 네 가지 단위 테스트와 세 가지 명령 경로로 했다.

읽기 전용 도구는 발견 사항 없이 통과하는지 확인했다.
발송 도구에서 승인과 허용 호스트 누락을 각각 찾는지 확인했다.
비밀 접근 범위가 빠졌을 때 별도 신호를 내는지 확인했다.
빈 도구 목록과 존재하지 않는 입력 파일을 정상 오류로 다루는지 확인했다.

실행 결과는 4개 테스트 모두 통과였고, 샘플 보고서는 미리 확인한 예시 출력과 일치했다. 존재하지 않는 입력 파일은 오류 메시지와 종료 코드 2로 끝났다. 성공 경로뿐 아니라 자동화에 연결될 때 필요한 실패 경로도 함께 확인한 이유다.

다음에 확인할 것

이 도구는 팀의 실제 도구 정의를 몇 개 읽어 봐야 유용성이 드러난다. 다음 단계에서는 서로 다른 성격의 매니페스트에 적용해, 경고가 실제 리뷰에서 놓친 결정을 찾아내는지와 오탐이 어느 정도인지 기록할 예정이다. 결과가 좋더라도 이 검사기를 실제 권한 제어로 오해하지 않는 것이 전제다. 선언 검토는 시작점이고, 실행 환경의 권한 제한과 변경 승인 절차는 별도로 남아 있어야 한다.