open·kritt 딥다이브
— "AI에게 취약점 찾아줘"가 안 먹히는 이유를 구조로 푼 오케스트레이션 엔진

1한 줄 정체

open·kritt는 "보안 리서치를 작은 작업 단위로 쪼개, 여러 AI 코딩 에이전트에게 격리된 일회용 컨테이너 안에서 병렬로 시키고, 그 결과를 일관된 스키마·중복 제거·심각도 순위로 정리해 주는 셀프호스팅 오케스트레이션 플랫폼"이다. 사용자는 웹 UI에서 워크플로우(프롬프트들의 사슬)를 짜고, 분석할 저장소를 지정해 스캔(scan)을 돌린다. 엔진은 그 스캔을 잡(job)으로 쪼개 에이전트들에게 분배하고, 나온 findings를 검증·순위화해 대시보드에 쌓는다.

기술적으로 정확히 말하면, open·kritt는 Postgres를 중앙 상태 저장소·작업 큐로 삼는 5개 서비스의 docker-compose 시스템이다. React 프론트엔드가 워크플로우 빌더/대시보드를 그리고, Express+Prisma 백엔드가 저장(persist) API를 맡으며, Python으로 짠 open_kritt_engine이 실제 스캔을 집행한다. 엔진은 자기 안에 Docker CLI를 품고 있어, 스캔마다 사이드카(sibling) 잡 컨테이너를 새로 띄워 그 안에서 코딩 에이전트를 실행한다. "기능 = 스텝 = 갈아끼울 수 있는 프롬프트 부품"이라는 등식이 이 저장소 전체를 관통한다.

2왜 주목받는가 — "통째로 던지기"의 실패를 구조로 푼다

첫째, 핵심 주장이 반(反)직관적이고 설득력 있다. README 첫 문단이 대놓고 말한다 — "모델에게 저장소 전체를 가리키며 취약점을 찾으라고 하면 거의 잘 안 된다." 대부분의 "AI 보안 도구"가 더 크고 똑똑한 모델을 자랑할 때, open·kritt는 방향을 튼다: 리서치를 작고 잘 정의된 작업으로 쪼개, 에이전트들에게 병렬로 돌리고, 출력을 합쳐 검증·우선순위화한다. 이건 프롬프트 요령이 아니라 작업 분해(task decomposition) + 앙상블이라는 시스템 설계다.

둘째, "진짜 리서치에서 나온 도구"라는 출처가 강하다. 만든 Kritt 팀은 버그바운티 이름 Blockian으로 Immunefi·HackenProof에서 150만 달러 이상 보상을 받은 실전 리서처들이다. open·kritt는 그들의 내부 파이프라인을 오픈소스로 증류한 것 — 즉 "이론상 좋아 보이는 설계"가 아니라 돈을 벌어 온 실전 워크플로우가 코드가 됐다.

셋째, "통제권을 사용자에게 준다". 프롬프트·워크플로우·모델 공급자·인프라를 전부 사용자가 소유한다. 모델은 BYO(Bring Your Own) — Codex 로그인이든 OpenAI·Anthropic·OpenRouter API 키든 원하는 걸 꽂는다. AGPL-3.0 라이선스로 완전 오픈소스이고, 데이터는 내 Postgres에만 남는다. "블랙박스 SaaS 스캐너"와 정반대 지점이다.

넷째, 격리를 진지하게 설계했다. 코드 분석 에이전트는 대상 저장소의 코드를 실제로 실행·컴파일해 봐야 할 때가 있는데(=신뢰할 수 없는 코드 실행), open·kritt는 이를 일회용(disposable) 잡 컨테이너 안에 가두고, 자격증명(credential)은 chmod 0700 경계 뒤에 숨긴다. "AI에게 도구를 쥐여 주되, 폭발 반경(blast radius)을 컨테이너로 제한한다"는 실무 감각이 코드에 녹아 있다.

3기술 스택 전체 지도

open·kritt의 첫 번째 놀라움은 "한 시스템 안에 언어가 두 개"라는 점이다. 무거운 오케스트레이션·프로세스 제어는 Python 엔진이 맡고, 사용자와 맞닿는 API·UI는 Node.js/React가 맡는다. 이건 흔한 실무 선택 — "동시성 많은 IO·서브프로세스 관리는 Python이 편하고, 웹 UI는 JS 생태계가 압도적"이라는 현실을 그대로 반영한다.

백엔드 — 얇은 "저장 계층"으로서의 Express + Prisma

