Vercel DeepSec, AI 코딩 에이전트를 활용한 오픈소스 보안 스캐너 살펴보기

AI 코딩 에이전트를 활용한 개발이 늘어나면서 코드 보안 검토 방식도 달라지고 있습니다. 단순히 특정 문자열이나 알려진 코드 패턴을 찾는 것만으로는 실제 보안 문제인지 판단하기 어려운 경우가 있기 때문입니다.

Vercel의 오픈소스 보안 스캐너인 DeepSec은 이러한 문제를 해결하기 위해 패턴 기반 검사를 먼저 수행하고, 이후 Codex나 Claude와 같은 코딩 에이전트가 파일 사이의 데이터 흐름과 방어 장치를 추적하는 방식으로 보안 검토를 진행합니다.

특히 PR에서 변경된 코드만 검사하는 것이 아니라 오랫동안 수정되지 않은 기존 코드까지 검사할 수 있으며, 검사 과정과 분석 이력을 저장해 작업을 중단했다가 다시 이어갈 수 있도록 구성되어 있습니다.

다만 DeepSec이 발견한 모든 항목을 실제 보안 취약점으로 볼 수 있는 것은 아닙니다. 검사 범위를 확인하고, 코드 경로를 다시 검토하며, 실제 공격 가능성과 영향을 확인하는 과정이 중요합니다.

반응형

DeepSec은 어떤 방식으로 보안 코드를 찾을까

DeepSec은 기존의 패턴 기반 스캐너와 AI 코딩 에이전트의 역할을 나눠 보안 검토를 진행합니다.

전통적인 정적 스캐너는 문자열로 조립된 SQL이나 인증 래퍼가 보이지 않는 라우트, 사용자 입력을 다른 서버로 전달하는 호출처럼 알려진 패턴을 빠르고 예측 가능하게 찾는 데 적합합니다.

하지만 패턴만으로는 다음과 같은 상황을 판단하기 어렵습니다.

• 다른 함수에서 URL을 검증하고 있는지
• 특정 라우트가 공개되어 있는지
• 요청이 사설망까지 도달할 수 있는지
• 사용자 입력 이후 다른 방어 장치가 존재하는지

DeepSec에서는 이처럼 코드의 맥락을 확인해야 하는 부분을 Codex나 Claude 같은 코딩 에이전트가 조사합니다.

전체 과정은 다음과 같은 구조로 진행됩니다.

저장소 파악 → 진입점 목록 → 패턴 검사 → AI 조사 → 재검증 → 보고서

패턴 검사는 조사해야 할 범위를 좁히고, AI 에이전트는 그중 실제로 코드 경로를 따라가며 깊은 분석을 수행하는 역할을 맡습니다.

따라서 단순히 AI 에이전트에게 "이 저장소의 보안 문제를 찾아라"라고 요청하는 방식과는 차이가 있습니다. DeepSec은 검사 범위 확인, 증분 상태, 작업 재개, 구조화된 발견 사항, 재검증, 일관된 보고 형식을 갖춘 보안 검토 하네스로 구성되어 있습니다.

PR뿐 아니라 기존 코드까지 검사

일반적인 PR 검사는 새롭게 변경된 코드에 집중합니다.

하지만 실제 애플리케이션에는 몇 년 전에 작성된 인증 코드나 출시 이후 거의 수정되지 않은 웹훅처럼 현재 변경되지 않았지만 여전히 중요한 코드가 존재할 수 있습니다.

DeepSec은 기존 저장소 전체와 PR에서 변경된 파일을 모두 검토할 수 있습니다.

전체 저장소 검사를 수행하면 최신 모델이 아직 검토하지 않은 기존 코드까지 검사 대상에 포함할 수 있습니다.

이 때문에 DeepSec의 검사는 단순히 "이번 PR에 문제가 있는가"만 확인하는 방식이 아니라, 저장소 전체에서 보안상 중요한 코드가 어떤 상태인지 확인하는 방식으로 활용할 수 있습니다.

먼저 검사 범위를 확인하는 이유

보안 검사를 수행할 때 발견 사항이 없다는 것이 항상 코드가 안전하다는 의미는 아닙니다.

중요한 파일을 검사하지 않았기 때문에 발견 사항이 없었을 수도 있기 때문입니다.

