Burp Suite project parser

Contract

Field	Bound contract
Trigger	A user asks to search or analyze a Burp Suite .burp project, extract audit items, inspect request or response metadata, or search captured traffic.
Authority	Read-only: the .burp project is read through Burp Suite Professional; no project file is modified. No remote mutation.
Side effect	The user-selected local .burp project is read through Burp Suite Professional; output is capped and filtered in parsed mode, or streamed raw in stream mode.
Done	The requested operation returns the correct JSON output for the selected mode: size-checked and truncated in parsed mode, or raw streamed in stream mode.

Inputs

• Project file path (required): absolute path to a .burp project file.
• Operation (required): one of auditItems, proxyHistory, siteMap, responseHeader='regex', responseBody='regex', or a sub-component filter such as proxyHistory.request.headers.
• Mode (required): parsed (default) or stream. stream returns the parser output unchanged to stdout without body truncation.
• BURP_JAVA (required if not at default platform path): path to Burp Suite Professional's bundled Java executable.
• BURP_JAR (required if not at default platform path): path to burpsuite_pro.jar.
• jq (required for parsed mode): used for filtering, truncating body fields, and triaging audit items.

Procedure

1. Verify prerequisites. Confirm Burp Suite Professional is installed, the burpsuite-project-file-parser extension (github.com/BuffaloWill/burpsuite-project-file-parser) is loaded, and BURP_JAVA, BURP_JAR, and jq resolve to existing executables. BURP_JAVA and BURP_JAR default to macOS /Applications/Burp Suite Professional.app/Contents/Resources/... and Linux /opt/BurpSuiteProfessional/.... If any prerequisite is missing, stop and report it. This skill does not parse .burp files directly. Done when: Burp Suite, the extension, Java, JAR, and jq are confirmed present.
2. Confirm the project file exists at the supplied path. If not, stop and report the missing file. Done when: the project file is confirmed.
3. If no operation argument is supplied, print usage and stop. Done when: at least one operation is present or usage is printed.
4. Mode parsed: preflight result size by running the operation through wc -cl:

   "$BURP_JAVA" -Djava.awt.headless=true -jar "$BURP_JAR" \
     --project-file="$PROJECT_FILE" <operation> | wc -cl
   

   The -Djava.awt.headless=true flag must precede -jar. Interpret both metrics: lines under 50 and bytes under 50 KB are safe; lines 50 to 200 or bytes 50 to 200 KB require narrowing; lines over 200 or bytes over 200 KB require further narrowing; lines over 1000 or bytes over 1 MB require stopping and refining. A single large response on one line shows a high byte count but only one line; the byte check catches this. Done when: size is classified as safe, needs narrowing, or stop-and-refine.
5. Mode parsed: if the size check is too broad, narrow the operation. Replace full proxyHistory or siteMap with sub-component filters (proxyHistory.request.headers, proxyHistory.response.headers, siteMap.request.headers, siteMap.response.headers). Tighten regex patterns from .* to specific content. Pipe through jq with a select filter before retrieving full output. Done when: the operation is narrowed to pass the size check.
6. Mode parsed: retrieve the narrowed result with a hard byte cap of 50 KB:

   "$BURP_JAVA" -Djava.awt.headless=true -jar "$BURP_JAR" \
     --project-file="$PROJECT_FILE" <operation> | head -c 50000
   

   Done when: the narrowed result is retrieved with a 50 KB byte cap.
7. Mode parsed: truncate body fields and triage audit items using jq. For any operation returning a .body field, truncate each body to 1000 characters before it enters context:

   ... | head -n 20 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'
   

   For audit items, triage by severity and confidence:

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

   Present Burp findings as indicators requiring manual validation, not proven vulnerabilities. Note that proxy history may be incomplete due to Burp scope filters, intercept settings, or traffic not routed through the proxy. Done when: every body field is truncated, audit items are triaged, and findings are presented as indicators requiring validation.
8. Mode stream: run the parser by executing the resolved Java binary headless against the resolved JAR, passing --project-file=<project-file> followed by every operation argument verbatim:

   <BURP_JAVA> -Djava.awt.headless=true -jar <BURP_JAR> --project-file=<PROJECT_FILE> <operation...>
   

   Stream the JSON output (one object per line) to stdout unchanged. Do not parse, filter, or mutate the output. Done when: the parser is invoked and its output is streamed.

Failure and recovery

• Missing prerequisite (Burp Suite, extension, Java, JAR, or jq not found): stop and report which prerequisite is missing. Do not attempt to parse .burp files directly.
• Project file not found: stop, naming the missing path. No parser invocation occurs.
• Unsupported platform: when uname -s is neither Darwin nor Linux and no BURP_JAVA/BURP_JAR overrides are set, stop and name the platform. The user must set both environment variables.
• Java or JAR not found: stop, naming the missing path and the environment variable to set. No parser invocation occurs.
• No operation supplied: print usage and stop. No parser invocation occurs.
• Result set too large (parsed mode, lines over 1000 or bytes over 1 MB after size check): do not retrieve. Report the size, apply sub-component filters or narrower regex, and re-check size before retrieving.
• Regex silently fails on encoded responses: response bodies may be gzip-compressed, chunked, or non-UTF8. Search headers first, try broader patterns, or direct the user to inspect the raw response in Burp's UI.
• Partial results from size cap (parsed mode): if head -c 50000 truncates output mid-stream, report that results are incomplete and the user should narrow the search or inspect remaining records in Burp's UI.
• Parser runtime error (stream mode or parsed mode): surface the parser's stderr and exit code unchanged. Do not swallow errors or fabricate results.
• Non-mutation: no rollback is needed; this skill only reads the project file through Burp Suite Professional and never modifies it.

Output

• Mode parsed: JSON objects, one per line, piped through jq. Audit items include name, severity, confidence, host, port, protocol, and url; header searches return url and header fields; body searches return url and body fields truncated to 1000 characters; total output capped at 50 KB. Findings are presented as indicators requiring validation, not as proof.
• Mode stream: raw JSON objects, one per line, streamed to stdout without size caps or body truncation.