deepsec

deepsec는 자체 인프라에서 실행할 수 있는 에이전트 기반 취약점 스캐너로, 기존 대규모 저장소의 모든 코드를 온디맨드로 검토하도록 최적화되어 있습니다.

deepsec는 애플리케이션에 오랫동안 잠복해 있던 찾기 어려운 문제를 표면화하도록 설계되었습니다. 최대 추론 수준(--thinking-level로 조정 가능, docs/models.md 참조)에서 최상의 모델을 사용하도록 구성되어 있어, 대규모 코드베이스의 경우 스캔 비용이 수천 달러에서 수만 달러에 달할 수 있습니다. 고객들은 그렇지 않았다면 수정되지 않았을 취약점을 얼마나 빨리 패치할 수 있었는지에 비추어 볼 때 그 비용이 가치 있다고 평가합니다.

대규모 코드베이스의 경우 작업이 워커 머신에 병렬로 분산됩니다. 실행이 중단되거나 도중에 오류가 발생하면 동일한 명령을 다시 실행하기만 하면 됩니다 — deepsec는 이미 분석한 파일은 건너뛰고 나머지만 조사하여 중단된 지점부터 다시 시작합니다.

시작하기

스캔하려는 저장소의 루트로 이동한 후 다음을 실행하세요:

npx deepsec init       # creates .deepsec/ with this repo as the first project
cd .deepsec
pnpm install           # installs deepsec from npm

# Proceed as instructed by `init` output

이제 코딩 에이전트가 설치를 부트스트랩하도록 하세요. 원하는 에이전트를 열고 다음을 프롬프트로 입력하세요:

도구를 이해하려면 .deepsec/node_modules/deepsec/SKILL.md를 읽으세요. 그런 다음 .deepsec/data/<id>/SETUP.md를 읽고 따르세요: 이 저장소의 README, 모든 AGENTS.md/CLAUDE.md, 그리고 몇 개의 대표적인 코드 파일을 훑어본 후 .deepsec/data/<id>/INFO.md의 각 섹션을 교체하세요.

간결하게 유지하세요 — 총 50–100줄을 목표로 하세요. 섹션당 3–5개의 예시를 선택하고, 완전한 열거는 하지 마세요. 기본 요소(인증 헬퍼, 미들웨어)의 이름은 명시하되 줄 번호는 넣지 마세요. 일반적인 CWE 카테고리는 건너뛰세요 — 내장 매처가 해당 부분을 처리합니다. 프로젝트 고유의 내용만 다루세요. INFO.md는 모든 스캔 배치에 주입되며, 장황한 컨텍스트는 신호를 약화시킵니다.

그런 다음 .deepsec/ 내부에서 스캔하세요:

pnpm deepsec scan
pnpm deepsec process    
pnpm deepsec revalidate # optional, cuts FP rate
pnpm deepsec export --format md-dir --out ./findings

deepsec가 코드의 더 많은 부분을 살펴봐야 한다고 생각되면, 매처 작성 문서를 제공하여 코드베이스에서 더 가치 있는 시작점을 찾게 하세요.

문서

• docs/getting-started.md — 첫 스캔 안내
• docs/reviewing-changes.md — PR 검토 및 CI 게이팅을 위한 process --diff
• docs/supported-tech.md — deepsec가 기본적으로 인식하는 프레임워크 및 에코시스템
• docs/writing-matchers.md — 코딩 에이전트에 프롬프트하여 매처 세트를 확장하세요
• docs/configuration.md — deepsec.config.ts 참조
• docs/plugins.md — 플러그인 작성
• docs/models.md — 모델 선택, 기본값, 거부, 향후 모델
• docs/vercel-setup.md — AI Gateway + Vercel Sandbox 키 / 토큰
• docs/architecture.md — 파이프라인 내부 구조
• docs/data-layout.md — data/ 스키마 (FileRecord, RunMeta, …)
• docs/faq.md — 비용, 모델 선택, 샌드박스 모드, FP 비율
• samples/ — 복사하여 사용할 수 있는 시작점 (현재: webapp/)
• CONTRIBUTING.md — 저장소 구조, 개발 워크플로우

AI 제공자

로컬에서 실행할 때 deepsec는 이 머신에 로그인되어 있다면 기존 claude / codex 구독으로 폴백합니다. 구독(Claude Pro/Max, ChatGPT Plus)은 deepsec를 평가하는 데 유용하지만, 일반적으로 전체 저장소 스캔을 수행할 만큼의 충분한 용량이 없습니다.

실제 스캔에는 Vercel AI Gateway를 사용하세요. 하나의 키로 Claude와 Codex를 모두 사용할 수 있으며, 게이트웨이의 기본 할당량은 높은 동시성의 리서치 작업에 맞게 설계되어 있습니다.

AI_GATEWAY_API_KEY=vck_...

키 발급 및 Vercel Sandbox 설정에 대한 자세한 내용은 docs/vercel-setup.md를 참조하세요. 게이트웨이를 우회하려면 ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL(또는 OpenAI 쌍)을 명시적으로 설정하세요. 명시적 값은 항상 AI_GATEWAY_API_KEY 확장보다 우선합니다.

process 또는 revalidate 실행이 업스트림 자격 증명의 할당량 또는 크레딧 소진으로 중단되면, deepsec는 정상적으로 중지되고 충전할 위치를 알려줍니다. 이후 동일한 명령을 다시 실행하면 중단된 지점부터 다시 시작합니다.

분산 실행 (선택 사항)

대규모 모노레포는 Vercel Sandbox 마이크로VM에 작업을 분산할 수 있습니다:

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

Vercel 계정이 필요합니다. 로컬 작업 트리는 tar로 압축되어 업로드되며 .git은 제외됩니다. OIDC 토큰(로컬)과 액세스 토큰(CI)이 모두 지원됩니다 — docs/vercel-setup.md를 참조하세요.

deepsec 자체의 보안 모델

deepsec는 실행 중인 환경에 대한 전체 셸 액세스 권한을 가진 코딩 에이전트처럼 취급하세요. 신뢰할 수 있는 입력(소스 코드)에서 실행되도록 설계되었지만, 외부 종속성이나 벤더링된 코드로 인한 프롬프트 인젝션에 대해 여전히 우려할 수 있습니다.

샌드박스에서 실행하면(위 참조) 잠재적 노출 범위가 상당히 제한됩니다:

• 코딩 에이전트의 API 키는 샌드박스 외부에서 주입되므로 유출될 수 없습니다
• 워커 샌드박스의 경우, 샌드박스의 네트워크 이그레스는 코딩 에이전트 호스트로 제한됩니다 (부트스트랩 프로세스 중에는 이그레스가 허용되지만, 이때 코딩 에이전트는 실행되지 않습니다)

워크플로우 참조

라이선스

Apache 2.0. LICENSE 및 NOTICE를 참조하세요.