Burpsuite Project ParserCAUTION

Trail of Bits skills for security research, vulnerability detection, and audit workflows

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: burpsuite-project-parser
description: 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.
allowed-tools: Bash Read
---

# 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:**
1. **Burp Suite Professional** - Must be installed ([portswigger.net](https://portswigger.net/burp/pro))
2. **burpsuite-project-file-parser extension** - Provides CLI functionality

**Install the extension:**
1. Download from [github.com/BuffaloWill/burpsuite-project-file-parser](https://github.com/BuffaloWill/burpsuite-project-file-parser)
2. In Burp Suite: Extender → Extensions → Add
3. Select the downloaded JAR file

## Quick Reference

Use the wrapper script:
```bash
{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

**Check the exit code. Empty output is not a clean result.** Burp ignores flags it does not recognise, so
without the parser extension it starts normally and drops the query — which looks exactly like a search that
matched nothing.

| Exit | Meaning | What to do |
|------|---------|------------|
| 0 | Output produced | Proceed |
| 1 | Bad usage, or a missing file, Java or JAR | Read the message; fix the path |
| 3 | No output at all | **Do not report this as "nothing found".** An empty result set and an unloaded extension are indistinguishable from here. Run the control query below to tell them apart |
| 4 | Output was not JSON | The extension is not loaded and Burp ignored the flags. Install it before trusting any result |

Anything other than 0 means the search result is unverified, and saying "no matching traffic" on the strength
of it is a false negative reported as a clean finding.

### Resolving Exit 3: the control query

Exit 3 is the common case — most narrowly-scoped regexes legitimately match nothing — so it needs a resolution
you can carry out yourself. You have `Bash` and `Read`; Burp runs headless here, so there is no Extensions tab
to open and no GUI to inspect. Re-running the same query just returns 3 again.

Run a **control query** instead: a selector broad enough that it must return rows if the parser is working at
all, against the same project file. Use the sub-component filter, not the bare selector — a control is still a
query, and the rules above apply to it unchanged.

```bash
{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | head -c 2000
```

`proxyHistory.request.headers` is the right control precisely because it is broad but bounded: it covers every
record in the project, at under 1KB each. Bare `proxyHistory` would answer the same question and is banned
above for a reason — one record with bodies can be megabytes, and `head -n 1` does not stop that, it delivers
exactly one of them in full.

| Control result | What it means | What to do |
|---|---|---|
| Rows on stdout | The parser works | Your narrower query genuinely matched nothing. Report that as a result |
| Exit 3 again | Nothing comes back at all | Either the extension is not loaded, or this project holds no proxy history. Check you named the right project file and that it is non-empty, then ask the user to confirm `burpsuite-project-file-parser` under Burp Suite → Extensions |
| Exit 4 | Burp started and dropped the flags | The extension is not loaded. Say so; do not report on traffic |

**Run the control before concluding anything about the project's traffic.** Assuming the extension is loaded is
exactly how an unverified empty result becomes a clean bill of health — and asking the user to check the GUI is
a legitimate answer where the control is inconclusive. Guessing is not.

**Through a pipe the exit code is not yours to read.** A pipeline reports the status of its *last* command, and
nearly every example here ends in `| jq`, `| head` or `| wc -cl` — so `$?` is `head`'s 0, not the script's 3.
Two reliable signals:

- **stderr**, which reaches you regardless of piping. `Error: the parser produced no output.` or
  `Error: Burp produced output, but not one JSON object` is the answer; no such block means the run was fine.
- **`set -o pipefail`** when you want the code itself, or read `${PIPESTATUS[0]}`:

```bash
set -o pipefail
{baseDir}/scripts/burp-search.sh project.burp auditItems | jq -c 'select(.severity == "High")'
echo "exit: $?"
```

Non-JSON output never reaches stdout, so a downstream `grep` or `jq` cannot match a Burp startup banner and
mistake it for data.

See [Platform Configuration](#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.respons

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

plugins/modern-python/hooks/shims/pip3

plugins/modern-python/hooks/shims/python3

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Burpsuite Project Parser](https://modelsatlas.com/skills/trailofbits/burpsuite-project-parser/badge.svg)](https://modelsatlas.com/skills/trailofbits/burpsuite-project-parser/)

Not your listing, or something out of date? Claim or update your listing.