Custom AI Agent

Burp Suite와 현대 AI를 잇는 다리.

이름에 대한 참고: 이 확장 기능은 Custom AI Agent(이전 명칭: Burp AI Agent)로 게시됩니다. PortSwigger의 BApp Store 명명 요구 사항을 준수하고 Burp Suite의 내장 Burp AI 제공자와의 혼동을 피하기 위해 이름이 변경되었습니다. GitHub 저장소(github.com/six2dez/burp-ai-agent), 문서 사이트(burp-ai-agent.six2dez.com), 구성 디렉터리(~/.burp-ai-agent/)는 연속성을 위해 burp-ai-agent 식별자를 유지합니다.

Custom AI Agent는 보안 워크플로에 AI를 통합하는 Burp Suite용 확장 기능입니다. 로컬 모델이나 클라우드 제공자를 사용하고, MCP를 통해 외부 AI 에이전트를 연결하며, 수동 테스트에 집중하는 동안 패시브/액티브 스캐너가 취약점을 찾도록 하세요.

v0.9.0의 새로운 기능

• 네이티브 Anthropic 백엔드 (CAP-01) — Burp의 HTTP 전송을 통한 직접 Anthropic Messages API 호출. 모든 트래픽이 Proxy 기록에 표시됩니다.
• AES-256-GCM 저장 데이터 암호화 (SEC-01) — 저장된 모든 API 키와 토큰은 javax.crypto를 사용해 설치별 키로 암호화됩니다. 마스터 키는 암호문과 함께 Burp Preferences에 있으므로, 이는 환경 설정 파일을 우연히 들여다보는 것에 대한 방어이지 로컬 공격자에 대한 방어는 아닙니다. — 개인정보 및 보안 참고를 참조하세요.
• 실제 HKDF 호스트 익명화 (PRIV-01) — STRICT 모드는 이제 호스트 익명화에 실제 HMAC-SHA256 extract/expand(솔트 처리된 SHA-256이 아님)를 사용합니다.
• 요청/응답 본문 마스킹 + 사용자 정의 패턴 (PRIV-02) — 마스킹 파이프라인이 본문 필드와 ReDoS에 대해 검증된 사용자 구성 가능한 정규식 패턴을 포함합니다.
• 전송 전 비밀 트립와이어 (PRIV-03) — 고엔트로피 값이 Burp를 떠나기 전에 경고합니다. 허용 목록 작업은 감사 로그에 기록됩니다.
• 외부 MCP 서버 (CAP-02) — 외부/사용자 정의 MCP 서버(SSE 또는 stdio)에 연결하여 AI 에이전트가 Burp의 내장 도구와 함께 해당 도구를 호출할 수 있습니다.
• 세션별 토큰 예산 가드레일 (CAP-04) — BudgetGuard는 WARN/CAP/OFF 상태로 패시브 스캐너 지출을 제한합니다. 패시브 스캐너는 하드 상한에서 자동으로 일시 중지됩니다.

주요 기능

