open-kritt VPS 직접 호스팅 및 Docker 설정 방법

왜 노트북이 아닌 VPS에서 open-kritt를 직접 호스팅해야 하는가

삭제하고 다시 구축할 수 있는 서버에서 open-kritt를 직접 호스팅하십시오. 이 도구는 분석 에이전트를 일회용 작업 컨테이너 내부의 root 권한으로 실행하며, 각 에이전트에 코드의 쓰기 가능한 복사본과 직접적인 인터넷 접근 권한을 부여하고, 호스트의 Docker 소켓을 엔진 서비스에 마운트합니다. 이 작업 전용 서버라면 합리적인 절충안이지만, SSH 키가 저장된 개인용 기기에서는 위험한 선택입니다.

이러한 권고는 기본 설정의 네 가지 특성에서 비롯되며, 이 모든 내용은 프로젝트의 README와 compose 파일에 명시되어 있습니다.

에이전트는 강력한 권한을 갖도록 설계되었습니다. README에 따르면 도구 기반 에이전트는 일회용 작업 컨테이너 내부에서 root 권한으로 실행되며, 쓰기 가능한 저장소 복사본과 직접적인 인터넷 접근 권한을 가집니다. 이를 통해 에이전트는 도구를 설치하고, 대상을 컴파일하며, 테스트를 수행하고, 개념 증명(PoC)을 빌드할 수 있습니다. 스캔은 단순히 파일을 읽는 린터(linter)가 아닙니다. 사용자가 요청한 임의 코드 실행입니다. 인터넷 접근 권한은 양날의 검입니다. 에이전트가 대상을 조사하는 동안 가져오는 모든 데이터는 프롬프트 내부로 들어오는 신뢰할 수 없는 텍스트이며, 이는 에이전트에게 웹 검색 기능을 제공할 때 감수해야 하는 위험과 동일합니다.

엔진이 Docker 소켓을 보유합니다. docker-compose.yml은 호스트의 Docker 소켓을 엔진 서비스에 마운트합니다. 엔진이 작업당 하나의 스캔 컨테이너를 빌드하고 실행하기 때문입니다. 해당 소켓에 접근할 수 있는 모든 프로세스는 호스트 파일 시스템을 마운트하는 컨테이너를 시작할 수 있습니다. 따라서 엔진은 이를 실행하는 호스트의 root 권한을 사실상 보유하게 됩니다.

로그인 화면이 없습니다. 백엔드는 애플리케이션 인증 기능을 제공하지 않습니다. 포트에 접근할 수 있다는 것은 곧 스캔 결과와 서비스 제공자의 크레딧에 접근할 수 있음을 의미합니다.

스캔하는 코드는 종종 본인의 것이 아닙니다. 에이전트를 타사 저장소로 지정하는 것은 해당 저장소의 빌드 과정을 본인의 머신에서, root 권한으로, 네트워크 접근 권한을 부여한 채 실행하는 것과 같습니다.

코딩 에이전트가 왜 일회용 VM에서 실행되어야 하는지에 대해 읽어보셨다면, 이는 동일한 위협 모델이며 그 강도가 더 높다는 것을 알 수 있습니다. open-kritt를 위한 별도의 VPS를 마련하고, root 계정이 아닌 최소 권한을 가진 별도의 사용자 계정으로 해당 VPS를 운영하십시오.

open-kritt의 실제 동작 방식

open-kritt(저장소는 Kritt-ai/open-kritt이며, AGPL-3.0 라이선스를 따릅니다)은 취약점 연구를 작은 단위의 작업으로 분할하고, 여러 AI 에이전트를 통해 병렬로 실행한 뒤, 결과에서 중복을 제거하고 순위를 매깁니다. 사용자는 워크플로우를 집중적인 프롬프트 체인으로 정의하며, 각 단계는 이전 단계에서 구조화된 컨텍스트를 전달받습니다. 스캔 대상은 원격 또는 로컬 git 저장소입니다. 분석 엔진으로는 Codex나 Claude Code를 사용합니다. 후보군이 도출되면, 선택적으로 사후 스크립트를 실행하여 검증하거나 개념 증명(PoC)을 시도할 수 있습니다.

