burpsuite-project-parser

Burp Suite project parser

Contract

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.