Skip to content

Contributor Guide

Jump to bottom
pS3ud0RAnD0m edited this page Oct 11, 2026 · 5 revisions

Contributing to Burp Exporter

Thanks for helping improve burp-exporter.

Start with the repository Contributing guide. It covers discussions, issues, pull requests, testing expectations, and the information that helps maintainers review a change.

This page is a short local-development companion. Users can start at Home.

Quick local setup

Library and API versions live in libs.versions.toml.

From the repository root. On Linux and macOS use ./gradlew; on Windows use .\gradlew.bat (same tasks either way):

./gradlew compileJava compileTestJava
./gradlew spotlessCheck
./gradlew spotbugsMain spotbugsTest

spotlessApply handles many formatting changes.

For a full local build with OpenSearch integration tests, inspect the destination index inventory before and after the build. On Linux and macOS:

curl -sk -u "<user>:<password>" "https://opensearch.url:9200/_cat/indices?v" \
  && ./gradlew clean build -POPENSEARCH_USER=<user> -POPENSEARCH_PASSWORD=<password> \
  && curl -sk -u "<user>:<password>" "https://opensearch.url:9200/_cat/indices?v"

On Windows (PowerShell):

curl.exe -sk -u "<user>:<password>" "https://opensearch.url:9200/_cat/indices?v"; if ($LASTEXITCODE -eq 0) { .\gradlew.bat clean build "-POPENSEARCH_USER=<user>" "-POPENSEARCH_PASSWORD=<password>" }; if ($LASTEXITCODE -eq 0) { curl.exe -sk -u "<user>:<password>" "https://opensearch.url:9200/_cat/indices?v" }

The test setup uses https://opensearch.url:9200; map that name to a local test cluster if you use one. The integration suite owns only disposable indexes whose names begin with tool-burp- and leaves none of those test indexes behind after a clean run. Unrelated cluster indexes are outside that suite's ownership. A cluster that is unavailable simply leaves the relevant integration tests skipped in CI. The OpenSearch wiki covers a local destination stack.

For UI changes, loading the built JAR in Burp provides a quick visual check. The repository Contributing guide has the fuller testing guidance, including temporary-file and reproduction-step conventions.

Implementation map

The code and Javadocs are the current source for implementation detail. These summaries help orient a contributor without duplicating them:

  • Logging: Logger.java sends runtime events to the Log panel. Burp Output receives only extension initialization/unload messages and initialization failures. Exporter-index forwarders add config, log, and stats documents without creating logging loops.
  • Sinks and retries: File and database exports share prepared documents where possible. The Log and Stats panels describe the user-facing result; the relevant sender and reporter classes show the current mechanics.
  • Run-scoped snapshot workers: SnapshotFlushExecutor owns startup, flush, and dual-sink pools for one export generation. Stop/unload retires old workers before a later Start installs usable replacements; late completions are fenced by run tokens.
  • Endpoint parsing: SearchEndpoint is the single canonical parser/resolver for database Base URLs. Path/query/fragment/user-info rejection and trailing-slash normalization stay centralized here rather than rebuilt with ad hoc URL strings.
  • Destination diagnostics: SearchDiagnosticText is the credential-redaction and UTF-8 byte-boundary for search-destination messages, response previews, headers, and exception chains. Transport logs go through this boundary.
  • HTTP body evidence: BodyContentEncodingSupport preserves exact wire bytes and progressively removes up to eight encoding layers. Mapping changes live in src/main/resources/search/mappings/ and cover Traffic, Sitemap, and Findings HTTP shapes together.
  • Managed temporary storage: ManagedDiskPaths owns the protected instance/project tree; ManagedStorageQuota provides cross-process per-project quotas. New paths stay under that tree and reuse the ownership, symlink, permission, low-disk, and quota checks.
  • Transactional whole-file output: WholeFileSave implements sibling-temporary writes and replacement semantics for configuration export. Whole-file writes reuse it instead of truncating the destination in place.
  • Repeater tab traversal: RepeaterSwingTabWalker owns best-effort EDT traversal, logical-slot identity, cancellation, and selection restoration. Exportable slots exclude Burp tool tabs, Repeater group containers, and editor sub-tabs.
  • UI-facing documentation: Config, Log, Stats, and Reference are the places to update when a behavior that users see changes.

Dependency and plugin versions live in the Gradle version catalog, gradle/libs.versions.toml. Catalog entries and their lock/verification effects stay updated together rather than scattering ad hoc version strings through source or build logic.

Adaptive batch size (implementation)

BatchSizeController provides one shared document-count target for bulk work. Successful bulks let the target grow; failures and capacity pressure reduce it. Payload builders still apply their byte limits, so document count is only one part of request sizing.

Traffic, periodic reporters, snapshots, and retry drains use this feedback alongside their own pacing and byte-aware limits. Stats and Exporter-index snapshots expose the resulting state for troubleshooting.

Export orchestration (implementation)

Start schedules the selected reporters, snapshots, and live traffic paths after preflight. Snapshot preparation uses bounded chunks and shared pacing; live traffic uses a queue and one drain worker. File and database work for the same prepared batch can run together, while retry recovery is database-only.

Source completion is reported through [SnapshotExport] and [StartupExport] lines. The Log Panel and Stats Panel describe how those results appear to users.

Traffic export path (offload and batching)

The HTTP handler builds an in-scope traffic document and offers it to a bounded queue rather than making a database call on Burp's HTTP thread. A dedicated worker drains that queue through chunked NDJSON bulk requests, with time and byte limits keeping latency and memory bounded.

Traffic Spill provides disk-backed headroom during destination pressure. Proxy History and historic WebSocket data use snapshot paths; live Proxy WebSocket polling and other live tool events join the traffic queue. The current implementation is in TrafficExportQueue, ChunkedBulkSender, and SnapshotExportEngine.

Clone this wiki locally