최종적으로 얻게 되는 결과물은 순위가 매겨진 후보 목록입니다. 이를 보고서가 아닌 트리아지(triage) 큐로 활용하십시오.

시작하기 전에 필요한 것

• Ubuntu 24.04, Debian 12 또는 Rocky Linux 9가 설치된 VPS. 설치 문서에는 x86_64 및 ARM64 아키텍처에서 테스트를 완료한 배포판으로 명시되어 있습니다.
• Docker Engine 및 Compose 플러그인.
• 호스트에 설치된 Node.js 20 이상 버전. ./kritt CLI는 컨테이너 내부가 아닌 호스트에서 실행되기 때문입니다.
• 모델 제공업체 1곳: Codex 로그인 또는 OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY 중 하나.
• 비공개 저장소를 스캔할 계획인 경우에만 필요한 GITHUB_TOKEN. 제공되는 .env.example에 명시된 바와 같이, GitHub 토큰만으로는 스캔을 실행할 수 없습니다.

먼저 Docker와 Node 20 설치하기

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

새로운 그룹 멤버십이 적용되도록 로그아웃 후 다시 로그인한 다음, Compose 플러그인이 설치되었는지 확인합니다.

docker compose version

버전 문자열이 출력되면 Compose가 플러그인으로 설치된 것입니다. docker: 'compose' is not a docker command가 출력된다면 구형 독립 실행형 docker-compose 바이너리가 설치된 것이며, open-kritt은 docker compose을 호출합니다. docker 그룹의 멤버십은 호스트의 root 권한과 동일하므로, open-kritt을 실행할 계정만 이 그룹에 포함하십시오. 해당 설정에 대한 자세한 내용은 VPS에서 Docker 실행하기를 참조하십시오.

Ubuntu 24.04는 자체 저장소에서 Node 18을 제공하지만, CLI는 20 미만 버전에서 종료됩니다. NodeSource를 사용하십시오.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v

node -v은 v20. 이상의 버전을 출력해야 합니다. Rocky Linux 9에서는 동일한 작업을 위해 sudo dnf module enable nodejs:20 -y를 실행한 뒤 sudo dnf install -y nodejs을 수행합니다.

open-kritt 복제 및 특정 태그 버전 고정

git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt
git fetch --tags
git tag --list
git checkout v1.3.0

main은(는) 이동하지만 태그는 이동하지 않습니다. 2026년 8월 기준으로 최신 태그는 v1.3.0이며, 2026년 8월 4일에 게시되었습니다. git tag --list은(는) 복제 시점에 존재하는 내용을 보여줍니다. 태그를 체크아웃하면 저장소는 detached HEAD 상태가 되는데, 이는 커밋을 수행할 브랜치가 아니라 고정된 배포본으로 복제본을 다루는 상황에서 올바른 동작입니다. 나중에 업그레이드하려면 릴리스 노트를 읽은 뒤 git fetch --tags을(를) 실행하고, 새 태그를 체크아웃한 다음 start이(가) 이미지를 다시 빌드하므로 ./kritt start을(를) 다시 실행하십시오.

./kritt을(를) sudo와(과) 함께 실행하지 마십시오. 문서에 명시된 사항입니다. CLI는 .data/ 하위의 프로젝트 로컬 자격 증명 디렉터리를 관리합니다. root 권한으로 실행하면 해당 디렉터리의 소유권이 root로 변경되어, 이후 일반 사용자로 실행할 때 쓰기 권한이 없어 오류가 발생합니다.

./kritt setup을 통한 모델 접근 설정

./kritt setup

이 명령어는 .env이 존재하지 않을 경우 .env.example로부터 생성하며, 각 자격 증명의 상태를 출력하고 설정하거나 해제할 수 있게 합니다. 명령어는 터미널에 값을 다시 출력하지 않습니다. .env과 엔진 자격 증명 파일은 모두 0600 모드로 작성됩니다.

