Deepsec 딥다이브
— 코딩 에이전트에게 "네 회사 전 코드베이스를 감사해봐"라고 시키는 도구

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 "a security harness for finding vulnerabilities in your codebase powered by coding agents" — 직역하면 "코딩 에이전트로 구동되는, 코드베이스 취약점을 찾는 보안 하니스(security harness)"다. 보안 하니스 (security harness)란 취약점 탐지 로직 자체가 아니라, "탐지 도구(여기선 AI 에이전트)를 대량의 코드에 체계적으로 투입하는 실행 골격"을 뜻한다 — 사람이 등산할 때 매는 안전벨트(harness)처럼, 에이전트가 코드베이스 구석구석을 안전하고 재현 가능하게 훑도록 잡아주는 틀이다.

README는 비용도 숨기지 않는다: "최고 성능 모델을 최대 사고 수준(maximum thinking levels)으로 쓰도록 설정되어 있어, 대형 코드베이스 스캔은 수천~수만 달러가 들 수 있다"고 명시한다. 싸구려 도구가 아니라 "정말 중요한 레포를 한 번 제대로 훑는" 용도다. 중단되면 이어서 재개하고, 이미 분석한 파일은 건너뛴다.

2왜 주목받는가

트렌딩 이유 · 기존 SAST/DAST 스캐너 대비 장점.

2026년 상반기 "AI 에이전트가 코드를 감사한다"는 아이디어 자체는 새롭지 않다. 하지만 deepsec이 주목받는 이유는 Vercel이 자기 프로덕션 코드에 실제로 돌리고 있는 도구를 그대로 오픈소스로 공개했다는 점, 그리고 "싸고 빠른 정적분석" 대신 "비싸도 되니 정확한 것"을 정면으로 선택했다는 포지셔닝이다. 처음부터 "이거 비쌉니다, 그래도 오래 숨어있던 버그를 잡는 게 그만한 가치가 있다"고 못박는다.

기존 방식과 무엇이 다른가

3기술 스택 전체 지도

모노레포 4개 패키지 + AI 에이전트 3종 + 분산 실행 인프라.

4아키텍처 심화 분석

"싸게 넓게 훑고, 비싸게 깊게 판다" — 5단계 파이프라인.

deepsec의 뼈대는 docs/architecture.md가 명시한 5단계 파이프라인이다. 각 단계는 독립된 CLI 서브커맨드이고, 모두 같은 온디스크 저장소(data/<projectId>/)를 읽고 쓴다. 핵심 설계는 "각 단계가 이전 결과를 덮어쓰지 않고 추가한다"는 것 — 재실행해도 안전하고, 중단됐다 재개해도 중복 작업이 없다.

① scan — 정규식 200개로 "볼 만한 곳" 고르기 (무료)

packages/scanner/src/matchers/ 아래 198개의 매처(matcher) 파일이 프로젝트 루트를 훑는다. 각 매처는 SQL 인젝션, 인증 우회, XSS 같은 카테고리 하나를 담당하고, 여러 개의 정규식 + 프레임워크별 게이트(예: Express 라우트인지 package.json으로 먼저 확인)로 후보를 찾는다. 이 단계는 AI 호출이 전혀 없어 무료고, 2천 파일 레포도 ~15초면 끝난다.

// packages/scanner/src/matchers/sql-injection.ts (일부)
export const sqlInjectionMatcher: MatcherPlugin = {
  noiseTier: "precise",               // precise/normal/noisy 3단계 — 우선순위에 반영
  slug: "sql-injection",
  filePatterns: ["**/*.{ts,tsx,js,jsx}"],
  match(content, _filePath) {
    return regexMatcher("sql-injection", [
      { regex: /`\s*SELECT\s+[^`]{0,400}\$\{/,
        label: "template literal SELECT with interpolation" },
      { regex: /['"]SELECT\s+[^'"]{0,400}['"]\s*\+/,
        label: "string concat SELECT" },
      // ... LIKE/RLIKE/INSERT/UPDATE/DELETE 변형까지 총 15개 패턴
    ], content);
  },
};

매처마다 noiseTier(precise/normal/noisy)가 있어, 나중에 배치 순서를 정할 때 "더 확실한 패턴"부터 AI에게 넘긴다. 매처는 examples 필드로 자체 테스트 예시까지 갖고 있어(packages/scanner/src/__tests__/matcher-examples.test.ts), 새 매처를 추가해도 회귀 테스트가 자동으로 붙는다.

