OOBBridge

OOBBridge is a Java 21 Burp Suite extension that connects Burp's request-editing workflow to an existing, self-hosted Interactsh deployment through the local OpenSSH client. A user can reserve a mapped payload, insert it into selected request text, observe when that payload is later sent, record a sanitized request/response summary, and poll for safe interaction summaries.

OOBBridge does not send modified requests, scan targets, provision cloud resources, manage Interactsh, expose an HTTP API, store SSH keys, or replace the Azure evidence system. Closing Burp stops only local extension workers; remote callback collection and notification continue independently.

Architecture

Burp request editor                    Existing Azure VM
  user selection                           source of truth
       |                                         ^
       v                                         |
OOBBridge controller -> BackendClient -> local OpenSSH
       |                    |              fixed argv only
       |                    +-> Mock       JSON over stdin/stdout
       v
~/.oobbridge safe local config/cache

See docs/ARCHITECTURE.md for component and data-flow details.

Prerequisites

• Java 21.
• The included Gradle wrapper (downloads Gradle 9.6.0 on first use).
• A current Burp Suite release compatible with Montoya API 2026.4.
• For SSH mode only: local OpenSSH, an existing SSH alias, and the manually installed fixed bridge command.
• Python 3 on the remote Ubuntu host for the standard-library bridge.

Build

On Windows:

.\gradlew.bat clean test
.\gradlew.bat clean shadowJar

The loadable shaded JAR is:

build/libs/OOBBridge.jar

Jackson is included; Montoya API classes are compile-only and excluded because Burp provides them.

Load in Burp

1. Open Burp Suite.
2. Go to Extensions.
3. Add a Java extension.
4. Select build/libs/OOBBridge.jar.
5. Open the OOBBridge suite tab.
6. Start in the default Mock mode.
7. Configure SSH mode only after installing and testing the remote bridge manually.

Safe Mock-mode walkthrough

1. Leave Backend mode set to MOCK.
2. Enter an active engagement such as demo and click Save Settings.
3. Click Test Connection; the status should become Connected.
4. In an editable Burp request, select placeholder text such as REPLACE_ME.
5. Right-click and choose OOBBridge → Insert fresh OOB payload.
6. Confirm the insertion metadata.
7. Verify only the selected bytes changed to a hostname ending in .mock.invalid.
8. Manually send the request if desired. Insertion itself never sends it.
9. Review Payloads and Activity.

Mock state is in memory for the current extension load; safe payload associations and cursors are also cached in ~/.oobbridge/state.json. Ambiguous reservations are recovered through ~/.oobbridge/pending-reservations.json, which stores only opaque SHA-256 backend-bound operation keys and UUIDs. Each key includes the backend mode, SSH alias, fixed command, engagement, request context, and raw request hash, so a recovery identity cannot cross backend configurations. The file contains no raw requests.

SSH mode

First follow docs/AZURE_BRIDGE_SETUP.md. Then:

1. Verify the intended alias works in the operating system's existing SSH configuration.
2. In Settings, select SSH.
3. Configure the SSH executable, alias, and one fixed remote command.
4. Do not put arguments, request data, shell syntax, credentials, or key paths in the remote-command field.
5. Set the connection timeout and active engagement.
6. Click Save Settings, then Test Connection.
7. Enable polling only after the connection test succeeds.

The extension executes only:

ssh -T <alias> <fixed-command>

Every operation is JSON written to stdin. Remote diagnostics use stderr. Reservation requests include a client-generated UUID. A timed-out reservation is retried once with the identical UUID, so the bridge returns the committed payload instead of allocating another. The SSH timeout has a 30-second minimum; the optional remote interactsh-map step is limited to 5 seconds.

Azure bridge installation

Installation is deliberately manual. The repository does not execute or copy the helper. The operator copies server/interactsh-burp-bridge.py, installs it as the configured fixed command, sets ownership/permissions, optionally sets OOBBRIDGE_ENGAGEMENT_ROOT, and performs local health/reservation tests before enabling SSH mode. Exact commands and rollback steps are in docs/AZURE_BRIDGE_SETUP.md.