백엔드(open-kritt-backend)는 의외로 얇다. Express 5(최신 메이저)와 Prisma(타입세이프 ORM)로 Postgres 앞에 REST를 씌운 게 전부다. 라우트 목록이 곧 이 앱의 도메인 지도다: workflows·steps·scans·vulnerabilities·postScripts·severityRankers·agentSkills·generations·modelProviders·accounts·settings. 핵심 설계 결정은 "무거운 일은 절대 백엔드가 하지 않는다"는 것 — 백엔드는 워크플로우와 스캔 요청을 DB에 저장만 하고, 실제 실행은 Postgres 큐를 폴링하는 Python 엔진이 가져간다. 로깅은 pino(고성능 JSON 로거)를 쓴다.

프론트엔드 — 워크플로우를 "그리는" 곳

프론트엔드(open-kritt-frontend)는 React 18 + Vite 8 SPA다. 컴포넌트 이름만 봐도 이 앱이 뭘 하는지 드러난다 — PromptEditor(프롬프트 편집), SchemaEditor(출력 스키마 편집), WorkflowModelConfiguration(스텝별 모델 선택), CommandPalette(⌘K 빠른 이동), Markdown(findings 렌더). 의존성이 React·React-DOM·React-Router 딱 3개로 극도로 절제돼 있는 게 인상적이다. 상태관리 라이브러리(Redux 등)도, UI 키트도 없이 순수 React로 간다 — "도구는 최소, 로직은 명확히"라는 취향이 보인다. 테스트는 Vitest로 컴포넌트마다 .test.jsx가 짝지어 붙어 있다.

엔진 — 시스템의 심장 (Python)

진짜 복잡도는 여기 있다. open_kritt_engine 패키지는 파일 하나가 7만 줄에 육박하는 모듈들의 집합이다: worker.py(워커 루프)·workspace.py(잡 작업공간 준비)·harnesses.py(에이전트 어댑터)·db.py(DB·재시도)·post_processing.py(후처리)·generation.py(AI로 워크플로우 초안 생성)·prompting.py(템플릿 렌더). Postgres는 Prisma 없이 psycopg로 직접 다루고, 출력 검증은 jsonschema Draft 2020-12로 한다. 이 엔진이 하는 일을 다음 섹션에서 해부한다.

4아키텍처 심화 — 스텝·하네스·일회용 잡 컨테이너

open·kritt의 아키텍처는 세 개의 핵심 개념 위에 서 있다: ① 스텝(step)으로 쪼갠 워크플로우, ② 이질적 에이전트를 감싸는 하네스(harness), ③ 격리·폐기되는 잡 컨테이너. 전체 그림부터 보자.

핵심 패턴 ① — 스텝 × 깊이(depth): 워크플로우라는 미니 프로그래밍 언어

open·kritt의 워크플로우는 사실상 "프롬프트로 짜는 데이터 파이프라인"이다. 워크플로우는 여러 스텝(step)으로 이뤄지고, 각 스텝은 하나의 프롬프트 + 그 프롬프트가 반드시 내야 하는 구조화된 출력(output format) 선언이다. 스텝은 깊이(depth)로 묶여 순서대로 실행되며, 한 깊이의 출력이 다음 깊이의 입력으로 흐른다.

# 스텝 하나의 구성 요소 (docs: "What are steps?")
Name          # 사람이 읽는 라벨
Content       # 에이전트에 보낼 프롬프트, {{변수}} 자리표시자 포함
Output format # 이 스텝이 낼 key와 타입 (string/number/boolean/array/object)
Depth         # 몇 번째 층인가 (0 = 진입점)
Multi-output  # 입력 하나당 결과 여러 개를 낼 수 있는가
Consume all   # 이전 층 전체를 한 배치로 받는가

여기서 가장 영리한 제약은 "마지막(terminal) 스텝은 특별하다"는 규칙이다. 가장 깊은 스텝은 반드시 고정된 finding 스키마를 뱉어야 하고, 빌더는 그 스키마가 갖춰지기 전엔 저장을 막는다. 필수 키는 이렇게 정해져 있다:

explanation, file_path, line, summary, trigger_flow,
vulnerability_type, malicious_input_example, malicious_actor
  (+ 선택: exploitable)

이 한 줄이 시스템 전체를 지탱한다. 모든 스캔의 최종 산출물이 같은 모양이기 때문에, 그 위에서 중복 제거·심각도 랭킹·대시보드 렌더 같은 자동화가 전부 가능해진다. "자유로운 자연어 출력"을 "타입이 정해진 레코드"로 강제 변환하는 것 — 이게 LLM을 파이프라인 부품으로 쓰는 핵심 기술이다.

핵심 패턴 ② — 하네스(harness): 서로 다른 에이전트 CLI를 하나의 인터페이스로