② process — AI 에이전트가 실제로 코드를 읽고 판정 (가장 비싼 단계)

후보 파일들은 디렉토리 기준으로 5개씩 묶여(batch) AI에게 전달된다(packages/processor/src/batch.ts) — 같은 폴더 파일은 서로 관련이 깊어서 묶어 보내면 문맥을 공유할 수 있다는 논리다. 프롬프트는 고정 템플릿이 아니라 코어 프롬프트 + 감지된 기술스택 하이라이트 + 이 배치에 걸린 슬러그별 메모를 그때그때 조립한다(packages/processor/src/prompt/assemble.ts).

실제로 AI에게 전달되는 핵심 지시(packages/processor/src/prompt/core.ts)는 역할 부여부터 시작한다: "You are a world-class security researcher... You think like an attacker". 그다음 심각도 분류표(CRITICAL/HIGH/MEDIUM + HIGH_BUG/BUG), 알려진 취약점 슬러그 목록, 그리고 결정적으로 "정적 분석만 하라 — 절대 취약점을 재현·실행·공격하지 마라"는 명시적 금지 조항이 들어간다.

흐름 한 줄기 끝까지 따라가기 — "SQL 인젝션 후보 하나가 리포트로 나오기까지"

단계별로 실제 데이터가 어떻게 바뀌는지 추적해보자.

③ revalidate — 다시 읽고 진짜인지 재확인

process가 낸 판정을 같은(또는 다른) AI 에이전트가 한 번 더 검토한다. 이번엔 코드만이 아니라 git 히스토리까지 참고해 "이미 고쳐졌는지(fixed)"까지 확인한다. 결과는 true-positive / false-positive / fixed / uncertain 넷 중 하나. 문서에 따르면 이 단계 하나로 오탐률이 50% 이상 줄어든다. HIGH 이상 심각도에는 반드시 돌리길 권장한다.

④ AI 백엔드 3종 — 같은 계약, 다른 실행기

packages/processor/src/agents/ 아래 Claude·Codex·Pi 세 플러그인이 같은 인터페이스(AgentPlugin)를 구현한다. 셋 다 같은 프롬프트, 같은 JSON 출력 스키마를 쓰지만 실행 방식이 다르다 — Claude는 Claude Agent SDK로 로컬 OS 샌드박스(bubblewrap/Seatbelt)까지 씌우고, Codex는 처음부터 읽기 전용 샌드박스에서 grep 위주로 빠르게 돈다. findings는 에이전트 간에 자동으로 중복 제거(dedupe)되므로, Claude로 한 번 돌리고 Codex로 다시 돌려 "두 번째 의견"을 받는 것도 안전하다.

// packages/processor/src/agents/claude-agent-sdk.ts — 환경변수 화이트리스트
const CLAUDE_ENV_ALLOWLIST = new Set([
  "PATH", "HOME", "USER", "SHELL", "TERM", "TZ", "LANG", ...
]);
// 프롬프트 인젝션 방어: 레포 안의 악성 콘텐츠가 에이전트에게
// "환경변수 다 출력해"라고 시켜도 GITHUB_TOKEN, AWS_* 는 애초에
// 자식 프로세스 환경에 없어서 유출이 불가능하다.

⑤ 대규모 분산 — Vercel Sandbox로 워커 병렬화

파일 수천 개짜리 모노레포는 로컬 한 대로 오래 걸린다. pnpm deepsec sandbox process --sandboxes 10는 작업 트리를 tar로 묶어 업로드하고(.git은 제외), Vercel Sandbox 마이크로VM 10대에 파일 목록을 분할(partition)해 각자 process를 돌린 뒤 결과를 병합(merge-records)한다. 마이크로VM (microVM)이란 일반 가상머신보다 훨씬 가볍고 빠르게 뜨는 격리 실행 단위로, 워커마다 독립된 샌드박스를 통째로 새로 만드는 셈이라 한 워커가 이상해져도 다른 워커에 영향이 없다.

5디렉토리 구조 해부

4개 패키지 모노레포 + 스캔당한 코드가 저장되는 곳.

6학습 포인트 (기술별)

이 저장소 하나로 배울 수 있는 것 + 실습 아이디어.

6-1. 정규식 매처 설계 — "노이즈 등급"이라는 아이디어

