deepsec: 대규모 코드베이스에 잠복한 취약점을 찾아내는 에이전트 기반 보안 하네스

9bow · 8월 2, 2026, 10:30오전

deepsec 소개

오래된 대규모 저장소에는 수년 전에 들어온 뒤 아무도 다시 읽지 않는 코드가 쌓여 있습니다. 상시 돌아가는 정적 분석과 PR 리뷰는 새로 추가되는 코드에 집중하므로, 이미 저장소 깊숙이 잠복해 있는 취약점은 좀처럼 드러나지 않습니다. 이런 문제를 찾으려면 저장소 전체를 한 번에 충분히 깊게 읽는 조사가 필요한데, 사람이 하기에는 규모가 너무 크고 AI에게 통째로 맡기기에는 비용을 가늠하기 어려웠습니다.

deepsec 은 vercel-labs 조직이 공개한 에이전트 기반 취약점 스캐너로, 자신의 인프라에서 직접 실행하는 보안 하네스(harness)입니다. 기존 대규모 저장소의 전체 코드를 온디맨드로 정밀 조사하는 데 최적화되어 있고, 오랫동안 잠복해 있던 찾기 어려운 문제를 드러내는 것이 목표입니다. 비용 구조도 숨기지 않습니다. 최고 성능 모델을 최대 추론 강도로 쓰도록 설정되어 있어(--thinking-level 로 조정 가능) "대규모 코드베이스에서는 스캔 비용이 수천에서 수만 달러에 이를 수 있다" 고 밝히면서, 그만큼 빠르게 패치할 가치가 있었다는 고객 경험을 함께 언급합니다.

핵심 설계는 단계 분리입니다. 무료 정규식 스캔으로 조사할 후보 지점을 먼저 좁히고, 그 후보에만 비싼 AI 조사를 배치로 돌린 뒤, 재검증 단계에서 오탐을 걸러냅니다. 대형 모노레포는 Vercel Sandbox 마이크로VM으로 작업을 분산할 수 있고, 실행이 중단되면 같은 명령을 다시 실행해 이미 분석한 파일을 건너뛰고 이어갑니다. 본 게시물에서는 deepsec의 파이프라인 구조와 시작 방법, 자체 보안 모델을 정리합니다.

상시 스캐너와 deepsec의 차이

CI에 붙는 규칙 기반 스캐너는 커밋마다 빠르게 돌지만 일반적인 CWE 패턴 위주로 잡는 것으로 알려져 있습니다. deepsec은 그 반대편을 겨냥합니다. 내장 매처가 일반 CWE 범주를 커버하되, 프로젝트별 맥락 문서(INFO.md)를 모든 조사 배치에 주입해 그 저장소 고유의 인증 헬퍼나 미들웨어 관례까지 이해한 상태로 코드를 읽게 합니다. 실행 주기도 다릅니다. 커밋마다 도는 게이트가 아니라, 필요할 때 저장소 전체를 훑는 온디맨드 정밀 조사가 기본형이고, PR 단위 검토는 process --diff 모드가 따로 담당합니다.

누구에게 유용한가

보안 예산이 있고 오래된 대규모 코드베이스를 운영하는 팀이라면, 외부 컨설팅 없이 자신의 인프라 안에서 전수 조사를 돌릴 수 있다는 점이 deepsec의 실질적인 가치입니다. 반면 개인 프로젝트나 소규모 저장소에서 무료 도구를 찾는 경우라면 비용 구조가 맞지 않습니다. 로컬에 로그인된 Claude Pro/Max나 ChatGPT Plus 구독으로도 돌아가지만, 저자들은 이를 평가 용도로 규정하고 실제 스캔에는 Vercel AI Gateway 키를 권장합니다. 전체 스캔을 감당할 사용량 여유가 구독에는 없기 때문입니다.

deepsec의 파이프라인

저장소의 docs/architecture.md 는 파이프라인을 다음과 같이 요약합니다.

       scan          process        revalidate          enrich           export
        │              │                │                │                  │
        ▼              ▼                ▼                ▼                  ▼
  candidates  →   findings    TP/FP/Fixed verdict  →  +committers  →  JSON / md-dir