DeepSec은 초기 설정 과정에서 HTTP 라우트, RPC 핸들러, 큐 소비자, cron 작업, CLI 명령, 웹훅, 에이전트 도구 등을 구조화된 진입점 목록으로 만듭니다.

그리고 이 목록을 실제 매처가 도달한 파일과 비교해 검사 사각지대를 확인합니다.

중요한 진입점에 매처가 존재하지 않는다면 프로젝트 전용 매처 생성을 시도합니다. 그래도 검사 범위를 충족하지 못하면 유료 AI 단계로 넘어가기 전에 중단할 수 있도록 구성되어 있습니다.

즉, AI 분석을 시작하기 전에 무엇을 검사하고 있는지부터 확인하는 과정이 포함됩니다.

매처는 AI가 조사할 코드를 고르는 역할

DeepSec에서 사용하는 매처(matcher)는 보안상 민감할 가능성이 있는 코드를 조사 대상으로 선택하는 규칙입니다.

일반적으로 파일 경로와 정규식을 조합해 후보 파일을 찾습니다.

중요한 점은 매처가 취약점을 증명하는 것이 아니라는 것입니다.

매처의 역할은 어디를 더 깊게 살펴봐야 하는지를 정하는 것입니다.

매처는 다음과 같이 구분됩니다.

• precise: 특정 버그를 강하게 시사하는 패턴
• normal: 에이전트 조사가 필요한 유용한 후보
• noisy: 좁은 파일군 전체를 검토할 필요가 있을 때 사용하는 패턴

매처 범위가 지나치게 넓어지면 AI 단계로 넘어가는 파일이 많아지면서 비용도 증가할 수 있습니다.

따라서 프로젝트 전용 매처를 구성할 때는 실제 소스 디렉터리를 가리키는지, 생성 파일을 제외하는지, 의도한 진입점에 도달하는지, 후보 수가 적절한지 확인해야 합니다.

scan --matchers <slug>를 사용하면 개별 매처를 실행하고 실제로 어떤 파일이 매칭되는지도 확인할 수 있습니다.

AI 에이전트는 코드의 흐름을 따라간다

패턴 검사를 통해 후보가 선정되면 process 단계에서 코딩 에이전트가 해당 코드를 조사합니다.

에이전트에는 다음과 같은 정보가 제공됩니다.

• 소스 파일
• 후보 매칭 정보
• INFO.md
• 저장소의 코드를 추적할 수 있는 도구
• 구조화된 출력 형식

에이전트는 호출자와 미들웨어, 입력 검증, 인가, 기타 방어 장치를 확인하면서 코드 경로를 추적합니다.

그 결과 발견 사항에는 심각도와 신뢰도, 영향을 받는 코드 줄, 설명, 권장 수정 사항 등이 포함됩니다.

이 과정에서 중요한 것은 특정 코드 한 줄만 보는 것이 아니라 입력이 어디에서 들어와 어떤 경로를 거쳐 어떤 작업에 도달하는지 확인한다는 점입니다.

프로젝트 맥락을 제공하는 INFO.md

DeepSec의 프로젝트 맥락에는 INFO.md가 사용됩니다.

이 파일은 조사와 재검증, 우선순위 분류 프롬프트에 포함되는 프로젝트 정보입니다.

여기에는 다음과 같은 내용을 기록할 수 있습니다.

• 제품의 주요 기능
• 신뢰하지 않는 입력의 진입점
• 인증과 인가 방식
• 민감한 데이터
• 중요한 불변 조건
• 위험해 보이지만 의도된 패턴

자동으로 생성된 내용을 그대로 사용하는 것이 아니라 검토하고 사실에 맞게 정리하는 것이 중요합니다.

또한 INFO.md에는 비밀정보를 넣어서는 안 됩니다.

프로젝트 맥락을 제공하는 이유는 같은 코드 패턴이라도 실제 제품에서 어떤 역할을 하는지에 따라 판단이 달라질 수 있기 때문입니다.

발견된 504건이 모두 보안 취약점은 아니다

DeepSec의 검사 결과를 이해할 때 가장 중요한 부분입니다.

제공된 실제 사례에서는 flaviocopes.com 저장소의 729개 파일을 검사했고, 504건의 잠재적 발견 사항이 생성됐습니다.

