visa/visa-vulnerability-agentic-harness 딥다이브
— LLM이 코드 취약점을 스스로 찾고·고치고·검증하는 Visa의 오픈소스 보안 하네스

1프로젝트 한 줄 요약

전통적인 코드 보안 스캐너(SAST)를 써 본 사람은 두 가지 고통을 안다. 첫째, 오탐(false positive)이 산더미다. 스캐너가 "여기 취약점!"이라 외친 200건 중 실제로 고쳐야 할 건 20건뿐인데, 사람이 그걸 하나하나 걸러내야 한다. 둘째, 스캐너는 찾기만 하고 고쳐주진 않는다. VVAH는 이 둘을 정면으로 겨냥한다.

VVAH에게 저장소를 던지면, LLM 에이전트들이 위협 모델을 세우고 → 코드를 잘게 나눠 훑고 → 발견을 적대적으로 재검증하고 → 중복·연쇄를 정리해 Markdown + SARIF 리포트를 낸다. 여기서 멈추지 않는다. 원하면 remediate로 실제 수정 패치를 작성하고, validate로 독립 심사 패널이 그 패치를 채점해 "검증됨 / 부분 / 재검토 필요" 판정까지 내린다.

가장 중요한 지표는 정확도가 아니라 MTTA(Mean Time to Adapt) — "AI가 취약점을 찾은 순간부터, 검증된 수정이 프로덕션에 반영되기까지의 경과 시간"이다. VVAH의 모든 설계는 이 시간을 줄이는 데 맞춰져 있다.

2왜 주목받는가 — '발견'이 아니라 '신뢰'

AI로 코드를 스캔하는 도구는 이미 여럿 나왔다. 그런데 VVAH가 7주 만에 별 1,000개를 넘기며 트렌딩에 오른 건, 접근각과 출신이 남다르기 때문이다. 네 가지 결이 겹친다.

① Visa가 직접 낸 사내 보안 하네스 + Project Glasswing 계보

결제 산업의 거인 Visa가, 자기들이 내부에서 쓰던 AI 애플리케이션 보안 하네스를 통째로 오픈소스로 공개했다는 것 자체가 화제였다. 게다가 이 도구는 Anthropic의 Project Glasswing(AI 보조 취약점 연구 이니셔티브)에서 얻은 학습을 바탕으로 만들어졌다고 README가 밝힌다. "대기업의 실전 보안 자동화 노하우를 코드로 열람할 수 있다"는 점이 개발자·보안 연구자를 끌어들였다.

② 병목은 '발견'이 아니라 '트리아지'라는 문제 정의

VVAH의 테제는 명확하다: "AI 기반 취약점 관리의 병목은 발견 속도가 아니라 트리아지 속도다. VVAH는 그 제약을 중심으로 설계됐다." 대부분의 AI 스캐너가 "더 많이 찾기"를 자랑할 때, VVAH는 찾은 것을 사람이 믿고 고칠 수 있는 형태로 압축하는 데 집중한다. 오탐 제거·CVSS 점수·SARIF 표준 출력·수정 DTO가 그 도구들이다.

③ 오탐을 죽이는 3중 방어

LLM 스캐너의 최대 약점은 "그럴듯하지만 틀린" 오탐이다. VVAH는 이걸 세 겹으로 막는다: (1) 스테이지4의 다중 렌즈 + 결정론적 투표(같은 코드 청크를 여러 전문 시각으로 N번 훑어 다수결), (2) 스테이지5의 결정론적 사전 필터(신뢰도·증거 게이트), (3) 스테이지6의 적대적 검증자(발견을 "틀렸다고 증명하라"며 다시 소스로 파고드는 두 번째 의견). 오직 TRUE_POSITIVE만 살아남는다.

④ 발견에서 끝나지 않고 '루프를 닫는다'

퍼저·SAST·DAST는 대개 탐지에서 멈춘다. VVAH는 스테이지10에서 실제 수정 패치를 만들고(remediate), 스테이지11에서 적대적 검증 패널이 그 패치를 가중 게이트로 채점한다(validate). "AI가 고치고, 다른 AI가 그 수정을 깐다"는 propose-and-critique 루프가 실제 프로덕션 코드로 구현돼 있다.

3기술 스택 전체 지도