• 12개 AI 백엔드 — Burp AI(내장), Anthropic, Ollama, LM Studio, NVIDIA NIM, Perplexity, 일반 OpenAI 호환, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59개 MCP 도구 — Claude Desktop(또는 모든 MCP 클라이언트)이 Burp를 자율적으로 구동하게 합니다(스토어 빌드에는 확장 네이티브 AI 도구 8개, 전체 빌드에는 59개 전체).
• 범위 제한 MCP 액세스 — 선택적으로 모든 MCP 도구를 범위 내 호스트로 제한하여 외부 AI 클라이언트가 Burp를 통해 범위 외 대상을 접근할 수 없게 합니다.
• 62개 취약점 클래스 — 인젝션, 인증, 암호화 등을 아우르는 패시브 및 액티브 AI 스캐너. 패시브 스캐너는 Burp PassiveScanCheck(Burp Pro)로 실행됩니다.
• Releases에서 설치 — Releases에서 JAR을 다운로드하세요. BApp Store에는 없습니다: 제출이 2026년 1월부터 열려 있습니다.
• 테마 인식 UI — 내부 디자인 시스템이 설정 패널을 스타일링하고 Burp의 라이트/다크 전환에 맞춰 자동으로 테마를 다시 적용합니다.
• Burp Scan Skill — MCP를 통해 선호하는 AI 코딩 어시스턴트(Claude Code, Gemini CLI, Codex 등)를 스캐너로 사용하세요.
• 3가지 개인정보 보호 모드 — STRICT / BALANCED / OFF. 민감한 데이터가 Burp를 떠나기 전에 마스킹합니다.
• 사용자 정의 프롬프트 라이브러리 — 컨텍스트별(HTTP 요청 또는 스캐너 이슈)로 자유 형식 프롬프트를 저장하세요. 오른쪽 클릭 메뉴에서 실행하거나 Custom…을 통해 임시 프롬프트를 입력할 수 있습니다.
• 감사 로깅 — 규정 준수를 위한 SHA-256 무결성 해싱이 포함된 JSONL. 모든 실행은 재현 가능성을 위해 promptSource / contextKind로 스탬프 처리됩니다.

빠른 시작

1. 설치

최신 JAR을 Releases에서 다운로드하거나 소스에서 빌드하세요(Java 21):

git clone https://github.com/six2dez/burp-ai-agent.git
cd burp-ai-agent

# Full build (default, GitHub releases) — all 59 MCP tools
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# Output: build/libs/Custom-AI-Agent-full-<version>.jar

# Store build (BApp Store submission) — 8 extension-native AI MCP tools only
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar -PstoreBuild=true
# Output: build/libs/Custom-AI-Agent-<version>.jar

2. Burp에 로드

1. Burp Suite(Community 또는 Professional)를 엽니다.
2. Extensions > Installed > Add로 이동합니다.
3. 확장 유형으로 Java를 선택하고 .jar 파일을 선택합니다.

이 확장 기능은 Burp의 내장 Burp AI 제공자와 구별하기 위해 Burp에서 Custom AI Agent(Extensions 목록과 Suite 탭의 이름)로 등록됩니다.

3. 에이전트 프로필

이 확장 기능은 첫 실행 시 번들 프로필을 ~/.burp-ai-agent/AGENTS/에 자동 설치합니다. 해당 디렉터리에 추가 *.md 파일을 넣으면 사용자 정의 프로필을 추가할 수 있습니다.

4. 백엔드 구성

AI Agent 탭을 열고 Settings로 이동하세요. 백엔드를 선택하세요:

NVIDIA NIM의 경우 백엔드는 NVIDIA 호스팅 엔드포인트와 동일한 chat-completions 스타일 흐름을 기대합니다. 다음은 작동하는 구성입니다:

Backend: NVIDIA NIM
Base URL: https://integrate.api.nvidia.com
Model: moonshotai/kimi-k2.5
API Key: <your nvapi token>

게이트웨이가 요구하지 않는 한 추가 헤더는 비워 두세요. 확장 기능은 /v1/chat/completions로 요청을 보내고 구성된 bearer 토큰을 자동으로 사용합니다.

5. 첫 번째 분석 실행

1. Burp Proxy를 통해 대상을 탐색합니다.
2. Proxy > HTTP History에서 아무 요청이나 오른쪽 클릭합니다.
3. Extensions > Custom AI Agent > Analyze this request를 선택합니다.
4. AI 분석과 함께 채팅 세션이 열립니다.

6. MCP를 통해 Claude Desktop 연결(선택 사항)

Settings > MCP Server에서 MCP 서버를 활성화하고 Claude Desktop 구성에 다음을 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "burp-ai-agent": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://127.0.0.1:9876/sse"
      ]
    }
  }
}