수동으로 설정하려면 다음을 수행하십시오.

cp .env.example .env
chmod 600 .env
mkdir -p .data/codex
chmod 700 .data/codex

그런 다음 .env에 공급자 키를 편집하여 넣고 파일 권한을 0600으로 유지하십시오. 어느 쪽이든 이제 서버에 작동하는 공급자 자격 증명이 위치하게 되며, 이는 해당 서버에 다른 것을 두지 말아야 할 또 하나의 이유입니다. 이 프로젝트 전용 키를 생성하여 나중에 취소하더라도 중요한 서비스에 영향이 없도록 하십시오. AI 에이전트가 비밀에 접근하지 못하도록 관리하기에서 더 넓은 범위의 습관을 다룹니다.

첫 스캔 전에 공급자 지출 한도 설정하기

open-kritt는 작업을 분산(fan-out)하도록 설계되었으며, 이 분산 작업에 대해 비용이 발생합니다. v1.3.0 버전의 .env.example 기본값은 보수적으로 설정되어 있습니다. ENGINE_WORKER_COUNT=2은 파일 내에서 소형 2-vCPU 장비를 위한 보수적 기본값으로 설명되며, ENGINE_MAX_CONCURRENT_SCANS=1도 마찬가지입니다. 이 설정들 위에는 하나의 공급자 계정에서 허용되는 최대 동시 루트 모델 호출 수인 ENGINE_WORKERS_PER_ACCOUNT=15과, Codex 세션이 최대 5개의 하위 에이전트를 실행할 수 있다는 점을 고려한 ENGINE_CODEX_MAX_SUBAGENTS_PER_SESSION=5가 있습니다. 더 큰 VPS에서 작업자(worker) 수를 늘리면 동시에 실행되는 모델 호출 수도 함께 증가합니다.

저장소 내에는 지출을 제한하는 기능이 없습니다. .env.example에는 예산 설정 항목이 존재하지 않습니다. 엔진 자체의 중단 조건은 앞서 언급한 작업자 제한과 ENGINE_HARNESS_TIMEOUT_SECONDS뿐이며, 이는 하네스(harness) 실행당 기본값이 7200초로 설정되어 있습니다. 따라서 지출 상한선은 공급자 측에서 설정해야 합니다. 첫 스캔을 시작하기 전에 공급자 콘솔을 열고 월간 하드 리밋을 설정하십시오. 스캔이 끝난 뒤에는 이미 늦습니다. VPS에서 AI 에이전트 비용 제어하기 문서에서 공급자별 설정 방법을 안내합니다.

로컬 차원의 제동 장치도 있습니다. ENGINE_WORKER_COUNT=0을 설정하면 새로운 작업 수신이 일시 중지되며, 스택이 실행 중일 때 설정(Settings) 화면에서 동일한 작업자 값을 변경할 수 있습니다.

이 가이드는 스캔당 비용을 명시하지 않습니다. 비용은 저장소의 크기, 구축하는 워크플로우, 그리고 기반이 되는 모델에 따라 달라지기 때문입니다. 작은 저장소를 대상으로 스캔을 한 번 실행한 뒤, 대규모 저장소에 적용하기 전에 공급자의 사용량 페이지를 확인하십시오.

스택 시작 및 상태 확인

./kritt start

이 명령은 .env과 최소 하나의 자격 증명을 확인한 뒤 docker compose up --build를 실행합니다. 첫 빌드는 프론트엔드, 백엔드, 엔진, 실행기 뷰 및 데이터베이스 이미지를 모두 생성하므로 시간이 다소 소요됩니다. 또한 포그라운드에서 실행되므로 SSH 세션을 종료하면 스택도 함께 중단됩니다. tmux 내부에서 실행하거나, 첫 빌드가 성공한 후에는 백그라운드 모드로 실행하십시오. 이 방법들은 재부팅 시 자동으로 복구되지 않으므로, 서버 재시작 후에도 스택을 유지하려면 재부팅 후에도 셀프 호스팅 에이전트 유지하기에 설명된 systemd 유닛 패턴을 그대로 적용하면 됩니다.