VVAH의 코드는 100% Python이다(약 200개 .py, 2.8만 줄). 본체는 취약점을 직접 계산하는 엔진이 아니라, LLM에게 일을 시키고 결과를 타입 있는 계약(pydantic)으로 주고받으며 단계를 오케스트레이션하는 지휘자다. 그래서 무거운 연산은 전부 LLM API 쪽에 있고, 로컬은 상태·랭킹·리다이렉션만 담당한다.

pyproject.toml — 실제 런타임 의존성 (Python ≥ 3.10)

# package: vvaharness · entry point: vvaharness.cli:main · Apache-2.0
pydantic          >=2.13.4   # Finding·ThreatModel 등 데이터 계약
pydantic-settings >=2.14.1   # 설정/세팅
PyYAML            >=6.0.3    # 프로파일(YAML) 파싱
anthropic         >=0.107.0  # Anthropic Python SDK 백엔드
openai            >=2.41.0   # OpenAI 호환 백엔드
httpx             >=0.28.1   # HTTP 전송(TLS/mTLS)
python-dotenv     >=1.2.2    # .env 자동 로드
claude-agent-sdk  >=0.2.87   # ★ 수정(S10)·검증 패널(S11) 구동

기본 프로파일이 쓰는 모델 (default.yaml)

기본 프로파일은 역할마다 모델을 나눠 박는다. 스캔 8개 역할은 claude-sonnet-4-6(빠르고 저렴한 대량 훑기)에, 스캔 후 수정·검증 역할은 claude-opus-4-8(정밀함이 필요한 판단)에 배정한다. sdk.yaml은 전 역할을 Anthropic SDK로 돌리며 스테이지4 다수결 투표를 켠다(온도 0.4, 3회 실행, 임계 2표). SBOM(2026-06-26)상 전체 의존성 폐쇄집합은 639개 컴포넌트이며 전부 허용 라이선스(MIT/Apache/BSD/PSF), GPL 계열은 없다.

4아키텍처 심화 분석 — 4단계 11스테이지

VVAH의 전체 흐름은 4개 단계(phase), 11개 스테이지로 나뉜다. 모든 모델 호출은 backends/llm.py를 거쳐 역할별 via: 키로 디스패치되고, 각 스테이지는 저장소 바깥의 SQLite 상태 DB(~/.vvaharness/state/)에 체크포인트를 남겨 --resume으로 이미 끝난 스테이지를 건너뛴다. 탐지 데이터의 흐름은 이렇다:

축 ① 각 스테이지 = 갈아끼우는 '스킬' (조립식 파이프라인)

VVAH의 각 LLM 스테이지는 독립적으로 튜닝·버전 관리되는 조립식 스킬이다 — 공격면 매퍼, 위협 모델러, 리서치 전략가, 전문 렌즈 연구자들, 적대적 검토자, 중복 제거기, 익스플로잇 전략가, 수정 에이전트, 검증 패널. 스테이지 사이는 pydantic으로 타입 있는 계약을 주고받으므로, 한 스테이지의 프롬프트나 모델을 바꿔도 배선을 다시 하지 않는다. "에이전트를 조립 가능한 스킬로 분해"하는 패턴의 교과서다.

축 ② 위협 모델링을 '먼저' 한다 (S2)

패턴 매칭 SAST가 코드를 무차별로 훑는 것과 달리, VVAH는 스테이지2에서 먼저 STRIDE·OWASP·트러스트 경계 기반 위협 모델을 세운다. "이 앱에서 진짜 중요한 자산이 뭐고, 신뢰 경계가 어디인가"를 정해 공격면을 좁힌 뒤 정밀 분석에 들어간다. 헛수고를 줄이는 것이다.

축 ③ 오탐을 죽이는 적대적 검증자 (S6)

스테이지6은 발견을 "틀렸다고 증명하라"는 명령을 받은 두 번째 의견이다. 새 에이전트 세션에서 소스를 다시 읽고, 호출자를 외부 진입점까지 거슬러 추적하고, 상류 방어(입력 검증·인코딩·인증 게이트)를 찾아 발견을 죽이려 시도한다. 외부 진입점에 닿지 못하거나 방어가 있으면 FALSE_POSITIVE다.