Node.js 18+ 필요. External Access를 활성화하면 MCP 클라이언트는 모든 요청에 Authorization: Bearer <token>을 보내야 합니다.

Settings > MCP > External Servers(SSE 또는 stdio 전송)에서 외부 또는 사용자 정의 MCP 서버를 등록할 수도 있습니다. 외부 서버 인증 토큰은 개인정보 및 보안 참고에 설명된 주의 사항과 함께 저장 시 암호화됩니다. 설정 세부 사항과 보안 참고는 docs/external-mcp-servers.md를 참조하세요.

Burp Scan Skill(터미널 AI 스캐닝)

burp-scan 스킬을 사용하면 터미널에서 모든 AI 코딩 어시스턴트(Claude Code, Gemini CLI, Codex 등)를 Burp 스캐너로 사용할 수 있습니다. 플러그인의 내장 AI 대신 터미널의 AI가 추론 엔진이 되고 Burp는 MCP를 통해 도구를 제공합니다.

포함 내용

• 스캔 작업별로 구성된 MCP 도구 참조(전체 빌드의 최대 59개 도구)
• 패시브 분석 프로토콜(요청을 보내지 않는 트래픽 분석)
• 액티브 테스트 페이로드 라이브러리(탐지 패턴이 포함된 62개 취약점 클래스용 200개 이상의 페이로드)
• 종단 간 스캔 워크플로(scope -> passive -> active -> OOB -> report)
• 심각도/신뢰도 매핑이 포함된 이슈 생성 프로토콜

Claude Code에 설치

스킬을 Claude Code 스킬 디렉터리에 복사하세요:

# Global (available in all projects)
cp -r skills/burp-scan ~/.claude/skills/burp-scan

# Or project-specific
cp -r skills/burp-scan .claude/skills/burp-scan

그런 다음 Claude Code에서 /burp-scan을 사용하거나 Burp 스캔을 언급할 때 자동으로 트리거되게 하세요.

다른 AI 어시스턴트에 설치

이 스킬은 skills/burp-scan/SKILL.md에 있는 독립형 Markdown 파일입니다. 시스템 프롬프트나 컨텍스트 파일을 지원하는 모든 AI 어시스턴트에서 사용할 수 있습니다:

• Gemini CLI / Codex / OpenCode: 컨텍스트 파일로 추가하거나 시스템 프롬프트에 붙여넣기
• 사용자 정의 MCP 클라이언트: MCP 연결과 함께 스킬 콘텐츠를 시스템 컨텍스트로 포함
• 모든 LLM: 파일이 자체 포함형입니다 — MCP 도구 정의와 함께 컨텍스트로 제공하세요

사용 예시

You: Connect to Burp MCP at localhost:9876 and scan the proxy history for IDOR vulnerabilities

AI: [Uses proxy_http_history to pull traffic]
    [Identifies endpoints with numeric IDs]
    [Sends http1_request with ID+1, ID-1 payloads]
    [Compares responses for different user data]
    [Creates issue_create for confirmed IDOR]

이 스킬과 플러그인의 내장 스캐너는 상호 보완적입니다: 플러그인은 자동화된 백그라운드 스캐닝을 실행하고, 스킬은 터미널에서 대화형의 분석가 주도 스캐닝을 가능하게 합니다.

문서

전체 문서는 **burp-ai-agent.six2dez.com**에서 확인할 수 있습니다.

• 설치
• 빠른 시작
• UI 둘러보기
• 에이전트 프로필
• 패시브 스캐너
• 액티브 스캐너
• MCP 개요
• 개인정보 보호 모드
• 설정 참조
• 문제 해결
• Burp Scan Skill

운영자 플레이북

• MCP 강화
• UI 안전 가이드
• 백엔드 문제 해결
• Anthropic 백엔드 설정
• 외부 MCP 서버

개인정보 및 보안 참고