하지만 이 504건을 그대로 수정해야 할 보안 취약점 목록으로 볼 수는 없습니다.

결과는 다음과 같이 분류됐습니다.

• critical 1건
• high 16건
• medium 67건
• high-impact bugs 42건
• bugs 378건

특히 378건은 일반적인 버그에 해당했습니다.

계산 오류나 잘못 생성된 출력, 경계 사례, UI 문제 등이 포함됐으며 모두 보안 긴급 상황을 의미하는 것은 아니었습니다.

따라서 DeepSec에서는 발견 건수를 그대로 대응 작업으로 바꾸기보다 후속 검토를 통해 실제 조사해야 할 영역을 좁혀가는 과정이 필요합니다.

재검증으로 실제 문제인지 확인

DeepSec의 revalidate는 발견 사항을 다시 조사해 다음과 같이 분류합니다.

• true-positive
• false-positive
• fixed
• uncertain
• duplicate

이 과정에서는 코드를 다시 읽고 Git 이력을 살펴볼 수도 있습니다.

특히 중요한 것은 발견 사항의 제목만 보고 수정 작업을 시작하지 않는 것입니다.

예를 들어 보안 문제가 의심되는 경우 다음 연결을 직접 확인해야 합니다.

신뢰하지 않는 입력 → 빠진 통제 → 민감한 연산 → 실제 영향

자료에서는 URL의 청구서 ID에 테넌트 소유권 검사가 빠진 경우를 예로 들고 있습니다. 이 경우 해당 ID를 이용해 데이터베이스에서 다른 테넌트의 청구서를 반환할 수 있는 코드 경로가 실제로 존재하는지 확인해야 합니다.

결국 AI가 발견했다고 해서 그것만으로 문제가 확정되는 것이 아니라, 실제 코드 경로와 방어 장치를 확인하는 과정이 필요합니다.

발견 사항을 우선순위별로 정리하는 triage

많은 발견 사항이 나온 경우에는 triage를 통해 작업 우선순위를 정할 수 있습니다.

이 단계에서는 발견 사항의 텍스트와 악용 가능성, 영향을 바탕으로 P0, P1, P2, skip 등의 작업 우선순위를 부여합니다.

여기서도 중요한 점은 triage가 재검증을 대체하지 않는다는 것입니다.

예를 들어 높은 심각도로 표시된 문제가 실제로 접근할 수 없는 내부 프로토타입에만 존재한다면, 공개 결제 엔드포인트에서 발생하는 다른 문제와 같은 방식으로 처리할 수 없습니다.

따라서 우선순위를 정하는 것과 실제 문제가 맞는지 확인하는 것은 별개의 과정입니다.

근본 원인별로 묶어야 실제 대응이 쉬워진다

flaviocopes.com 사례에서는 504건의 발견 사항 중 462건이 src/tools와 src/pages/tools의 브라우저 도구에서 발생했습니다.

이 중 상당수는 일반적인 제품 버그였습니다.

또한 도구 구현과 Astro 페이지 양쪽에서 같은 문제가 보고되기도 했습니다.

이런 경우 각 발견 사항을 하나씩 수정하는 것보다 공통된 원인을 찾아 하나의 원인을 수정하는 것이 더 효율적일 수 있습니다.

후속 검토에서는 다음과 같은 기준으로 범위를 좁혔습니다.

• 인터넷에서 접근 가능한가
• 공격자가 입력을 통제할 수 있는가
• 다른 파일에 방어 장치가 존재하는가
• 여러 보고서가 같은 근본 원인을 가리키는가
• 실제로 영향을 받는 코드 경로가 존재하는가

그 결과 실제 조사가 필요한 영역을 서버 측 구매·강의 복구·공개 폼 흐름, 실행 가능한 콘텐츠를 렌더링하거나 명령과 코드를 생성하는 브라우저 도구, 로컬 운영 스크립트 등으로 좁힐 수 있었습니다.

DeepSec 초기 설정과 비용 관리

DeepSec을 처음 실행할 때는 검사 범위뿐 아니라 비용과 시간도 고려해야 합니다.

저장소를 변경하지 않고 설정 계획만 확인하려면 다음 명령을 사용할 수 있습니다.

