trajeckt: 에이전트용 런타임 강화 게이트웨이(Sealed-Commitment 기반)
trajeckt는 에이전트가 호출하는 각 툴 호출을 개별적으로 평가하는 전통적 접근의 맹점을 보완하기 위해 설계된 런타임 강화(gateway)입니다. 제공된 리포지토리 자료에 따르면 주요 아이디어는 "에이전트 실행 전에 허가된 궤적(trajectory)을 컴파일해 봉인(sealed)된 그래프로 만들고, 실행 중 모든 호출을 그 그래프의 현재 도달 가능(frontier)에 대해 실패-닫힘(fail-closed)으로 검사"하는 것입니다. 이 접근은 여러 단계에 걸친 데이터 유출(exfiltration) 시나리오를 하나의 호출로는 잡아내지 못하는 기존 시스템의 구조적 한계를 메우는 것을 목표로 합니다.
요약: 리포지토리 README와 문서·예제에 나타난 핵심 흐름은 다음과 같습니다. Docker 기반 스택과 독립 실행 예제가 제공되며, 기본 모드에서는 auto_commitment로 도구 목록을 이용해 자동으로 봉인된 그래프를 만들고 세션에 설치한 뒤, 설치된 그래프 없이 도구 호출이 들어오면 명시적으로 차단합니다. 또한 운영자가 명시적으로 옵트아웃하면 휴리스틱(heuristic) 기반의 안전망을 동작시켜 알려진 악패턴만 차단합니다. 제공 자료에 없는 구현 세부(예: 내부 자료 구조의 모든 필드, 프로덕션 규모 성능 데이터)는 문서 범위에 포함되지 않아 본문에서는 출처에 근거한 기술만 서술합니다.
핵심 설계 요소
- 봉인된 커밋(Sealed-Commitment) 그래프: 에이전트가 실행할 수 있는 도구, 순서, 데이터 싱크(scope)를 사전에 선언·컴파일하고, HMAC 등으로 봉인합니다. 이 봉인이 세션의 권위(authority)가 되면 게이트웨이는 그 그래프의 현재 "도달 가능(frontier)"에 포함되지 않는 호출을 거부합니다.
- 전역 궤적 검사(trajectory-level enforcement): 각 호출은 현재 세션이 쌓아온 전체 궤적과 데이터 흐름 문맥에 대해 검사됩니다. 단일 호출은 합법적으로 보일 수 있으나, 이전 단계에서 나온 민감 데이터가 도착지로 가는 경우 마지막 단계에서 차단됩니다.
- 오프-에이전트 상태(agent-unreachable state): 에이전트의 컨텍스트 창은 잠재적으로 손상된 것으로 처리하고, 게이트웨이는 에이전트가 직접 접근할 수 없는 상태를 유지하며 검증을 수행합니다.
- 안전망(heuristic floor): 운영자가 봉인을 사용하지 않기로 명시적으로 선택하면(옵트아웃) 간단한 시퀀스 기반 휴리스틱을 적용하여 알려진 악패턴(예: ReadSensitive → ExternalWrite)을 차단합니다. 이는 1차적 제품 기능이 아닌 최후의 안전망으로 설계되어 있습니다.
실행 흐름(간단 예)
문서에 포함된 독립 실행 예제는 동일한 3단계 호출을 두 번 실행해 비교합니다. 전통적 방식(각 호출을 독립 평가)에서는 모든 호출이 허용되어 데이터 유출이 발생하지만, trajeckt의 봉인 검증을 적용한 경우 마지막 단계의 외부 전송이 차단됩니다. 예시에서 나오는 흐름(의사 코드):
read_database -> summarize -> send_email_external
# 전통적 평가: 모두 ALLOW
# trajeckt(봉인 그래프): 마지막 단계 BLOCK (exfiltration 탐지)
이 예제는 리포지토리에 포함된 cargo run --example demo 및 Docker 기반 스모크 테스트로 재현 가능합니다(문서에 기술됨).
운영 및 통합 요령
- 빠른 확인: Docker 이미지를 이용한
docker-compose up --build와/healthz엔드포인트로 기본 동작 여부를 확인할 수 있습니다(문서에 예시 커맨드 존재). - 자동 봉인(auto_commitment): 기본 모드에서는
tools/list핸드셰이크를 통해 봉인된 그래프를 자동으로 생성·설치합니다. 봉인이 설치되지 않으면 세션의 첫 도구 호출 이전에 차단됩니다. - 수동 봉인 및 설치: 운영자가
traj commit으로 명시적 봉인을 만들고trajeckt.install또는 제공된 툴로 게이트웨이에 설치할 수 있습니다. 설치된 세션은 UUID를 발급받고, 이 세션 ID를 에이전트 래퍼에 전달해야 합니다. - 세션 ID 일치성: 문서에 따르면
session_id불일치는 의도적 구성 오류로 간주되어 "no commitment installed" 형태로 차단되며, 이는 조용한 폴백(fallback)을 방지하기 위한 설계입니다.
잡는 것과 잡지 못하는 것 (제한 사항)
trajeckt 문서에서 명시하는 탐지 범위와 한계는 다음과 같습니다.
잡는 것(봉인 그래프 존재 시):
- 계획 외 호출(off-plan calls): 현재 봉인 그래프의 Frontier에 없으면 거부.
- 인증되지 않은 싱크로의 데이터 유출: provenance/권한 범위를 벗어나는 쓰기 차단.
- 민감 데이터가 고위험 행동을 제어하는 경우(taint 기반 차단).
- 궤적 수준의 인과 구조가 선언된 의도와 벗어날 때(그래프 기반 검증).
잡지 못하는 것:
- 콘텐츠의 의미(semantic)를 완전히 이해해야 탐지 가능한 공격(예: 자연어로 숨겨진 인젝션 지시). 문서에서 이 한계는 명확히 언급되어 있습니다.
- 선언된 인과 매니폴드(allowed causal manifold) 내부에서 발생하는 공격. 즉, 공격자가 궤적을 합법적으로 보이게 만들 수 있으면 차단되지 않습니다.
- 기존 정책 엔진이 제공하는 구성 기반 제어(allow/deny 목록, 인자 검증, RBAC 등)를 대체하지 않습니다. 따라서 기존 보안 제어와의 결합이 필요합니다.
ClawTrojan 벤치마크와 검증
문서에는 ClawTrojan이라는 독립 벤치마크에 대해 테스트를 수행했고, 'stealthy-delay' 패턴(cs_delay_002) 같은 일부 패턴은 end-to-end로 차단되는 사례가 명시되어 있습니다. 리포지토리의 테스트 코드(tests/clawtrojan_cs_delay_002.rs)와 enforcement 코드 간의 상호 동기화(동일한 신뢰 격자와 floor 정의를 공유)로 인해 적어도 일부 공격 패턴은 실험적으로 방어가 증명되었다고 문서화되어 있습니다. 다만 제공된 증거팩에는 모든 ClawTrojan 패턴에 대한 완전한 커버리지가 포함되어 있는지에 대한 명확한 전체 목록은 없으므로, 일반화 적용 가능성은 추가 검증이 필요합니다.
개발자 관점: 통합 예
리포지토리는 Python SDK 예제와 LangGraph 래퍼(에이전트 툴 노드용) 통합 샘플을 포함합니다. 일반적인 통합 절차는 다음과 같습니다(문서 기반 요약):
- 봉인된 그래프 생성(자동 또는 수동)
- 봉인 그래프를 게이트웨이에 설치하여 세션 ID 발급
- 에이전트 런타임에서 해당 세션 ID로 HTTP 래퍼를 사용해 도구 호출을 중계
세부 명령어와 예제는 리포지토리의 sdk-python과 examples 디렉터리에 포함되어 있으므로, 실제 통합 시 소스의 예제를 참고해 환경 변수와 키를 일치시키는 것이 중요합니다.
용어 해설
쉬운정의: 에이전트가 실행할 때 따라야 할 허가된 도구 목록과 순서를 사전에 컴파일해 암호학적으로 서명한 그래프입니다. 일상적 예: 회사 회의에서 미리 작성하고 서명한 회의 안건(누가 어떤 순서로 발언할지 정해진 문서)과 비슷합니다.
쉬운정의: 세션 동안 에이전트가 수행한 일련의 도구 호출과 그들 사이의 데이터 흐름입니다. 일상적 예: 택배가 여러 허브를 거쳐 목적지에 도착하는 경로 기록과 같습니다.
쉬운정의: 봉인 그래프에서 현재 세션 상태로부터 다음에 허용될 수 있는 도구 호출들의 집합입니다. 일상적 예: 보드 게임에서 현재 말의 위치에서 합법적으로 이동할 수 있는 칸들의 모음과 같습니다.
쉬운정의: 민감한 출처(예: 고객 DB)에서 유래해 특별 취급이 필요한 데이터 표식입니다. 일상적 예: 음식에서 이물질이 나와 다른 음식과 분리 보관하는 상황과 유사합니다.
쉬운정의: 문서에서 trajeckt과 상호작용하는 에이전트-도구 프로토콜(HTTP 기반)의 명칭입니다; 게이트웨이는 이 프로토콜의 일부 프로파일을 구현합니다. 일상적 예: 이메일 클라이언트가 서버와 주고받는 규약(예: IMAP/SMTP)과 같은 통신 규약입니다.
쉬운정의: 세션 상태가 안전 경계에 접근할 때 그 행위를 도전하거나 격리하는 행동 필터로, 궤적 안전성을 정량적으로 제어하는 메커니즘입니다. 일상적 예: 자동차의 충돌 방지 장치(ABS)가 급가속·급제동 상황에서 차량을 제어하는 것과 유사합니다.
쉬운정의: trajectory-style 에이전트 공격을 규정하고 테스트하는 독립적 벤치마크 세트 이름입니다; 문서에서 trajeckt는 이 벤치마크에 대해 테스트되었다고 보고합니다. 일상적 예: 보안 제품을 시험하는 표준 모의 해킹 시나리오 세트와 비슷합니다.
결론 및 권고
trajeckt는 에이전트-도구 통합에서 발생할 수 있는 다단계 악용을 궤적 수준에서 방어하려는 설계 철학을 제시합니다. 문서와 예제는 초기 사용자가 Docker·예제 스크립트로 빠르게 실험해볼 수 있게 구성되어 있고, 봉인된 그래프와 세션 설치, 세션 ID를 통한 엄격한 매치가 핵심 운영 패턴입니다. 다만 의미 기반 공격(semantic)과 선언된 궤적 내부에서의 위협은 여전히 남아 있으므로, 기존 정책 엔진·문맥 기반 검증과 병행해 사용해야 합니다.
참고: 이 글은 공개된 리포지토리의 README·문서·예제 파일을 근거로 요약·분석한 것입니다. 구현의 상세 내부(성능 테이블, 모든 테스트 커버리지 등)는 문서에 완전하게 포함되어 있지 않으므로, 프로덕션 도입 전 소스 코드와 테스트를 직접 검토할 것을 권장합니다.
Sources
- beebeeVB/trajeckt (GitHub repository) — license:
unknown, retrieved:2026-07-06. - Image: AI-generated cover image via OpenRouter — license:
ai-generated-original.