docker compose up -d --build
docker compose ps

docker compose ps을 실행하면 open-kritt-frontend, open-kritt-backend, open-kritt-engine, open-kritt-executor-view 및 open-kritt-db이 목록에 나타나야 합니다. 그런 다음 서버 자체에서 백엔드가 응답하는지 확인하십시오.

curl -s http://127.0.0.1:3002/api/health

JSON 응답이 출력되면 백엔드가 정상적으로 실행 중인 것입니다. Failed to connect to 127.0.0.1 port 3002: Connection refused이 출력되면 실행되지 않은 상태이며, docker compose logs backend을 통해 그 이유를 확인할 수 있습니다. 저장소 디렉터리에서 docker compose down를 실행하여 모든 서비스를 중단하십시오.

선택 사항: docker compose exec backend npm run seed을 실행하면 데모 데이터를 불러올 수 있습니다. 실제 스캔에 비용을 들이기 전에 인터페이스를 확인해 볼 수 있는 간편한 방법입니다.

SSH 터널을 통해 5173 포트의 UI에 접속하기

compose 파일에 정의된 모든 서비스는 기본적으로 127.0.0.1에 바인딩됩니다. 프론트엔드는 5173, 백엔드는 3002, executor 뷰는 8090, Postgres는 5432 포트를 사용합니다. 이 바인딩 설정을 변경하지 말고, 로컬 머신에서 SSH를 통해 해당 포트를 포워딩하십시오.

ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip

명령어가 실행되는 동안 로컬 브라우저에서 http://localhost:5173를 엽니다. -N 옵션은 셸을 실행하지 않고 포트 포워딩만 수행하도록 합니다. executor 뷰도 함께 사용하려면 동일한 명령어에 -L 8090:127.0.0.1:8090 옵션을 하나 더 추가하십시오.

FRONTEND_BIND_ADDRESS=0.0.0.0를 설정하고 터널을 건너뛰고 싶은 유혹이 들 수 있습니다. 하지만 절대 그렇게 하지 마십시오. 백엔드에는 로그인 화면이 없으므로, 해당 페이지에 접근하는 누구나 스캔을 시작하여 사용자의 제공자 크레딧을 소진할 수 있습니다. 또한 그 아래에는 두 번째 함정이 있습니다. 컨테이너 포트를 외부로 공개하면 ufw의 기본 정책이 적용되기 전에 처리가 이루어지므로, ufw deny 5173 규칙이 올바르게 보일지라도 실제로는 아무것도 차단하지 못합니다. ufw를 우회하는 Docker 포트에서 이러한 현상을 유발하는 규칙 체인을 확인할 수 있습니다.

VPS 크기 산정

ENGINE_MIN_FREE_STORAGE_GB의 기본값은 20이며, 가용 저장 공간이 이 값 미만으로 떨어지면 엔진은 새로운 작업별 스캔 컨테이너 시작을 거부합니다. 빌드된 이미지, 체크아웃 캐시, Postgres 데이터, 작업 워크스페이스가 모두 같은 디스크를 사용하므로, 20 GB 용량의 VPS에서는 스캔이 전혀 시작되지 않습니다. 40 GB를 최소 사양으로 고려하고, 대규모 저장소를 스캔한다면 더 많은 용량을 할당하십시오.

메모리는 단순 산술을 따릅니다. ENGINE_MEMORY_RESERVE_GB=2은 엔진, 데이터베이스, API 및 단기 오버헤드를 위해 메모리를 확보하며, 각 스캔 러너는 ENGINE_SCAN_RUNNER_MEMORY_MB=1536의 예약 및 하드 제한을 가집니다. 따라서 워커 2개를 실행하려면 다른 작업이 시작되기 전에 약 5 GB의 메모리가 필요합니다. 엔진은 남은 예산 내에서 실행 가능한 러너만 허용하므로, 사양이 낮은 장비에서는 스캔이 실패하는 대신 대기열에 쌓이게 됩니다. 이는 OOM(Out-of-Memory) 킬러에 의해 강제 종료되는 것보다 훨씬 나은 장애 대응 방식입니다.