# s6_verify.py — "일단 틀렸다고 가정하라"는 시스템 프롬프트(요약)
SYSTEM = """당신은 SAST 파이프라인의 second-opinion 검토자다. 아래 발견은
스캐너가 낸 것이니, 소스에서 직접 확인하기 전까지 틀렸다고 가정하라.
  A. 인용된 파일·라인을 열어 코드가 실제로 뭘 하는지 확정한다.
  B. 콜체인을 바깥으로 추적: 호출자를 Grep으로 찾아 외부 진입점에
     닿을 때까지. 외부 진입점 없음 → 익스플로잇 불가.
  C. 발견을 죽여라: 입력검증/allow-list, 프레임워크 인코딩/파라미터화,
     인증·인가 게이트, 테스트 전용/미호출 코드를 찾는다.
DECISION: (B)가 외부 진입점에 닿고 AND (C)/(D)에 방어가 없고
          AND 영향이 가설이 아닌 실제일 때만 TRUE_POSITIVE."""

축 ④ 고친 뒤 '독립 패널'이 채점한다 (S11)

수정(S10)이 실제 파일을 고치면, 검증(S11)은 읽기 전용 적대적 패널이 그 수정을 심사한다. 항상 도는 2개 페르소나(security-architect·penetration-tester)에, 수정이 2개 이상 저장소에 걸칠 때만 cross-repo-analyzer가 추가된다. 각 수정은 4개 가중 게이트로 채점된다.

# validation/constants/scoring.py — 수정 품질 채점 가중치
GATE_WEIGHTS = {
    "root_cause":              0.43,    # 근본 원인을 고쳤나
    "instance_coverage":       0.2467,  # 같은 결함의 모든 인스턴스를
    "no_new_vulnerabilities":  0.1867,  # 새 취약점을 안 만들었나
    "security_best_practices": 0.1366,  # 보안 모범사례를 지켰나
}
THRESHOLD_FIXED   = 0.80   # 이상이면 FIXED
THRESHOLD_PARTIAL = 0.50   # 이상이면 PARTIAL
COVERAGE_FLOOR    = 0.50   # 활성 게이트 가중 미만 → UNVERIFIABLE(채점 불가)

중요한 건 fail-closed 설계다. 누락되거나 건너뛴 게이트가 점수를 부풀리지 못한다. 패널은 철저히 읽기 전용이라 패치도, 도커도 건드리지 않는다.

5디렉토리 구조 해부

콘솔 진입점은 vvaharness.cli:main 하나다. 명령은 setup · doctor · estimate · scan · remediate · validate · gc로 나뉜다. 실제 로직은 vvaharness/(1.9MB) 아래에 스테이지·백엔드·수정·검증으로 층을 나눠 담겼다.

6학습 포인트

① 프로덕션급 에이전트 파이프라인 설계 — 스테이지 + 타입 계약

"AI로 보안 스캔"이라는 하나의 거대한 작업을 11개의 독립적이고, 체크포인트되고, 개별 튜닝 가능한 스테이지로 쪼갠 방식이 핵심 교재다. 각 스테이지는 pydantic으로 타입 있는 핸드오프를 주고받는다: ContextPackage → ThreatModel → TaskManifest → Finding[] → FinalReport. 이 Finding 객체가 파이프라인의 척추이고, 각 스테이지가 여기에 필드를 채워 넣으며 발전시킨다.

# models.py — Finding: 스테이지마다 이 객체를 enrich한다
class Finding(BaseModel):
    file: str
    line_start: int
    vuln_class: VulnClass
    cwe: str | None = None            # "CWE-79" → MD·SARIF로 전달
    exploit_scenario: str = ""        # 입력→영향, 5문장 이내
    source_ref: str | None = None     # 오염 입력이 들어오는 file:line
    sink_ref: str | None = None       # 안전하지 않게 쓰이는 file:line
    confidence: float = Field(ge=0.0, le=1.0)
    votes: int = 1                    # s4 다수결 교집합 표수
    # ── s6 적대적 검증이 채우는 필드 ──
    verdict: Literal["TRUE_POSITIVE", "FALSE_POSITIVE"] | None = None
    cvss_vector: str | None = None    # CVSS:3.1/AV:.../...
    cvss_score: float | None = None

② LLM 오탐을 통제하는 3중 방어

