How portswigger/json-decoder works
1. Repository purpose
- This repo is a small collection of Burp Suite extensions written in Python for Jython 2.7.
- It is not a single application with one runtime path; it is two separate Burp extensions plus the metadata needed to package one of them as a Burp BApp.
2. Top-level components
- JSONDecoder.py: a JSON pretty-printer / decoder helper for Burp.
- Argonaut.py: a parameter reflection/echo checker for requests and responses.
- BappManifest.bmf and BappDescription.html: Burp BApp packaging metadata and description content.
- There is no shared framework code visible in the repo; each extension appears to stand on its own.
3. Runtime and integration boundary
- Both extensions are designed to run inside Burp Suite, using Burp’s extension APIs rather than acting as standalone programs.
- The key architectural boundary is between:
- Burp’s HTTP traffic/event model and
- extension-specific analysis/formatting logic implemented in the Python files.
4. JSONDecoder subsystem
- This extension is a response-body transformer/decoder focused on JSON.
- Its core behavior is to take captured content, detect JSON-like payloads, and render it in a more readable pretty-printed form.
- It also contains a heuristic cleanup step for “JSON garbage” suffixes such as }]);, which means the parser is intentionally tolerant of non-strict JSON responses.
5. JSONDecoder data flow
- Burp provides a response body or selected content.
- The extension checks the content type, with default handling for application/json and text/javascript.
- If the user forces decoding or the content matches, the extension attempts to strip trailing noise, decode the JSON, and display a formatted output back in Burp.
6. Argonaut subsystem
- This extension scans request parameters and compares them against the corresponding response content to detect whether inputs are reflected.
- Its purpose is security-oriented: identifying where user-controlled data is echoed back by the target application.
7. Argonaut analysis flow
- Burp supplies request/response pairs.
- The extension enumerates request parameters, searches for matching occurrences in the response, and reports reflections.
- The important output boundary is not persistence or networking; it is the analysis result shown back to the tester inside Burp.
8. Transformation/escaping model in Argonaut
- Argonaut does more than plain substring matching: it accounts for output transformations so reflected data can still be recognized when escaped.
- The README shows two implemented transformation modes:
- Plain
- Jinja2 template escaping
- This makes the matching logic more robust against common encoding/escaping behaviors in server responses.
9. Shared architectural pattern
- Both extensions follow the same broad pattern:
- consume Burp-captured HTTP data,
- perform specialized parsing or matching,
- present enriched results to the user.
- Neither extension appears to introduce external services, databases, or background workers.
10. Packaging and distribution
- BappManifest.bmf and BappDescription.html indicate Burp’s BApp packaging format.
- That means at least one extension is intended for distribution through Burp’s extension ecosystem, with a manifest describing the extension and an HTML description for the BApp catalog.
11. Likely diagram boundaries
- For an architecture diagram, the most important boxes are:
- Burp Suite host
- JSONDecoder extension
- Argonaut extension
- BApp metadata/package
- Data arrows should run from Burp HTTP traffic into each extension, then back to Burp UI/output; there is no evidence of cross-extension calls.
12. Operational context
- The README explicitly calls out testing on Burp Suite 1.6.01 and newer, with Jython 2.7.
- That version/runtime pairing is materially important because it defines the execution model and Python compatibility for the extensions.
Main entry points: BappManifest.bmf BApp manifest · JSONDecoder.py JSONDecoder · Argonaut.py Argonaut · BappDescription.html BApp description
Components 13
Burp Suite
Host runtime and HTTP message boundary for both extensions
- Burp Suite · Burp host that supplies HTTP requests, responses, and UI integration
- HTTP traffic · Captured Burp messages consumed by both extensions
- Burp UI · Where formatted output and analysis results are shown to the tester
Extensions
Standalone Burp extensions implemented in Jython
- JSONDecoder · JSON pretty-printer and decoder helper
JSONDecoder.py - Type filter · Checks content type such as application/json and text/javascript
- Garbage strip · Removes trailing JSON noise like }]); before decoding
- Pretty print · Decodes JSON and renders readable formatted output
- Argonaut · Parameter reflection checker for requests and responses
Argonaut.py - Param scan · Enumerates request parameters for reflection testing
- Reflection match · Searches the response for parameter values and reports reflections
- Transforms · Normalizes matches for Plain and Jinja2 escaping behaviors
BApp packaging
Burp BApp metadata and catalog description
- BApp manifest · Burp BApp manifest describing the packaged extension
BappManifest.bmf - BApp description · HTML description content used for the Burp BApp listing
BappDescription.html
Connections 14
- Burp Suite → HTTP traffic: provides · Burp supplies request and response data to extensions
- HTTP traffic → JSONDecoder: feeds · Selected response content is passed into JSONDecoder
- JSONDecoder → Type filter: checks · Extension gates processing on content type or forced decode
- Type filter → Garbage strip: allows · Likely JSON payloads are cleaned before parsing
- Garbage strip → Pretty print: decodes · Cleaned payload is parsed and pretty-printed
- Pretty print → Burp UI: shows · Formatted JSON is returned to Burp for display
- HTTP traffic → Argonaut: feeds · Burp request/response pairs are analyzed by Argonaut
- Argonaut → Param scan: extracts · Parameters are enumerated from the request
- Param scan → Transforms: uses · Matching accounts for plain and Jinja2 escaping
- Transforms → Reflection match: normalizes · Transformed candidate values are compared against the response
- Reflection match → Burp UI: reports · Reflections are surfaced to the tester inside Burp
- BApp manifest → BApp description: pairs with · Manifest and HTML description together define the BApp package
- BApp manifest → Burp Suite: packages for · Metadata targets Burp's extension distribution ecosystem
- BApp description → Burp Suite: describes · Catalog description supports the Burp BApp listing