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를 사용하여 설치별 키로 암호화됩니다; 환경설정에 평문이 없습니다.
• 진정한 HKDF 호스트 익명화 (PRIV-01) — STRICT 모드는 이제 호스트 익명화에 진정한 HMAC-SHA256 추출/확장 (솔티드 SHA-256이 아님)을 사용합니다.
• 요청/응답 본문 수정 + 사용자 정의 패턴 (PRIV-02) — 수정 파이프라인은 본문 필드와 ReDoS에 대해 검증된 사용자 구성 가능 정규식 패턴을 포함합니다.
• 전송 전 비밀 트립와이어 (PRIV-03) — 높은 엔트로피 값이 Burp을 떠나기 전에 경고; 허용 목록 작업은 감사 로깅됩니다.
• 외부 MCP 서버 (CAP-02) — 외부/사용자 정의 MCP 서버(SSE 또는 stdio)에 연결하여 AI 에이전트가 Burp의 내장 도구와 함께 자신의 도구를 호출할 수 있습니다.
• 세션별 토큰 예산 가드레일 (CAP-04) — BudgetGuard는 WARN/CAP/OFF 상태로 수동 스캐너 지출을 제한합니다; 수동 스캐너는 하드 캡에서 자동으로 일시 중지됩니다.

주요 특징

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

빠른 시작

1. 설치

Burp의 BApp Store에서 Custom AI Agent를 설치하거나, 릴리스에서 최신 JAR을 다운로드하거나, 소스에서 빌드하세요 (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) — 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(커뮤니티 또는 프로페셔널)를 엽니다.
2. 확장 > 설치됨 > 추가로 이동합니다.
3. 확장 유형으로 Java를 선택하고 .jar 파일을 선택합니다.

확장 프로그램은 Burp에 Custom AI Agent로 등록됩니다(확장 목록 및 Suite 탭의 이름). Burp의 내장 Burp AI 제공자와 구별하기 위함입니다.

3. 에이전트 프로필

확장 프로그램은 첫 실행 시 번들 프로필을 ~/.burp-ai-agent/AGENTS/에 자동 설치합니다. 사용자 정의 프로필을 추가하려면 해당 디렉터리에 추가 *.md 파일을 넣으세요.

4. 백엔드 구성

AI Agent 탭을 열고 설정으로 이동합니다. 백엔드를 선택하세요:

NVIDIA NIM의 경우 백엔드는 NVIDIA 호스팅 엔드포인트와 동일한 채팅 완료 스타일 흐름을 기대합니다. 작동하는 구성은 다음과 같습니다:

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 기록에서 요청을 오른쪽 클릭.
3. 확장 > Custom AI Agent > 이 요청 분석 선택.
4. AI 분석과 함께 채팅 세션이 열립니다.

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

설정 > MCP 서버에서 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+ 필요. 외부 액세스를 활성화하면 MCP 클라이언트는 모든 요청에 Authorization: Bearer <token>을 보내야 합니다.

설정 > MCP > 외부 서버에서 외부 또는 사용자 정의 MCP 서버(SSE 또는 stdio 전송)를 등록할 수도 있습니다. 외부 서버 인증 토큰은 저장 시 암호화되어 보관됩니다. 설정 세부 사항 및 보안 참고 사항은 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개 이상의 페이로드)
• 종단 간 스캔 워크플로 (범위 -> 수동 -> 능동 -> OOB -> 보고서)
• 심각도/신뢰도 매핑이 있는 이슈 생성 프로토콜

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 키스토어 비밀번호 등)은 설치별 마스터 키를 사용하여 AES-256-GCM으로 저장 시 암호화됩니다.
• STRICT 개인정보 모드는 진정한 HKDF(HMAC-SHA256 추출/확장)를 사용하여 호스트를 익명화합니다. BALANCED 모드는 쿠키, 토큰 및 인증 헤더를 수정합니다. OFF 모드는 트래픽을 그대로 보냅니다.
• 외부 MCP 서버 출력은 AI 프롬프트에 들어가기 전에 신뢰 경계 마커로 래핑되어 신뢰할 수 없는 서버 응답으로부터 프롬프트 인젝션을 방지합니다.

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

요구 사항

• Burp Suite 커뮤니티 또는 프로페셔널 (2023.12 이상)
• Java 21 (최신 Burp에 런타임용으로 번들됨; 소스 빌드 시 별도 필요)
• 최소 하나의 AI 백엔드 구성 (위 표 참조)

라이선스

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

면책 조항

사전 동의 없이 대상을 공격하기 위해 Custom AI Agent를 사용하는 것은 불법입니다. 해당 법률을 준수하는 것은 사용자의 책임입니다. 개발자는 이 도구로 인한 오용이나 손해에 대해 책임을 지지 않습니다. 책임감 있게 사용하세요.

기여

이슈 및 풀 리퀘스트를 환영합니다. 개발 설정 및 가이드라인은 CONTRIBUTING.md를, 아키텍처 세부 사항은 개발자 문서를 참조하세요.