Claude Code, Codex, Cursor Agent는 각각 다른 회사가 만든 다른 CLI다 — 실행법도, 실패 방식도, 인증도 제각각이다. harnesses.py(7만 줄 규모)는 이들을 "하네스"라는 공통 어댑터로 감싸, 엔진 입장에선 "어떤 에이전트든 똑같이 호출"할 수 있게 만든다. 특히 인상적인 건 실패를 1급 시민으로 분류한다는 점이다:

# harnesses.py — 재시도 불가 실패 taxonomy(발췌)
NON_RETRYABLE_HARNESS_FAILURES = {
  "auth_failed", "configuration_error", "cyber_safety_blocked",
  "invalid_output_schema", "model_access_denied",
  "model_unavailable", "quota_exceeded", "start_failed", ...
}
# ↔ 일시적(재시도 가능) 실패: 속도제한(rate limit) 계열은 따로 분류

왜 중요한가? 수십 개 잡을 병렬로 돌리면 실패가 예외가 아니라 일상이다. 어떤 실패는 재시도하면 낫고(속도 제한), 어떤 실패는 재시도해봤자 소용없다(인증 실패·스키마 불일치). 이 둘을 코드 레벨에서 명시적 집합(frozenset)으로 구분해 두면, 워커는 "이건 잠시 뒤 다시, 저건 즉시 포기"를 자동 판단할 수 있다. 견고한 분산 작업 시스템의 전형적 설계다.

핵심 패턴 ③ — 일회용 잡 컨테이너 (Docker-out-of-Docker)

엔진 컨테이너의 Dockerfile을 보면 docker:27-cli를 통째로 복사해 넣는다. 즉 엔진은 자기 안에서 docker run을 호출해 형제(sibling) 컨테이너를 새로 띄운다 — 이 패턴을 DooD(Docker-out-of-Docker)라 부른다. 스캔이 시작되면 엔진은 대상 레포의 쓰기 가능한 사본을 만들고, Claude Code/Codex/Cursor가 설치된 일회용 컨테이너를 띄워 그 안에서 에이전트를 root로 실행한다.

핵심 패턴 ④ — Postgres를 큐·락·상태의 단일 진실원으로

open·kritt는 별도의 메시지 브로커(RabbitMQ·Redis 등)를 쓰지 않는다. Postgres 하나가 큐·상태 저장소·동시성 제어를 전부 겸한다. db.py에는 이 철학이 코드로 박혀 있다 — 속도 제한 시 지수 백오프(exponential backoff)로 재시도하고(기본 60초 → 최대 10분), 쿼터 소진은 최대 8일까지 끈질기게 재시도하며, 스캔 진입은 Postgres 자문 락(advisory lock)으로 조율한다.

# db.py — 재시도 정책 상수(발췌)
RATE_LIMIT_RETRY_BASE_SECONDS = 60.0        # 첫 재시도 대기
RATE_LIMIT_RETRY_MAX_SECONDS  = 10 * 60.0   # 상한 10분
QUOTA_RETRY_MAX_SECONDS = 8 * 24 * 60 * 60  # 쿼터 소진은 최대 8일 재시도
QUEUED_SCAN_ADMISSION_LOCK = (0x6B726974, ...)  # 스캔 진입 자문 락

이 선택의 장점은 운영 단순성이다. 셀프호스팅 사용자가 브로커를 따로 세울 필요 없이 docker compose up 하나로 전부 뜬다. "규모가 극단적으로 크지 않다면, Postgres가 큐도 겸하게 하라"는 요즘 백엔드 트렌드(예: SELECT ... FOR UPDATE SKIP LOCKED)의 실전 사례다.

5디렉토리 구조 해부

이 구조에서 읽어야 할 신호는 세 가지다. 첫째, 언어 경계가 폴더 경계와 일치한다 — engine/는 순수 Python, backend/·frontend/는 JS. 둘째, 엔진 폴더 하나에 복잡도가 몰려 있다 — 나머지는 얇고, 진짜 알맹이는 open_kritt_engine/에 있다. 셋째, 문서(docs-site/)가 코드와 같은 저장소에 있어, 개념(스텝·랭커·post-script)을 코드와 대조하며 읽을 수 있다.

데이터 모델이 곧 도메인 사전

schema.prisma의 모델 이름을 나열하면 open·kritt의 세계관이 그대로 드러난다:

6학습 포인트 — 기술별 배울 것

① LLM 엔지니어링 — "구조화된 출력"의 교과서