198개 매처 각각이 noiseTier: "precise" | "normal" | "noisy"를 선언한다. SQL 인젝션처럼 패턴이 명확한 건 precise, "인증 관련 코드 전반"처럼 넓게 잡는 auth-bypass는 normal이다. 이 값이 나중에 noiseScore()로 배치 우선순위를 정하는 데 쓰인다 — 확실한 후보부터 AI에게 먼저 보내는 전략이다.

6-2. AI 프롬프트를 코드처럼 조립하기

assemblePrompt()는 프롬프트 엔지니어링을 "긴 문자열 하나"가 아니라 코어 + 조건부 하이라이트 + 조건부 슬러그 메모로 나눠 조립 가능한 구조로 짰다. 토큰 예산(문자 6000자, 대략 1500토큰)을 넘으면 자동으로 요약본으로 강등하는 로직까지 있다 — "프롬프트가 길어질수록 모델이 산만해진다"는 실전 교훈이 코드에 그대로 녹아 있다.

// packages/processor/src/prompt/assemble.ts (개념 요약)
const sections = [CORE_PROMPT];
if (frameworkSection.length <= 6000) sections.push(frameworkSection);
else sections.push(oneLineFallback);      // 폴리글랏 레포는 요약으로 강등
sections.push(slugSpecificNotes);          // 이 배치에 걸린 슬러그만
sections.push(projectInfoMd);              // INFO.md 원문 그대로 첨부

6-3. 심각도 분류 체계 설계하기

CORE_PROMPT는 CRITICAL/HIGH/MEDIUM이라는 흔한 3단계에, 보안이 아닌 버그를 위한 HIGH_BUG/BUG 두 단계를 더했다. "보안 취약점은 아니지만 데이터 유실·중단을 일으킬 수 있는 버그도 같이 보고하라"는 지시다. 매처 슬러그 하나하나가 표로 정의되어 있어, 새 카테고리를 추가하려면 이 표 + 매처 파일 한 개만 더하면 된다.

6-4. 3개의 서로 다른 AI SDK를 같은 인터페이스로 감싸기

Claude Agent SDK, Codex SDK, Pi 코딩 에이전트는 API도, 실행 방식도, 응답 형식도 다르다. deepsec은 AgentPlugin 인터페이스(investigate(), revalidate() 두 메서드) 하나로 셋을 통일했다. 새 AI 제공자가 나오면 이 인터페이스만 구현하면 --agent 플래그에 바로 꽂힌다 — docs/models.md가 실제로 "미래의 Anthropic Mythos 같은 신모델도 문자열 하나 바꾸면 된다"고 설명한다.

6-5. 프롬프트 인젝션 방어 — 환경변수 화이트리스트

코딩 에이전트에게 셸 실행 권한을 주는 도구는 필연적으로 위험하다. deepsec은 자식 프로세스(claude/codex CLI)에 process.env 전체를 넘기지 않고, PATH·HOME·TERM 같은 필수 변수 + 인증에 필요한 최소 크리덴셜만 골라 넘긴다. 레포 안에 악성 콘텐츠(프롬프트 인젝션)가 있어 에이전트가 "환경변수 다 출력해"라는 지시를 따르게 되더라도,애초에 GITHUB_TOKEN 같은 값이 그 프로세스 환경에 없어서 유출이 원천 차단된다.

7시스템 요구사항

로컬 실행 자체는 가볍다 — 진짜 비용은 AI API 토큰이다.

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

난이도별 4단계. 반드시 본인 소유이거나 명시적으로 스캔을 허가받은 코드베이스에만 실행할 것.

9관련 기술 심화 학습 로드맵

이 저장소를 출발점으로, 5주 코스.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: vercel-labs/deepsec
• 시작 가이드: docs/getting-started.md
• 아키텍처 내부: docs/architecture.md
• 모델 선택·비용: docs/models.md
• 데이터 스키마: docs/data-layout.md
• PR 리뷰 모드: docs/reviewing-changes.md
• 매처 작성법: docs/writing-matchers.md
• FAQ: docs/faq.md
• npm 패키지: npmjs.com/package/deepsec
• Vercel AI Gateway: vercel.com/ai-gateway
• Vercel Sandbox: vercel.com/docs/vercel-sandbox
• Claude Agent SDK: @anthropic-ai/claude-agent-sdk