npx deepsec init --plan --output json

작업 공간의 뼈대만 생성하려면 다음과 같이 실행합니다.

npx deepsec init --scaffold-only

--scaffold-only는 패키지 설치나 로그인, 모델 선택, 저장소 검사, 유료 처리를 시작하지 않습니다.

중요한 저장소라면 생성된 .deepsec/ 디렉터리를 먼저 검토하고 필요한 설정 파일을 확인한 뒤 실제 검사를 진행할 수 있습니다.

첫 검사에서 비용과 시간을 제한하는 것도 가능합니다.

npx deepsec init --max-cost-usd 25 --max-duration 30m

설정한 한도에 도달하면 안전한 지점에서 작업이 중단됩니다.

같은 명령을 다시 실행하면 완료된 작업을 건너뛰고 이어서 진행할 수 있습니다.

또한 .deepsec/에서 일부 작업만 먼저 처리해 비용과 속도, 발견 품질을 확인할 수도 있습니다.

pnpm deepsec process --limit 50

처음부터 대규모 저장소 전체를 처리하기보다 작은 범위에서 실제 결과를 확인하는 방식입니다.

모델 인증은 여러 방식을 지원

DeepSec의 기본 인증 경로는 Vercel AI Gateway입니다.

필요하면 Vercel에 로그인하고 DeepSec 작업 공간을 위한 작은 프로젝트를 생성할 수 있습니다.

또한 --model-auth local을 사용하면 이미 로그인된 로컬 Codex 또는 Claude 세션을 사용할 수 있습니다.

이 방식에서는 게이트웨이 토큰이나 API 키를 별도로 설정하지 않습니다.

OpenAI나 Anthropic의 직접 API 키를 사용하는 방식도 제공됩니다.

이때 --ai-api-key-env를 사용하면 DeepSec은 실제 키 값이 아니라 환경 변수 이름을 저장할 수 있습니다.

API 키가 셸 기록에 남지 않도록 주의해야 하며 이후 실행에서도 해당 환경 변수를 제공해야 합니다.

.deepsec/ 작업 공간에는 무엇이 저장될까

DeepSec은 프로젝트와 별도로 .deepsec/ 작업 공간을 생성합니다.

이 공간에는 자체 package.json, 의존성, 설정, 상태가 존재합니다.

주요 파일은 다음과 같습니다.

• deepsec.config.ts
• generated-matchers.ts
• AGENTS.md

그리고 data/<project>/ 아래에는 다음과 같은 구조가 저장됩니다.

• INFO.md
• SETUP.md
• project.json
• setup/
• files/
• runs/
• reports/

생성되는 Git 설정에서는 자격 증명과 재생성 가능한 검사 상태 등을 제외할 수 있습니다.

다만 보안 보고서에는 민감한 코드 경로나 취약점 세부 정보가 포함될 수 있으므로, 해당 파일을 저장소에 커밋할 때는 프로젝트 정책을 확인해야 합니다.

일상적인 검사는 증분 방식으로 진행

전체 초기 검토가 끝난 이후에는 모든 검사를 처음부터 다시 수행할 필요가 없습니다.

일반적인 흐름은 다음과 같습니다.

status → scan → process → revalidate → report

scan은 활성화된 매처를 적용해 후보 파일을 기록하며 AI 모델을 호출하지 않습니다.

process는 대기 중인 후보 파일을 코딩 에이전트에 전달하는 유료 처리 단계입니다.

revalidate는 기존 발견 사항을 다시 확인합니다.

마지막으로 report를 통해 결과를 정리할 수 있습니다.

발견 사항은 분석 이력에도 기록됩니다. 모델과 에이전트, 시간, 확인 가능한 비용 등을 기록하며, 이력은 추가만 가능한 형태로 유지됩니다.

따라서 이후 다른 모델로 다시 분석하더라도 이전 분석 기록을 삭제하지 않습니다.

PR 변경 사항도 별도로 검사할 수 있다

전체 저장소를 검사한 이후에는 현재 브랜치에서 변경된 파일을 대상으로 검토할 수 있습니다.

예를 들어 다음 명령을 사용할 수 있습니다.

process --diff origin/main