각 단계는 독립된 CLI 하위 명령이고, 같은 온디스크 표현(data/<projectId>/ 아래의 FileRecord JSON)을 읽고 씁니다. 모든 단계는 멱등적이라 다시 실행하면 덮어쓰는 대신 새 정보를 병합합니다.

scan 은 AI 호출 없이 정규식 매처로 후보 지점을 모으는 무료 단계로, 2천 개 파일 기준 15초 정도가 걸립니다. process 는 대기 중인 파일을 배치로 묶어 AI 에이전트에게 보내는 가장 비싼 단계입니다. 에이전트 백엔드는 세 가지를 지원하며 같은 프롬프트와 같은 JSON 출력 스키마를 쓰기 때문에, 한 프로젝트 안에서 백엔드를 섞어 재조사할 수도 있습니다.

`--agent`	SDK	기본 모델
`codex` (기본값)	`@openai/codex-sdk`	`gpt-5.5`
`claude`	`@anthropic-ai/claude-agent-sdk`	`claude-opus-4-8`
`pi`	`@earendil-works/pi-coding-agent`	`zai/glm-5.2`

revalidate 는 기존 발견을 다시 읽고 git 이력에서 수정 여부까지 확인해 true-positive / false-positive / fixed / uncertain 판정을 붙입니다. 비용은 process 와 비슷하지만, 대부분의 저장소에서 오탐율을 경험적으로 50% 이상 줄였다고 문서에 적혀 있습니다. 이 밖에 저렴한 모델로 P0/P1/P2 를 분류하는 triage, 커미터와 소유권 정보를 붙이는 enrich, 결과를 정리하는 report · export · metrics 가 있습니다.

deepsec 시작하기

스캔할 저장소 루트에서 초기화하고, .deepsec/ 디렉토리 안에서 실행합니다.

npx deepsec init       # .deepsec/ 생성, 이 저장소를 첫 프로젝트로 등록
cd .deepsec
pnpm install           # npm에서 deepsec 설치

pnpm deepsec scan
pnpm deepsec process
pnpm deepsec revalidate # 선택 사항, 오탐율을 낮춤
pnpm deepsec export --format md-dir --out ./findings

초기화 후에는 자신이 쓰는 코딩 에이전트에게 .deepsec/node_modules/deepsec/SKILL.md 와 SETUP.md 를 읽혀 저장소 맥락 문서인 INFO.md 를 채우게 합니다. 이 문서는 모든 조사 배치에 주입되므로, 저자들은 50~100줄 분량으로 짧게 유지하고 프로젝트 고유의 인증 헬퍼·미들웨어 같은 프리미티브만 담으라고 안내합니다. 장황한 맥락은 오히려 신호를 희석시키기 때문입니다.

분산 실행과 deepsec 자체의 보안 모델

대형 모노레포는 Vercel Sandbox 마이크로VM으로 작업을 분산합니다.

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

로컬 작업 트리가 tar로 묶여 업로드되고 .git 은 제외됩니다. 한편 deepsec 자체는 "실행 환경에서 전체 셸 접근 권한을 가진 코딩 에이전트처럼 취급하라" 고 안내합니다. 신뢰할 수 있는 입력(자신의 소스 코드)을 다루도록 설계됐지만, 외부 의존성이나 벤더링된 코드로 인한 프롬프트 인젝션 우려가 있다면 샌드박스 실행이 노출 범위를 줄여 줍니다. 에이전트용 API 키는 샌드박스 바깥에서 주입되어 유출될 수 없고, 워커 샌드박스의 네트워크 송신은 코딩 에이전트 호스트로만 제한됩니다.

deepsec의 라이선스

deepsec은 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 고지 사항은 저장소의 NOTICE 파일에 함께 정리되어 있습니다.

deepsec 공식 홈페이지

deepsec 소개 Vercel 블로그

deepsec GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!