• 저장된 비밀 — 암호화가 하는 일과 하지 못하는 일. 저장된 모든 API 키와 토큰(Anthropic, MCP bearer 토큰, TLS 키스토어 비밀번호 등)은 설치별 무작위 마스터 키(SecretCipher)를 사용하는 AES-256-GCM으로 암호화됩니다. 그 마스터 키 자체는 보호하는 암호문 옆에 Base64로 인코딩된 채 Burp Preferences에 저장됩니다(기본 설정 secret.master.key.v1). 따라서 Burp Preferences를 읽을 수 있는 사람은 키도 읽고 비밀을 복호화할 수 있습니다. 이는 로컬 공격자나 사용자 권한으로 실행되는 악성 프로세스로부터는 보호하지 못합니다. 환경 설정 파일이나 내보낸 프로젝트를 우연히 들여다보는 것에 대한 난독화로 취급하세요. 자격 증명이 그러한 위협 모델에서 살아남아야 한다면 전용 비밀 저장소에 보관하고 세션마다 붙여넣으세요.
• 모델이 생성한 도구 호출은 승인이 필요합니다. 확장 기능이 모델 출력에서 파싱한 도구 호출은 사용자가 결정할 때까지 Burp에 대해 실행되지 않습니다. 모든 도구는 필수 보안 등급을 갖습니다: 자동 실행(읽기 전용 및 출력 제한), Approve for session 옵션으로 확인, 또는 호출할 때마다 확인. 카탈로그가 인식하지 못하는 도구 이름은 자동이 아닌 항상 확인으로 처리되며, 외부 ext: 네임스페이스 도구는 항상 모든 호출을 확인합니다. 결정은 모달 대화상자 대신 채팅 기록에 인라인 카드로 표시되며, 각 결정은 감사 이벤트와 Burp의 Output 탭의 한 줄로 기록됩니다(감사 로깅은 기본적으로 꺼져 있으므로). 거부하면 모델에 오류 대신 중립적인 "권한 없음, 재시도하지 마세요" 결과가 반환됩니다. 이 등급은 Unsafe Mode 스위치와 독립적입니다: Unsafe Mode는 도구가 결코 실행될 수 있는지 여부를, 등급은 모델이 묻지 않고 실행할 수 있는지 여부를 결정합니다. 설계 근거: DECISIONS.md ADR-15. 운영자 실행 가이드: docs/ui-safety-guide.md.
• STRICT 개인정보 보호 모드는 실제 HKDF(HMAC-SHA256 extract/expand)를 사용하여 호스트를 익명화합니다. BALANCED 모드는 쿠키, 토큰, 인증 헤더를 마스킹합니다. OFF 모드는 트래픽을 그대로 전송합니다.
• 외부 MCP 서버 출력은 AI 프롬프트에 들어가기 전에 신뢰 경계 마커로 감싸져 신뢰할 수 없는 서버 응답으로부터의 프롬프트 인젝션을 방지합니다.

설정은 내부적으로 스키마 버전이 관리되며(settings.schema.version) 안전한 업그레이드를 위해 로드 시 추가 방식으로 마이그레이션됩니다.

요구 사항

• Burp Suite Community 또는 Professional(2023.12+)
• Java 21 (최신 Burp에 런타임용으로 번들되어 있음. 소스에서 빌드하려면 별도로 필요)
• 하나 이상의 AI 백엔드 구성(위 표 참조)

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.

면책 조항

사전 동의 없이 대상을 공격하는 데 Custom AI Agent를 사용하는 것은 불법입니다. 모든 관련 법률을 준수할 책임은 사용자에게 있습니다. 개발자는 이 도구로 인한 오용 또는 피해에 대해 책임을 지지 않습니다. 책임감 있게 사용하세요.

기여

Issue와 pull request는 언제나 환영합니다. 개발 설정 및 지침은 CONTRIBUTING.md를, 아키텍처 세부 사항은 개발자 문서를 참조하세요.