# portswigger/json-decoder architecture

> Architecture diagram of the GitHub repository portswigger/json-decoder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/portswigger/json-decoder
- Repository: https://github.com/portswigger/json-decoder

## Overview

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`](https://github.com/portswigger/json-decoder/blob/master/BappManifest.bmf) (BApp manifest), [`JSONDecoder.py`](https://github.com/portswigger/json-decoder/blob/master/JSONDecoder.py) (JSONDecoder), [`Argonaut.py`](https://github.com/portswigger/json-decoder/blob/master/Argonaut.py) (Argonaut), [`BappDescription.html`](https://github.com/portswigger/json-decoder/blob/master/BappDescription.html) (BApp description)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_burp["Burp Suite"]
  node_burp_suite["Burp Suite<br/>host runtime"]
  node_http_messages["HTTP traffic<br/>request/response stream"]
  node_burp_ui["Burp UI<br/>results surface"]
end

subgraph group_extensions["Extensions"]
  node_json_ext["JSONDecoder<br/>Burp extension<br/>[JSONDecoder.py]"]
  node_json_filter{{"Type filter<br/>content gate"}}
  node_json_cleanup{{"Garbage strip<br/>tolerant parser"}}
  node_json_render["Pretty print<br/>formatter"]
  node_arg_ext["Argonaut<br/>Burp extension<br/>[Argonaut.py]"]
  node_param_enum{{"Param scan<br/>request analysis"}}
  node_reflect_match{{"Reflection match<br/>echo detector"}}
  node_transform_modes{{"Transforms<br/>escaping model"}}
end

subgraph group_package["BApp packaging"]
  node_manifest["BApp manifest<br/>package metadata<br/>[BappManifest.bmf]"]
  node_description["BApp description<br/>catalog text"]
end

node_burp_suite -->|"provides"| node_http_messages
node_http_messages -->|"feeds"| node_json_ext
node_json_ext -->|"checks"| node_json_filter
node_json_filter -->|"allows"| node_json_cleanup
node_json_cleanup -->|"decodes"| node_json_render
node_json_render -->|"shows"| node_burp_ui
node_http_messages -->|"feeds"| node_arg_ext
node_arg_ext -->|"extracts"| node_param_enum
node_param_enum -->|"uses"| node_transform_modes
node_transform_modes -->|"normalizes"| node_reflect_match
node_reflect_match -->|"reports"| node_burp_ui
node_manifest -->|"pairs with"| node_description
node_manifest -.->|"packages for"| node_burp_suite
node_description -.->|"describes"| node_burp_suite

click node_json_ext "https://github.com/portswigger/json-decoder/blob/master/JSONDecoder.py"
click node_arg_ext "https://github.com/portswigger/json-decoder/blob/master/Argonaut.py"
click node_manifest "https://github.com/portswigger/json-decoder/blob/master/BappManifest.bmf"
click node_description "https://github.com/portswigger/json-decoder/blob/master/BappDescription.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_burp_suite,node_http_messages,node_burp_ui toneBlue
class node_json_ext,node_json_filter,node_json_cleanup,node_json_render,node_arg_ext,node_param_enum,node_reflect_match,node_transform_modes toneAmber
class node_manifest,node_description toneMint
```

## Components

### Burp Suite

Host runtime and HTTP message boundary for both extensions

- **Burp Suite**: host runtime · Burp host that supplies HTTP requests, responses, and UI integration
- **HTTP traffic**: request/response stream · Captured Burp messages consumed by both extensions
- **Burp UI**: results surface · Where formatted output and analysis results are shown to the tester

### Extensions

Standalone Burp extensions implemented in Jython

- [JSONDecoder](https://github.com/portswigger/json-decoder/blob/master/JSONDecoder.py): Burp extension · JSON pretty-printer and decoder helper · `JSONDecoder.py`
- **Type filter**: content gate · Checks content type such as application/json and text/javascript
- **Garbage strip**: tolerant parser · Removes trailing JSON noise like }]); before decoding
- **Pretty print**: formatter · Decodes JSON and renders readable formatted output
- [Argonaut](https://github.com/portswigger/json-decoder/blob/master/Argonaut.py): Burp extension · Parameter reflection checker for requests and responses · `Argonaut.py`
- **Param scan**: request analysis · Enumerates request parameters for reflection testing
- **Reflection match**: echo detector · Searches the response for parameter values and reports reflections
- **Transforms**: escaping model · Normalizes matches for Plain and Jinja2 escaping behaviors

### BApp packaging

Burp BApp metadata and catalog description

- [BApp manifest](https://github.com/portswigger/json-decoder/blob/master/BappManifest.bmf): package metadata · Burp BApp manifest describing the packaged extension · `BappManifest.bmf`
- [BApp description](https://github.com/portswigger/json-decoder/blob/master/BappDescription.html): catalog text · HTML description content used for the Burp BApp listing · `BappDescription.html`

## Connections

- 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