비결정적인 LLM 출력을 신뢰 가능하게 만드는 세 가지 상보적 기법이 한 레포에 다 있다: (1) 결정론적 사전 필터 게이트(S5), (2) "틀렸다고 증명하라"는 적대적 검증자(S6), (3) 다중 에이전트 다수결 투표(S4, 온도 지원 모델 필요). "AI가 그럴듯하게 틀리는" 문제를 어떻게 공학적으로 붙잡는지 배우는 최고의 사례다.

③ 다중 제공사 LLM 오케스트레이션 / 추상화

backends/llm.py의 깔끔한 via: 디스패치 계층은 Claude CLI ⇄ Anthropic SDK ⇄ OpenAI를 역할마다 코드 변경 없이 갈아끼운다. 여기에 샌드박스된 로컬 툴루프(localtools.py, Read/Glob/Grep만·Bash 없음)를 직접 구현했다. "LLM 제공사에 종속되지 않는 추상화 계층을 어떻게 짜는가"의 실전 답안이다.

④ 에이전트 보안 공학 — 이 레포의 백미

가장 값진 교훈이다. deny-by-default 툴 샌드박스(Bash 없음 → 호스트 셸 RCE 없음), cwd 제한과 심볼릭 링크/UNC 거부, 페르소나 프롬프트에 박은 프롬프트 인젝션 저항, 출력 경계에서의 마스킹(redaction), fail-closed 채점, 킬 스위치(VVAHARNESS_REMEDIATE_DISABLE). 심지어 CHANGELOG에는 CWE-502(pickle 역직렬화) 위험을 SQLite/JSON으로 이관한 기록도 있다 — 자기 코드에도 보안 원칙을 적용한 것이다.

⑤ remediate→validate 루프 (propose-and-critique)

Claude Agent SDK로 한 에이전트가 패치를 쓰고, 독립된 적대적 패널이 그 패치를 가중 게이트로 채점하는 구조는, 어떤 "AI가 제안하고 AI가 비판하는" 워크플로에도 재사용할 수 있는 패턴이다. 채점이 fail-closed라 게이트를 건너뛰어 점수를 부풀릴 수 없다는 점까지 뜯어볼 가치가 있다.

⑥ AppSec 기본기가 코드로 구현돼 있다

STRIDE 위협 모델링, 오염 흐름 분석(진입점→싱크 콜그래프 추적), CVSS 3.1 벡터 채점, CWE 매핑, SARIF 2.1.0 출력, CMDB/CVE 컨텍스트 주입 — 보안 이론서에 나오는 개념들이 전부 읽을 수 있고 테스트 가능한 코드(약 85개 테스트)로 구현돼 있다. 보안을 책이 아니라 코드로 배우고 싶은 사람에게 이상적이다.

7하드웨어 / 시스템 요구사항

VVAH는 오케스트레이터라 특별한 하드웨어가 필요 없다. 무거운 연산은 전부 LLM API 쪽에 있기 때문이다. 대신 진짜 비용은 토큰이다. 스테이지·발견마다 USD 상한이 걸려 있고(예: S1 $25, S6 발견당 $10, S11 $15), 실행 전 vvaharness estimate로 비용을 가늠하도록 권한다.

# 설치 → 점검 → 비용 추정 → 리포트까지만 스캔(수정 없이)
pipx install .              # 단일 명령 vvaharness 설치
vvaharness setup            # 프로파일·백엔드·자격증명 설정
vvaharness doctor           # 자격증명·백엔드 헬스체크
vvaharness estimate         # 토큰/비용 사전 추정
vvaharness scan --repo ./myapp --stop-after s9   # s9까지 = 리포트만, 파일 수정 안 함

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

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

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/visa/visa-vulnerability-agentic-harness (Apache-2.0 · Python 100% · 분석 시점 v1.1.0 · ⭐ 약 1,036)
• TrendShift: trendshift.io/repositories/49779 (2026-07-25 Daily #15)
• 핵심 소스: vvaharness/models.py(Finding 계약) · pipeline/stages/s6_verify.py(적대적 검증) · backends/llm.py(via 디스패치) · backends/localtools.py(샌드박스 툴루프) · validation/constants/scoring.py(채점 게이트)
• 설계 문서: docs/architecture.md · docs/SETUP_GUIDE.md · docs/models.md · docs/validation.md · docs/outputs.md · SECURITY.md
• 배경 기술: anthropic.com/glasswing(Project Glasswing) · SARIF · CVSS(FIRST)