스테이징된 변경 사항은 --diff-staged, 커밋하지 않은 파일과 추적되지 않는 파일은 --diff-working으로 검사할 수 있습니다.

특히 PR 검토에서는 매처가 반응하지 않은 변경 파일도 에이전트가 검토하도록 구성할 수 있다는 점이 특징입니다.

PR용 Markdown 요약이 필요하다면 --comment-out comment.md를 사용할 수 있습니다.

다만 처음부터 CI를 차단하는 방식으로 운영하기보다 권고 모드에서 보고서를 보관하면서 비용과 오탐 수준을 확인한 뒤 차단 검사로 전환하는 방식이 권장됩니다.

신뢰하지 않는 PR에서는 별도의 주의가 필요

보안 검토 도구를 CI에 적용할 때는 PR 코드 자체만 생각해서는 안 됩니다.

PR에서는 애플리케이션 코드뿐 아니라 package.json, 설치 스크립트, DeepSec 설정처럼 CI에서 실행될 수 있는 파일도 변경할 수 있습니다.

따라서 신뢰하지 않는 코드를 실행하는 작업에 강력한 저장소 권한을 함께 제공해서는 안 됩니다.

자료에서는 다음과 같은 작업 분리를 제시합니다.

첫 번째 작업은 코드 읽기와 검토 실행, 산출물 작성만 수행하고 저장소 수정 권한을 갖지 않습니다.

두 번째 작업은 안전하게 정제한 산출물을 읽고 PR 댓글만 작성하며 PR 코드를 실행하지 않습니다.

특히 검토 작업에는 모델 자격 증명이 존재할 수 있기 때문에 외부 PR을 처리할 때는 비밀정보에 접근하지 못하도록 구성해야 합니다.

정기적인 CI 검사도 가능

신뢰할 수 있는 기본 브랜치를 대상으로 예약 전체 검사를 실행하는 방식도 사용할 수 있습니다.

제공된 예에서는 수동 실행 또는 매주 월요일 06:00에 예약 실행하고, 읽기 전용 저장소 권한과 60분 제한, Node.js 24를 사용하는 형태를 제시합니다.

전체 검사는 다음과 같은 흐름으로 진행됩니다.

의존성 설치
↓
scan
↓
process
↓
높은 심각도 재검증
↓
Markdown 내보내기