두 가지 정리(prune) 설정인 ENGINE_AUTO_PRUNE_DOCKER_BUILD_CACHE과 ENGINE_AUTO_PRUNE_UNUSED_DOCKER_IMAGES은 기본적으로 활성화(true)되어 있습니다. 작업이 완료되면 엔진은 사용되지 않는 빌드 캐시, 사용되지 않는 이미지, 중지된 스캔 컨테이너를 제거합니다. 실행 중인 컨테이너가 참조하는 이미지, 바인드 마운트, 데이터베이스 데이터, 자격 증명 및 볼륨은 보존됩니다. 이는 호스트를 공유해서는 안 되는 또 다른 이유입니다. 사용자가 직접 구성하지 않은 정리 도구가 해당 Docker 데몬에서 실행되고 있기 때문입니다.

로컬 저장소를 유출 없이 스캔하기

LOCAL_REPOS_PATH는 기본적으로 ./local_repos으로 설정되며, 백엔드 및 엔진 컨테이너의 /local_repos 경로에 바인드 마운트됩니다. 따라서 호스트의 해당 폴더에 저장소를 넣으면 컨테이너 내부에서 즉시 확인할 수 있습니다. 작업 중인 트리(working tree)가 아닌 새로 클론한 저장소를 사용하십시오. 작업 컨테이너는 쓰기 가능한 복사본을 가지며, 컨테이너 내부에서 root 권한을 갖고 외부 인터넷에 접근할 수 있습니다. 즉, 복사본에 포함된 모든 내용은 수정되거나 외부로 전송될 수 있습니다. 프로젝트를 복사하기 전에 .env 파일과 개인 키를 제거하십시오.

제공되는 결과와 그렇지 않은 것

순위가 매겨진 후보 탐지 결과가 제공됩니다. 검증된 취약점이 제공되는 것은 아닙니다. 순위와 중복 제거는 트리아지 대기열의 우선순위를 결정할 뿐, 해당 항목이 실제 취약점임을 증명하지는 않습니다. 포스트 스크립트(post-script)를 통해 검증을 시도하고 개념 증명(PoC)을 구축할 수 있으며, 이는 도구가 제공하는 가장 강력한 신호입니다. 하지만 포스트 스크립트가 실패했다고 해서 해당 탐지 결과가 거짓이라는 증거는 아닙니다. 모든 후보 항목은 여전히 사람이 직접 검토해야 합니다.

이 가이드는 open-kritt가 실제 버그를 얼마나 찾아내는지에 대해 어떠한 주장도 하지 않습니다. 측정된 바가 없기 때문입니다. 귀하의 코드베이스에 대한 탐지율을 언급하는 사람이 있다면, 그 사람은 귀하의 코드베이스를 대상으로 도구를 실행해 본 적이 없는 것입니다. 우선 이미 잘 알고 있는 저장소를 스캔하십시오. 직접 판단할 수 있는 탐지 결과가 가장 저렴하고 효과적인 보정 수단입니다.

이 도구는 대부분의 자체 호스팅 도구보다 권한 부여가 더 중요합니다. 에이전트가 코드를 컴파일 및 실행하고 네트워크에 접근하므로, 개념 증명 단계에서 실제 시스템에 영향을 줄 수 있습니다. 소유하고 있거나 테스트 계약을 맺은 코드만을 대상으로 지정하고, 무엇이든 실행하기 전에 대상 범위를 명시하십시오. ANTHROPIC_API_KEY을 구성하고 Claude Code 엔진을 사용하는 경우, VPS에서 안전하게 Claude Code 실행하기에 기재된 샌드박스 관례가 이 에이전트들에도 동일하게 적용됩니다.

FAQ

왜 open-kritt은 전용 VPS가 필요한가요?