open·kritt에서 가장 이식성 높은 교훈은 "자연어 출력을 스키마로 강제하라"다. schema.py는 사용자가 선언한 output format을 JSON Schema(Draft 2020-12)로 변환하고, 에이전트가 그 스키마에 맞는 JSON을 낼 때까지 검증한다. 배울 점: (1) LLM을 파이프라인에 넣으려면 출력이 파싱 가능한 레코드여야 한다, (2) "마지막 단계는 고정 스키마"라는 제약 하나로 하류 자동화 전체가 열린다, (3) 스키마 위반을 invalid_output_schema라는 재시도 불가 실패로 분류해 무한 재시도를 막는다.

② 분산 작업 시스템 — 큐·워커·재시도의 정석

worker.py·db.py·queue.py는 "실패에 강한 작업 시스템"의 살아 있는 예제다. 배울 점: 지수 백오프(속도 제한 대응), 실패 taxonomy(재시도 가능/불가 구분), 자문 락(중복 실행 방지), 워커 자동 스케일링(ENGINE_AUTOSCALE_SCAN_WORKERS_ON_PROVIDER_CAPACITY — 프로바이더 여력에 따라 워커 수 조절). 이 패턴들은 보안과 무관하게 어떤 배치 처리 시스템에도 그대로 옮겨진다.

③ 컨테이너 격리 — DooD와 폭발 반경 제한

engine/Dockerfile과 workspace.py에서 Docker-out-of-Docker로 일회용 컨테이너를 띄우는 법을 볼 수 있다. 배울 점: (1) 신뢰할 수 없는 작업은 폐기형 컨테이너에 가둔다, (2) 자격증명은 chmod 0700 경계·읽기전용 마운트·심볼릭 링크로 계층 분리한다, (3) 멀티스테이지 빌드로 docker-cli + node + python + 에이전트 CLI 3종을 한 이미지에 조립한다. "AI에게 도구를 주되 샌드박스로 가둔다"는 에이전트 인프라의 필수 감각이다.

④ 폴리글랏 아키텍처 — 언어를 일에 맞게

왜 한 언어로 통일하지 않았을까? 배울 점: 무거운 서브프로세스·동시성·프로세스 제어는 Python이 라이브러리(psycopg, subprocess)와 함께 편하고, 웹 UI·타입세이프 API는 JS 생태계(React, Prisma)가 압도적이다. 두 세계를 Postgres라는 공용 계약으로만 잇고 서로 직접 호출하지 않게 하면, 각 팀/각 언어가 독립적으로 진화할 수 있다.

⑤ 프론트엔드 — "최소 의존성" 리액트

상태관리 라이브러리도 UI 킷도 없이 React+Router 3개 의존성으로 복잡한 빌더 UI를 만든 사례다. 배울 점: lib/에 순수 함수(폴링·드래프트·모델 오버라이드)를 모으고 컴포넌트는 얇게 유지하는 법, 컴포넌트마다 .test.jsx를 짝지어 붙이는 테스트 문화. "도구를 늘리기 전에 플랫폼(React) 자체로 얼마나 갈 수 있는지"를 보여 준다.

7하드웨어 / 시스템 요구사항

open·kritt는 GPU가 필요 없다 — 모델 추론은 전부 외부 프로바이더(Anthropic·OpenAI·OpenRouter 등)가 대신하기 때문이다. 대신 Docker를 활발히 쓰고, 에이전트가 root로 인터넷에 접근하므로 "성능"보다 "격리"가 요구사항의 중심이다.

동시성 관련 노브도 풍부하다: ENGINE_WORKER_COUNT(엔진 이미지 기본 25, .env.example은 2로 보수적), ENGINE_MAX_CONCURRENT_SCANS, ENGINE_WORKERS_PER_ACCOUNT(계정당 15), ENGINE_HARNESS_TIMEOUT_SECONDS(잡 타임아웃 7200초=2시간). 즉 "한 계정으로 몇 개까지 병렬로 밀지"를 프로바이더 여력에 맞춰 조절하는 게 튜닝의 핵심이다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소 — github.com/Kritt-ai/open-kritt (AGPL-3.0, v1.2.0)
• 공식 사이트 — kritt.ai
• 문서(Docs) — docs.kritt.ai · 설치·설정 가이드
• 스텝/워크플로우 개념 — 저장소 docs-site/workflows/ · docs-site/severity-ranker/ · docs-site/post-scripts/
• 위협 모델(반드시 읽기) — 저장소 docs/threat-model.md
• 런치/리서치 글 — kritt.ai/open-kritt-launch
• 배경 지식 — Docker Compose 문서 · JSON Schema(Draft 2020-12) · Prisma ORM · "Postgres as a queue"(SKIP LOCKED) 패턴 · OWASP Top 10