burpsuite-project-parser

Name: burpsuite-project-parser
Author: trailofbits

Security Community

Repo stars 5,723
Forks 499
Author updated Jun 15, 2026, 04:05 PM
Author repo skills

Fluxly profile Facts only: domain, agents, trust score, runtime, permissions and network

Domain: Security
Compatible agents: Claude Code
Cursor
Cline
Codex
Windsurf
Gemini CLI

+20
Trust score: 88 / 100 · community maintained
Author / version / license: @trailofbits · no license declared
Token usage: Heavy
Setup complexity: Guided setup
External API key: Not required
Operating systems: macOS · Linux · Windows
Runtime requirements: No special requirements
Permissions: Read-only
Write / modify
Shell exec
Env read
Network behavior: External requests
Install commands: 26 variants

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview burpsuite-project-parser.preview

---
name: burpsuite-project-parser
description: Searches and explores Burp Suite project files (.burp) from the command line. Use when searching…
category: security
runtime: no special runtime
---

# burpsuite-project-parser output preview

## PART A: Task fit
- Use case: Searches and explores Burp Suite project files (.burp) from the command line. Use when searching response headers or bodies with regex patterns, extracting security audit findings, dumping proxy history or site map data, or analyzing HTTP traffic captured in a Burp project..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When to Use / Prerequisites / Quick Reference” and do not present inference as author intent.

## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Searches and explores Burp Suite project files (.burp) from the command line. Use when searching response headers or bodies with regex patterns, extracting security audit findings, dumping proxy history or site map data, or analyzing HTTP traffic captured in a Burp project.”.
- **02** When the source has headings, the agent prioritizes “When to Use / Prerequisites / Quick Reference” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands, read environment variables; may access external network resources; usually needs no extra API key.

## Running Rules
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options.

SKILL.md SKILL.md

---
name: burpsuite-project-parser
description: Searches and explores Burp Suite project files (.burp) from the command line. Use when searching…
category: security
source: trailofbits/skills
---

# burpsuite-project-parser

## When to use
- Searches and explores Burp Suite project files (.burp) from the command line. Use when searching response headers or b…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.

## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.

## Execution rules
- Organize steps around “When to Use / Prerequisites / Quick Reference” and keep inference separate from source facts.
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding the task.

## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies.

Evidence boundary and execution chain

The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.

skill "burpsuite-project-parser" {
  input      -> user goal + target files + boundaries + acceptance criteria
  context    -> When to Use / Prerequisites / Quick Reference
  rules      -> SKILL.md triggers / order / output contract
  runtime    -> no special runtime | read files, write/modify files, run shell commands, read environment variables | may access external network resources
  guardrails -> usually needs no extra API key + small-sample validation + diff/log review
  output     -> copyable result + checklist + next iteration
}

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Searches and explores Burp Suite project files (.burp) from the command line. Use when searching response headers or bodies with…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When to Use”, “Prerequisites”, “Quick Reference”, “Sub-Component Filters (USE THESE)”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name burpsuite-project-parser directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When to Use / Prerequisites / Quick Reference” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec / env-read; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Burp Project Parser

Search and extract data from Burp Suite project files using the burpsuite-project-file-parser extension.

When to Use

Searching response headers or bodies with regex patterns
Extracting security audit findings from Burp projects
Dumping proxy history or site map data
Analyzing HTTP traffic captured in a Burp project file

Prerequisites

This skill delegates parsing to Burp Suite Professional - it does not parse .burp files directly.

Required:

Burp Suite Professional - Must be installed (portswigger.net)
burpsuite-project-file-parser extension - Provides CLI functionality

Install the extension:

Download from github.com/BuffaloWill/burpsuite-project-file-parser
In Burp Suite: Extender → Extensions → Add
Select the downloaded JAR file

Quick Reference

Use the wrapper script:

{baseDir}/scripts/burp-search.sh /path/to/project.burp [FLAGS]

The script uses environment variables for platform compatibility:

BURP_JAVA: Path to Java executable
BURP_JAR: Path to burpsuite_pro.jar

See Platform Configuration for setup instructions.

Sub-Component Filters (USE THESE)

ALWAYS use sub-component filters instead of full dumps. Full proxyHistory or siteMap can return gigabytes of data. Sub-component filters return only what you need.

Available Filters

Filter	Returns	Typical Size
`proxyHistory.request.headers`	Request line + headers only	Small (< 1KB/record)
`proxyHistory.request.body`	Request body only	Variable
`proxyHistory.response.headers`	Status + headers only	Small (< 1KB/record)
`proxyHistory.response.body`	Response body only	LARGE - avoid
`siteMap.request.headers`	Same as above for site map	Small
`siteMap.request.body`		Variable
`siteMap.response.headers`		Small
`siteMap.response.body`		LARGE - avoid

Default Approach

Start with headers, not bodies:

# GOOD - headers only, safe to retrieve
{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | head -c 50000
{baseDir}/scripts/burp-search.sh project.burp proxyHistory.response.headers | head -c 50000

# BAD - full records include bodies, can be gigabytes
{baseDir}/scripts/burp-search.sh project.burp proxyHistory  # NEVER DO THIS

Only fetch bodies for specific URLs after reviewing headers, and ALWAYS truncate:

# 1. First, find interesting URLs from headers
{baseDir}/scripts/burp-search.sh project.burp proxyHistory.response.headers | \
  jq -r 'select(.headers | test("text/html")) | .url' | head -n 20

# 2. Then search bodies with targeted regex - MUST truncate body to 1000 chars
{baseDir}/scripts/burp-search.sh project.burp "responseBody='.*specific-pattern.*'" | \
  head -n 10 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'

HARD RULE: Body content > 1000 chars must NEVER enter context. If the user needs full body content, they must view it in Burp Suite's UI.

Regex Search Operations

Search Response Headers

responseHeader='.*regex.*'

Searches all response headers. Output: {"url":"...", "header":"..."}

Example - find server signatures:

responseHeader='.*(nginx|Apache|Servlet).*' | head -c 50000

Search Response Bodies

responseBody='.*regex.*'

MANDATORY: Always truncate body content to 1000 chars max. Response bodies can be megabytes each.

# REQUIRED format - always truncate .body field
{baseDir}/scripts/burp-search.sh project.burp "responseBody='.*<form.*action.*'" | \
  head -n 10 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'

Never retrieve full body content. If you need to see more of a specific response, ask the user to open it in Burp Suite's UI.

Other Operations

Extract Audit Items

auditItems

Returns all security findings. Output includes: name, severity, confidence, host, port, protocol, url.

Note: Audit items are small (no bodies) - safe to retrieve with head -n 100.

Dump Proxy History (AVOID)

proxyHistory

NEVER use this directly. Use sub-component filters instead:

proxyHistory.request.headers
proxyHistory.response.headers

Dump Site Map (AVOID)

siteMap

NEVER use this directly. Use sub-component filters instead.

Output Limits (REQUIRED)

CRITICAL: Always check result size BEFORE retrieving data. A broad search can return thousands of records, each potentially megabytes. This will overflow the context window.

Step 1: Always Check Size First

Before any search, check BOTH record count AND byte size:

# Check record count AND total bytes - never skip this step
{baseDir}/scripts/burp-search.sh project.burp proxyHistory | wc -cl
{baseDir}/scripts/burp-search.sh project.burp "responseHeader='.*Server.*'" | wc -cl
{baseDir}/scripts/burp-search.sh project.burp auditItems | wc -cl

The wc -cl output shows: <bytes> <lines> (e.g., 524288 42 means 512KB across 42 records).

Interpret the results - BOTH must pass:

Metric	Safe	Narrow search	Too broad	STOP
Lines	< 50	50-200	200+	1000+
Bytes	< 50KB	50-200KB	200KB+	1MB+

A single 10MB response on one line will show high byte count but only 1 line - the byte check catches this.

Step 2: Refine Broad Searches

If count/size is too high:

Use sub-component filters (see table above):

# Instead of: proxyHistory (gigabytes)
# Use: proxyHistory.request.headers (kilobytes)

Narrow regex patterns:

# Too broad (matches everything):
responseHeader='.*'

# Better - target specific headers:
responseHeader='.*X-Frame-Options.*'
responseHeader='.*Content-Security-Policy.*'

Filter with jq before retrieving:

# Get only specific content types
{baseDir}/scripts/burp-search.sh project.burp proxyHistory.response.headers | \
  jq -c 'select(.url | test("/api/"))' | head -n 50

Step 3: Always Truncate Output

Even after narrowing, always pipe through truncation:

# ALWAYS use head -c to limit total bytes (max 50KB)
{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | head -c 50000

# For body searches, truncate each JSON object's body field:
{baseDir}/scripts/burp-search.sh project.burp "responseBody='pattern'" | \
  head -n 20 | jq -c '.body = (.body | if length > 1000 then .[:1000] + "...[TRUNCATED]" else . end)'

# Limit both record count AND byte size:
{baseDir}/scripts/burp-search.sh project.burp auditItems | head -n 50 | head -c 50000

Hard limits to enforce:

head -c 50000 (50KB max) on ALL output
Truncate .body fields to 1000 chars - MANDATORY, no exceptions
```
jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'
```

Never run these without counting first AND truncating:

proxyHistory / siteMap (full dumps - always use sub-component filters)
responseBody='...' searches (bodies can be megabytes each)
Any broad regex like .* or .+

Investigation Workflow

Identify scope - What are you looking for? (specific vuln type, endpoint, header pattern)

Search audit items first - Start with Burp's findings:

{baseDir}/scripts/burp-search.sh project.burp auditItems | jq 'select(.severity == "High")'

Check confidence scores - Filter for actionable findings:

... | jq 'select(.confidence == "Certain" or .confidence == "Firm")'

Extract affected URLs - Get the attack surface:
```
... | jq -r '.url' | sort -u
```

Search raw traffic for context - Examine actual requests/responses:

{baseDir}/scripts/burp-search.sh project.burp "responseBody='pattern'"

Validate manually - Burp findings are indicators, not proof. Verify each one.

Understanding Results

Severity vs Confidence

Burp reports both severity (High/Medium/Low) and confidence (Certain/Firm/Tentative). Use both when triaging:

Combination	Meaning
High + Certain	Likely real vulnerability, prioritize investigation
High + Tentative	Often a false positive, verify before reporting
Medium + Firm	Worth investigating, may need manual validation

A "High severity, Tentative confidence" finding is frequently a false positive. Don't report findings based on severity alone.

When Proxy History is Incomplete

Proxy history only contains what Burp captured. It may be missing traffic due to:

Scope filters excluding domains
Intercept settings dropping requests
Browser traffic not routed through Burp proxy

If you don't find expected traffic, check Burp's scope and proxy settings in the original project.

HTTP Body Encoding

Response bodies may be gzip compressed, chunked, or use non-UTF8 encoding. Regex patterns that work on plaintext may silently fail on encoded responses. If searches return fewer results than expected:

Check if responses are compressed
Try broader patterns or search headers first
Use Burp's UI to inspect raw vs rendered response

Rationalizations to Reject

Common shortcuts that lead to missed vulnerabilities or false reports:

Shortcut	Why It's Wrong
"This regex looks good"	Verify on sample data first—encoding and escaping cause silent failures
"High severity = must fix"	Check confidence score too; Burp has false positives
"All audit items are relevant"	Filter by actual threat model; not every finding matters for every app
"Proxy history is complete"	May be filtered by Burp scope/intercept settings; you see only what Burp captured
"Burp found it, so it's a vuln"	Burp findings require manual verification—they indicate potential issues, not proof

Output Format

All output is JSON, one object per line. Pipe to jq for formatting:

{baseDir}/scripts/burp-search.sh project.burp auditItems | jq .

Filter with grep:

{baseDir}/scripts/burp-search.sh project.burp auditItems | grep -i "sql injection"

Examples

Search for CORS headers (with byte limit):

{baseDir}/scripts/burp-search.sh project.burp "responseHeader='.*Access-Control.*'" | head -c 50000

Get all high-severity findings (audit items are small, but still limit):

{baseDir}/scripts/burp-search.sh project.burp auditItems | jq -c 'select(.severity == "High")' | head -n 100

Extract just request URLs from proxy history:

{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | jq -r '.request.url' | head -n 200

Search response bodies (MUST truncate body to 1000 chars):

{baseDir}/scripts/burp-search.sh project.burp "responseBody='.*password.*'" | \
  head -n 10 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'

Platform Configuration

The wrapper script requires two environment variables to locate Burp Suite's bundled Java and JAR file.

macOS

export BURP_JAVA="/Applications/Burp Suite Professional.app/Contents/Resources/jre.bundle/Contents/Home/bin/java"
export BURP_JAR="/Applications/Burp Suite Professional.app/Contents/Resources/app/burpsuite_pro.jar"

Windows

$env:BURP_JAVA = "C:\Program Files\BurpSuiteProfessional\jre\bin\java.exe"
$env:BURP_JAR = "C:\Program Files\BurpSuiteProfessional\burpsuite_pro.jar"

Linux

export BURP_JAVA="/opt/BurpSuiteProfessional/jre/bin/java"
export BURP_JAR="/opt/BurpSuiteProfessional/burpsuite_pro.jar"

Add these exports to your shell profile (.bashrc, .zshrc, etc.) for persistence.

Manual Invocation

If not using the wrapper script, invoke directly:

"$BURP_JAVA" -jar -Djava.awt.headless=true "$BURP_JAR" \
  --project-file=/path/to/project.burp [FLAGS]

Install command

One-click installPick a runner, click Copy, paste into your terminal, press enter

npx skills add trailofbits/skills/plugins/burpsuite-project-parser/skills/burpsuite-project-parser -y

Open general install guide

View skill source

Works with

Claude Code
Cursor
Cline
Codex
Windsurf
Gemini
OpenCode
Roo Code
AAide
+Augment
GitHub Copilot
OpenClaw
KKiro
Junie
WWarp
Goose
Trae
Kilo Code
OpenHands
Amp
Zencoder
CContinue
AIAider
CodeBuddy
CodeGeeX
Replit Agent

Security audit

88 / 100

Community

未声明 license/许可。
未声明 version。
未限定 allowed-tools，默认拥有全部工具权限。

Metadata

Source: local
trailofbits/skills
中文

More by @trailofbits

Category & tags

Category Security