gif

## 개요 GIF(Governed Intelligence Framework)는 AI 도구 호출을 위한 거버넌스 런타임입니다. 에이전트가 수행한 작업을 사후에 기록하는 대신, 어떤 도구가 실행되기 전에 MCP(Model Context Protocol) 계층에서 정책을 강제합니다. 이 프로젝트는 문제를 기록이 아닌 궤적의 관점에서 바라봅니다. 단일 에이전트가 서로 관련 없는 데이터 소스 전반에 걸쳐 개별적으로는 허용 가능한 수천 건의 쿼리를 몇 초 만에 실행할 수 있으며, 그 집계로부터 도출된 추론 자체가 레코드 수준 거버넌스 표준으로는 포착하지 못하는 위반일 수 있습니다. ## 기능 AI 에이전트가 도구를 호출하면 GIF는 다음을 수행합니다. 1. 페르소나 확인 — 거버넌스 ID가 활성 상태인지, 유효 기간 내에 있는지, 해당 도구를 호출할 권한이 있는지 확인합니다. 2. 범위 강제 — 페르소나에 선언된 범위를 벗어난 호출은 거부되며 일반 오류가 아닌 1급 거버넌스 이벤트로 기록됩니다. 3. 조합 정책 평가 — 도입자의 도구 핸들러는 실행 전에 GIF가 제공하는 평가기를 호출합니다. 현재 세션에서 접근한 데이터 소스 집합이 선언된 민감도 임계값을 넘으면 해당 조합을 완성하는 호출이 차단됩니다. README의 예: 금융 기록, 인사 기록, 통신 메타데이터는 각각 단독으로는 허용될 수 있지만, 별도 호출을 통한 이들의 결합은 허용되지 않을 수 있습니다. 4. 모든 것 기록 — 허용된 호출, 거부, 세션을 데이터베이스 수준에서 INSERT 전용 권한으로 기록합니다. ## 핵심 개념 - **페르소나**: 필수적이고 null이 불가능한 선언된 목적, 명시적 도구 범위, 시간적 유효 범위, 위임 체인을 지닌 거버넌스 ID입니다. AI 행동 전에 인간 관리자가 생성합니다. - **범위**: 허용된 작업의 열거 목록. 범위 밖의 도구는 호출할 수 없습니다. - **범위 위반**: 1급 거버넌스 기록으로, 경계가 작동했다는 증거로 설명됩니다. - **조합 정책**: 세션에서 특정 데이터 소스 집합이 함께 접근되면 경계를 구성한다는 선언된 규칙입니다. GIF는 스키마, 활성 정책 평가기, 페일 클로즈드 의미론을 제공합니다. v0.1 평가기는 첫 번째 일치 정책 해석을 사용하며, 완전 평가는 v0.2 궤적 항목으로 나열되어 있습니다. - **감사 추적**: 데이터베이스 권한 수준에서 INSERT 전용 — 애플리케이션 역할은 감사 레코드를 UPDATE하거나 DELETE할 수 없습니다. - **위임 체인**: 하위 페르소나는 상위 범위의 엄격한 부분집합을 보유하므로, 하위 에이전트의 작업은 루트 관리 권한까지 추적됩니다. ## 아키텍처 두 개의 Docker 컨테이너: PostgreSQL 16과 Node.js MCP 서버. 클라이언트는 MCP 서버에 POST하며, 서버는 페르소나를 검증하고 범위를 강제한 후 도구를 디스패치합니다. PostgreSQL은 personas, sessions, audit_events, scope_violations를 보관합니다. 조합 정책 평가기는 도입자의 도구 서버가 자체 디스패치 지점에서 호출하는 프리미티브로 노출됩니다. 강제 엔진은 가져올 수 있는 패키지(`gif-enforcement`)로 제공되며 버전이 지정된 git 의존성으로 등록되어, 도입자는 GIF 소스를 수정하지 않고도 도메인 도구를 추가할 수 있습니다. ## 감사 무결성 감사 레코드는 데이터베이스 계층에서 해시 체인으로 연결됩니다. 트리거가 정규 바이트 형식에 대해 SHA-256 다이제스트를 계산하고 이를 이전 행의 다이제스트에 연결하므로, 사후 변조나 삭제는 체인을 끊습니다. 검증기 CLI는 파티션을 순회하며 다이제스트를 다시 계산하고 불일치와 체인 단절을 보고합니다. 정규 형식과 검증 절차는 별도의 Tamper-Evident Audit Record Contract 저장소(정규 형식 `audit-record-contract/1`, 원래 SEP-3004로 MCP에 제출됨)에 명시되어 있으며, GIF는 이에 대한 참조 구현입니다. 미러링된 벡터 집합이 저장소에 있으며, README에는 `npm run vectors`가 26개 벡터 통과를 기대한다고 명시되어 있습니다. ## 빠른 시작 사전 요구 사항은 Docker Engine 24+, Docker Compose v2, Git입니다. 문서화된 흐름은 `v0.2.4` 태그를 클론하고, 플레이스홀더 비밀을 제거하면서 `.env.example`을 복사하고, 생성된 `IDENTITY_HMAC_SECRET`을 추가하고, 실제 비밀번호를 설정한 후 `docker compose up -d --build`를 실행합니다. 데이터베이스는 역할, 스키마, 마이그레이션을 자동으로 초기화합니다. MCP 서버는 HMAC 비밀이 플레이스홀더로 남아 있거나 32바이트보다 짧으면 시작을 거부합니다. 게시된 두 포트는 기본적으로 `127.0.0.1`에 바인딩됩니다. `GIF_BIND_ADDR`로 이를 확장할 수 있으며, 프로덕션 배포 런북이 참조되어 있습니다. MCP 엔드포인트는 브라우저 `Origin` 헤더를 검증하여 `GIF_ALLOWED_ORIGINS`에 나열되지 않은 출처에는 403으로 응답합니다. Origin 헤더를 보내지 않는 클라이언트는 영향을 받지 않습니다. 상태 확인은 `GET /health`를 통해 이루어집니다. ## 현재 상태 README는 `v0.2.4` 고정을 권장합니다. 이 버전은 MCP SDK 2.0 기반에서 실행되며 v0.2 거버넌스 세션 의미론을 갖습니다. `session_start`로 발급되는 명시적 `gif_session_id` 핸들, 호출자 주도 종료, 벽시계 TTL이 그것입니다. 핵심 강제 기능은 완성된 것으로 설명되며 실제 PostgreSQL 16 인스턴스에 대해 엔드투엔드로 검증되었고, 통합 스위트와 적합성 시나리오가 CI를 통해 모든 커밋에서 실행되며, TypeScript strict 모드가 전체에 적용됩니다. 제공되는 기능으로는 페르소나 수명주기, Streamable HTTP 전송을 갖춘 MCP 강제 계층, 체인 검증기 CLI를 갖춘 추가 전용 해시 체인 감사 추적, 범위 위반 감지, 위임 체인 강제, 세션 관리, 도구 레지스트리와 레지스트리 기반 디스패치, 강제 패키징, 조합 정책 프리미티브, HMAC ID 토큰을 통한 프로비저너 ID 바인딩이 나열되어 있습니다. 은퇴한 MCP SDK v1 기반의 레거시 `v0.1.0` 릴리스는 더 이상 권장되지 않습니다. SQL 식별자 강화가 없으며(권고 GHSA-47gp-w74f-grvr) 백포트를 받지 않습니다. README에는 이 주입 취약점이 `v0.2.0-rc.1`까지의 태그에 영향을 미치며, `v0.2.0-rc.2`가 첫 패치 태그라고 명시되어 있고, 기존 도입자에게는 마이그레이션 문서를 안내합니다. 외부 타임스탬프 앵커, 저장 데이터 암호화, 멀티테넌트 운영 강화, 범위별 감사 체인을 다루는 규정 준수 강화 로드맵이 제품 개요에 문서화되어 있습니다. ## 문서 및 라이선스 저장소에는 평이한 언어 가이드, 제품 개요, 코드베이스 워크스루, 아키텍처 다이어그램, 비밀 문서, 기여자 및 도입자 런북, 실행 가능한 적합성 벡터가 포함되어 있습니다. Apache License 2.0에 따라 라이선스가 부여되며, 저작권은 2026 Notboatanchor Labs LLC에 있습니다.