Security model

• Default backend is Mock.
• OpenSSH configuration remains under operating-system control.
• No private keys, passphrases, Azure credentials, or webhook secrets are accepted or stored.
• Shells are never invoked. Process arguments are separated, and HTTP content never enters the command line.
• Mapping must be durably saved and the returned hostname validated before request replacement.
• A delayed reservation re-reads the live editor request. If the selected bytes changed, the mapped hostname is copied instead of overwriting newer edits.
• Sensitive headers are replaced with [REDACTED]; bodies are disabled by default and bounded/redacted when enabled.
• SSH stdout is capped at 1 MiB and stderr at 64 KiB while both streams continue to be drained. Interaction responses contain at most 500 records and 1 MiB.
• The HTTP observer returns original messages unchanged and does its work asynchronously.
• Per-engagement cursors prevent repeat interaction processing.
• Payload refresh merges sent/callback flags so an advanced cursor cannot erase previously observed local status.
• Server writes are confined to OOBBridge-owned files under a strictly validated existing engagement directory.
• Crash-atomic reservations/<UUID>.json files are authoritative. JSONL remains a secondary, backward-compatible index.
• Any invalid authoritative reservation file fails closed with MAPPING_CORRUPT; listing, interaction association, and new allocation stop without consuming a payload.
• Backend configuration and client are replaced as one immutable, generation- tagged selection. Reservations, refreshes, polling, connection tests, and delayed sent-request evidence remain bound to the selection they captured.

See docs/SECURITY.md for boundaries and threat decisions.

Troubleshooting

• SSH executable missing: configure an executable name available on PATH or a local executable path. The extension stores the path, never key data.
• Authentication failed: test the configured alias outside Burp and repair the operating system's SSH configuration.
• Remote command missing: install the helper manually and ensure the fixed command resolves for the SSH user.
• Timeout: increase the bounded connection timeout and inspect Burp's extension error output plus remote stderr.
• No unused payloads: add payloads through the existing Azure workflow; the bridge never edits payload-history.txt.
• Payload mapped with warning: the durable mapping succeeded, but optional metadata, activity logging, or interactsh-map work did not. The hostname remains reserved and must not be reused.
• MAPPING_CORRUPT: an authoritative reservations/*.json file is invalid. Repair or restore that record from trusted evidence before reserving or listing payloads; OOBBridge will not allocate around it.
• No selection: insertion is enabled only for selected text in an editable request. Use Copy fresh OOB payload when replacement is not appropriate.
• No callbacks: verify Azure evidence independently, then check engagement and cursor state. Burp readiness does not prove a target triggered a callback.

Known limitations

• Burp loading and live GUI behavior require manual testing with a compatible Burp build; unit tests do not embed Burp.
• V1 insertion classification is deterministic but intentionally heuristic.
• Interaction parsing supports common JSONL field names and returns summaries; unusual Interactsh record shapes may have payload ID 0.
• The local cache is safe metadata, not a replacement for Azure evidence.
• Response summaries are associated by Montoya message ID and a short managed wait; a request with no response is recorded without a response summary.
• Interaction polling is single-flight. Large backlogs are returned in batches of at most 500 and continue from the returned byte cursor.
• Interaction cursors are opaque device:inode:offset values. File replacement or truncation resets the offset safely and reports a warning.
• The context-menu “View” action brings Burp to the foreground but Montoya does not expose an API to select an existing custom suite tab.

Uninstall

1. Remove OOBBridge from Burp's Extensions view.
2. Optionally delete ~/.oobbridge/ to remove local safe configuration/cache.
3. If SSH mode was installed, manually remove only the bridge executable and any bridge-specific environment wrapper you created.

Do not remove engagement evidence, interactions.jsonl, existing mapping files, Interactsh services, DNS, firewall rules, certificates, or notification configuration.