CI 실행 사이에 검사 상태를 유지하려면 .deepsec/data/**를 비공개 저장소에 보존해야 합니다.

상태를 보존하지 않으면 새로운 실행기가 동일한 초기 작업을 반복 처리할 수 있습니다.

또한 보안 보고서를 공개 빌드 로그에 게시해서는 안 되며, 보고서를 별도의 비공개 산출물로 보관하는 과정이 필요합니다.

대규모 저장소에서는 Vercel Sandbox 활용

검사 규모가 커지면 Vercel Sandbox의 microVM을 이용해 작업을 분산할 수 있습니다.

예를 들어 다음과 같은 설정이 제공됩니다.

--sandboxes 10 --concurrency 4

각 샌드박스에 작업 일부를 배정하는 방식입니다.

Sandbox를 사용하면 다음과 같은 상황에서 도움이 될 수 있습니다.

• 로컬 실행에 수시간에서 수일이 걸리는 경우
• 후보가 수천 개에 이르는 경우
• 검사 작업 트리의 격리가 필요한 경우
• 예약된 작업을 일정한 시간 안에 완료해야 하는 경우

반대로 작은 저장소와 중간 규모 저장소에서는 로컬 실행이 더 간단할 수 있습니다.

분산 실행에는 인프라와 인증, 업로드 시간, 추가 비용이 발생하기 때문입니다.

여러 저장소도 하나의 작업 공간에서 관리

하나의 .deepsec/ 작업 공간으로 여러 저장소를 관리하는 것도 가능합니다.

init-project로 프로젝트를 추가하고 setup --project-id를 실행한 뒤 후속 검사에서도 프로젝트 ID를 지정하는 방식입니다.

웹 앱과 API, Worker, 백그라운드 서비스처럼 하나의 제품이 여러 저장소로 구성되어 있다면 활용할 수 있습니다.

반대로 서로 관련이 없는 저장소를 단순히 하나의 대시보드로 묶기보다는 함께 검토해야 하는 제품 단위로 구성하는 것이 적합합니다.

DeepSec이 모든 프로젝트에 적합한 것은 아니다

DeepSec은 애플리케이션과 서비스에 적합한 도구로 설명됩니다.

반면 다음과 같은 경우에는 우선적으로 사용하기에 덜 적합할 수 있습니다.

• 민감한 서버 코드가 없는 정적 사이트
• 외부 입력이 없는 작은 스크립트
• 프로젝트별 위협 맥락이 없는 라이브러리
• 생성 코드 중심의 프로젝트
• 로컬에서 신뢰할 수 없는 저장소
• 발견 사항을 검토하고 수정할 사람이 없는 프로젝트

사소한 수정마다 빠르게 확인하는 용도로도 적합하지 않을 수 있습니다.

PR 직접 모드에서도 검토하는 파일마다 모델 작업이 필요하기 때문입니다.

빠른 피드백에는 린터, 테스트, 의존성 스캐너, 좁고 명확한 정적 규칙을 사용하고, 깊은 저장소 추론이 필요한 영역에 DeepSec을 활용하는 방식이 제시됩니다.

DeepSec을 도입할 때 중요한 순서

DeepSec을 처음 적용한다면 제공된 자료에서는 다음과 같은 흐름을 제시합니다.

--scaffold-only로 생성물 검토 → 실제 위협 경계 보완 → 작고 제한된 검사 → 전체 저장소 확대

이 과정에서 중요한 것은 AI에게 많은 코드를 한 번에 전달하는 것이 아닙니다.

먼저 어떤 코드가 중요한지 파악하고, 어떤 진입점을 검사해야 하는지 확인한 뒤, 작은 범위에서 검사 결과와 비용을 확인해야 합니다.

그다음 전체 저장소로 범위를 확대하는 방식입니다.

특히 발견 건수가 많아졌을 때는 단순히 모든 결과를 수정 목록으로 만드는 것이 아니라, 재검증 → 실제 코드 경로 확인 → 근본 원인별 그룹화 → 실제 영향 확인의 과정을 거치는 것이 핵심입니다.

728x90

Vercel DeepSec은 패턴 기반 스캐너와 AI 코딩 에이전트를 결합해 저장소의 보안 문제를 조사하는 오픈소스 도구입니다.

패턴 스캐너가 먼저 조사 범위를 좁히고, Codex나 Claude 같은 에이전트가 여러 파일을 오가며 데이터 흐름과 인증, 인가, 검증 등의 방어 장치를 확인합니다.

특히 PR에서 변경된 코드뿐만 아니라 기존 코드 전체를 검사할 수 있고, 검사 상태와 분석 이력을 저장해 중단된 작업을 다시 이어갈 수 있다는 점이 특징입니다.

하지만 DeepSec이 저장소의 안전성을 증명하는 것은 아닙니다. AI가 발견한 결과에는 일반 버그와 오탐이 포함될 수 있으며, 실제 보안 문제인지 판단하려면 공격자가 통제할 수 있는 입력이 실제 민감한 연산까지 도달하는지 코드 경로를 확인해야 합니다.

실제 사례에서도 729개 파일을 검사해 504건의 잠재적 발견 사항이 나왔지만, 그 결과를 그대로 수정 작업으로 전환하지 않고 재검증과 근본 원인 분석을 통해 실제 조사 영역을 좁혔습니다.

결국 DeepSec을 활용할 때 중요한 것은 얼마나 많은 문제를 발견했는가보다 무엇을 제대로 검사했고, 발견한 문제가 실제 코드 경로에서 어떤 영향을 만드는지 확인하는 것입니다.

또한 모델 호출 비용과 코드 전송 문제, CI에서의 권한 관리, 신뢰하지 않는 PR에 대한 격리, 검사 상태와 보안 보고서의 보존까지 함께 고려해야 합니다.

자료에서 제시하는 DeepSec의 핵심적인 활용 방식은 AI에게 저장소 전체를 단순히 맡기는 것이 아니라, 검사 범위를 정의하고 후보를 선별한 뒤 AI의 깊은 분석과 사람의 재검증을 결합하는 것이라고 정리할 수 있습니다.

300x250

https://flaviocopes.com/deepsec/

A deep dive into DeepSec