분석 에이전트가 일회용 작업 컨테이너 내부에서 root 권한으로 실행되며, 코드의 쓰기 가능한 복사본을 가지고 직접 인터넷에 접속하기 때문입니다. 또한 엔진 서비스가 호스트의 Docker 소켓을 마운트하여 작업당 하나의 컨테이너를 실행하므로, 해당 소켓에 접근할 수 있는 모든 프로세스는 호스트 파일 시스템을 마운트하는 컨테이너를 시작할 수 있습니다. 따라서 전체 스택은 호스트의 root 권한을 가진 것으로 간주해야 합니다. 전용 VPS에서는 이러한 위험을 감수할 수 있으며, 서버를 재구축하는 데 비용이 들지 않습니다. 하지만 일상적인 워크스테이션에서 실행하면 SSH 키와 브라우저 프로필이 스캔 중인 코드와 동일한 신뢰 경계 내에 놓이게 됩니다.

SSH 터널을 사용하는 대신 5173 포트를 외부로 노출해도 되나요?

그렇게 해서는 안 됩니다. 백엔드는 애플리케이션 수준의 인증 없이 배포되므로, 해당 포트가 인터넷과 사용자의 분석 결과 및 제공자 크레딧 사이를 보호하는 유일한 수단입니다. 이러한 이유로 compose 파일은 모든 서비스를 127.0.0.1에 바인딩합니다. 대신 ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip를 실행하고 로컬에서 http://localhost:5173로 접속하십시오. ufw 규칙은 대안이 될 수 없습니다. Docker 포트를 공개하면 ufw의 기본 정책이 적용되기 전에 Docker가 먼저 처리하기 때문입니다.

open-kritt이 계획보다 많은 비용을 지출하지 않게 하려면 어떻게 해야 하나요?

open-kritt 자체에는 예산 설정 기능이 없으므로, 첫 스캔을 시작하기 전에 모델 제공자의 콘솔에서 하드 리밋을 설정하십시오. 처음 몇 번의 실행 동안은 기본 제공되는 동시성 설정인 ENGINE_WORKER_COUNT=2과 ENGINE_MAX_CONCURRENT_SCANS=1을 유지하십시오. 하나의 제공자 계정은 기본적으로 최대 15개의 루트 모델 호출을 동시에 허용하며, Codex 세션은 최대 5개의 하위 에이전트를 실행할 수 있다는 점을 기억하십시오. ENGINE_WORKER_COUNT=0을 실행하면 새로운 작업 수집이 일시 중지되며, 이는 가장 빠르게 로컬에서 작업을 멈추는 방법입니다.

어떤 버전을 체크아웃해야 하나요?

항상 태그를 사용하고, main는 사용하지 마십시오. git fetch --tags을 실행한 뒤 git tag --list을 확인하면 사용 가능한 버전을 볼 수 있으며, 2026년 8월 4일에 릴리스된 v1.3.0가 이 글을 쓰는 시점의 최신 버전입니다. 버전을 고정하면 몇 달 뒤에 재빌드해도 동일한 스택이 생성됩니다. 또한 업그레이드를 단순히 다른 날짜에 클론하여 발생하는 부작용이 아니라, 릴리스 노트를 읽고 결정하는 과정으로 만들 수 있습니다.

스캔이 시작되지 않습니다. 무엇을 확인해야 하나요?

먼저 디스크 여유 공간을 확인하십시오. 엔진은 여유 저장 공간이 ENGINE_MIN_FREE_STORAGE_GB(기본값 20 GB) 미만일 때 작업별 스캔 컨테이너를 실행하지 않습니다. 다음으로 ENGINE_WORKER_COUNT가 0이 아닌지 확인하십시오. 해당 값이 0이면 새로운 작업 수집이 일시 중지됩니다. 그 후 ./kritt setup를 실행하여 모델 자격 증명이 실제로 구성되었는지 확인하십시오. GITHUB_TOKEN만으로는 스캔을 실행할 수 없기 때문입니다. docker compose logs engine을 확인하면 작업을 건너뛴 이유를 알 수 있습니다.