Repository navigation
Config Panel
The Config tab selects what to export, where it goes, and starts or stops the run.
First run? Follow Home — Quick Start. Hover labels, auth fields, and Index Fields trees for control detail. Sections below mirror the Burp UI when you need more than tooltips.
Config-tab steps Home does not cover:
- Cluster — Local stack: OpenSearch wiki — Home. Skip if you already have a reachable endpoint.
- Confirm in Log and Stats — Log Panel — Run checklist; Stats Panel Exported counts and Failures vs Recovered Failures. For non-local Database endpoints, also follow Monitoring remote database exports.
-
Validate in OpenSearch — OpenSearch — Working with indexed data; OpenSearch Dashboards (
meta.indexed_at; defaulttool-burp-*).
Top Config card. Checkboxes (with + expanders where sub-options exist):
- Settings (Project / User sub-options)
- Sitemap
- Issues (severity sub-options; Findings index)
- Traffic (tool-source expanders: Proxy, Proxy History, Repeater, Repeater Tabs, and others)
- Exporter (log levels, Stats, Config)
On Burp Suite Community Edition, Config disables sources and traffic tools that the Burp Montoya API does not expose for that edition. Those UI limits follow the API surface rather than a separate exporter policy.
- Issues / Findings — Disabled (no findings index).
- Traffic — Burp AI and Scanner are disabled; other traffic tools stay available when Traffic is selected.
- Snapshots vs live — Proxy History and Repeater Tabs run once at Start; Sitemap and Findings refresh on an interval while export runs; Proxy live WebSocket callbacks export frames observed during the run.
-
NULLandFALSE_POSITIVEseverities are not exported and do not appear in the UI. - Snapshot backlog lines in the Log panel report
seen,exported, and skip counts per source — handy when export scope is narrow. - Findings, Sitemap, Proxy History, and historic Proxy WebSocket work share one ordered startup coordinator. Each source starts with a 50-item slice, targets about 15 seconds per completed slice, and adapts within 1-250 items from its own prepared-byte and throughput history. A completed slice that severely overruns the target can shrink the next allowance immediately; the current slice is never interrupted. Each source then yields to the next lane. Only one heavy snapshot engine run executes at a time, which bounds prepared-document memory while allowing every source to make progress.
When Traffic → Proxy is selected, each live Proxy HTTP exchange is captured only during the current export run. The exporter first tries to bind it to the exact Burp Proxy History row so the document can carry History identity, edit-state, listener, and timing values. Proxy History remains a separate, explicitly selected one-shot startup snapshot.
Documents can appear in the export destination slightly after Burp receives the response while that History join completes. That export-side delay does not delay traffic passing through Burp: request/response callbacks do only bounded in-memory admission; History lookup, document sizing, temporary spooling, and destination handoff run on exporter workers.
The join uses a private annotation marker. After binding, the exporter removes that marker from Burp notes and from the exported document; existing user notes are preserved. If no unique History row is available after the 15-second correlation window, an otherwise complete downstream request/response exchange is still exported, while History-only fields remain unavailable. This prioritizes the traffic evidence without guessing metadata.
Proxy enrichment and observable-stage fields (History identity/timing values remain null when no exact bind is available):
burp.proxy.history_idburp.proxy.listener_portburp.proxy.history_is_editedburp.proxy.request_change_stagesburp.proxy.response_change_stagesburp.timing.req_sentburp.timing.endburp.timing.req_sent_to_res_startburp.timing.req_sent_to_res_end
The exported request and response are the furthest downstream representations the live Proxy callbacks expose: the request about to be sent and the response about to be returned to the client. The exporter does not emit unsent originals as additional documents. When all comparison points are observable, burp.proxy.request_change_stages and burp.proxy.response_change_stages report byte changes at RECEIVED_TO_SENT and, for responses, UPSTREAM_TO_RECEIVED. An empty list means the observed stages were equal; null means the comparison was unavailable. Proxy WebSocket live frames follow the same downstream rule and expose their own websocket.change_stages. History-only snapshots do not expose all live callback stages, so their stage fields can be null.
Fresh entries normally bind against newly appended History rows in near real time. Temporary spooling can move a pending document out of heap while the current run is still resolving it. The spool is an overflow mechanism, not persistent export state: Stop, extension unload, and the next Start discard unresolved prior-run artifacts. Nothing is replayed across export runs.
Temporary entries live in a protected, owner-restricted instance tree below {java.io.tmpdir}/burp-exporter/instances/<instance-id>/projects/<project-id>/proxy-correlation. Each loaded extension instance holds an operating-system ownership lock. Startup removes abandoned unlocked instance trees but never traverses a tree whose owner lock is still held. Symlink, ownership, and private-permission checks fail closed before sensitive writes.
The exporter-managed ceiling is per Burp project, including concurrent extension instances: 768 MiB for ordinary traffic spill plus 256 MiB for Proxy correlation (1 GiB total per project). Cross-process quota files serialize reservations. The separate free-space guard still preserves 1 GiB free on the volume.
Related panels: Log Panel — Live Proxy correlation lines, Stats Panel — Proxy Correlation, and Reference — Live Proxy History-field correlation.
Repeater Tabs is off by default so enabling it is an intentional choice. After start, Burp may appear frozen or unresponsive while the walk runs; more Repeater tabs usually means a longer freeze (commonly about 10-30 seconds; large tab sets can take longer). Expand Traffic and select Repeater Tabs when you want that historic snapshot.
Repeater Tabs is not the same as Repeater. It captures a one-time snapshot of the Repeater tabs you have open when you press Start - not live traffic. Live sends after export starts are represented when Repeater is also enabled under Traffic.
Burp does not expose Repeater tabs through the Montoya API, so this path is best-effort by design. The exporter combines three capture mechanisms:
- Editor hooks — extension request/response editor providers observe Repeater editor bindings as Burp attaches traffic to tabs.
- Context-menu fallback — a Repeater-only context-menu path for manual capture when hooks alone miss a tab.
- Startup Swing tab walk — on Start, two delayed passes (about 350 ms and 1.6 s later) walk Burp's Repeater UI on the EDT: select the Repeater tool, incrementally visit nested tab panes so each tab's editors bind, then restore your prior tool and tab selections. We do not intentionally switch Pretty / Raw / Hex / Render views.
Each pass owns a restoration stack and checks the active export generation between steps. Stop, unload, cancellation, or a traversal failure prevents later selections and still makes a best-effort restoration of the previously selected Burp tool and Repeater tabs. Because Burp's unload confirmation dialog can outlast a scheduled pass, unload cancellation is best-effort; the extension never treats a stale pass as part of a later run.
Captured pairs are cached for the extension session, de-duplicated per run, and exported to the traffic index with tool=Repeater Tabs when that source is selected. The walker treats only top-level standalone tabs and the child tabs inside Repeater groups as exportable slots; group containers and request/response editor tabs such as Pretty, Raw, Hex, Render, or Hackvertor are not exported as Repeater tabs.
Dedupe and metadata
- Per-run fingerprint — SHA-256 over request bytes, response bytes, and Burp annotations — prevents exporting the same tab twice across walk passes and editor rebinds.
- Startup slot keys — when Burp exposes a logical tab slot during the walk, two visible tabs with identical traffic can still export separately instead of collapsing into one document.
-
Tab / group labels — best-effort
burp.repeater.tab_nameandburp.repeater.tab_groupwhen readable headers exist;nullis preferred over a guessed mismatch (common with identical concurrent Repeater tabs). - Export scope — applied before a tab is queued; out-of-scope captures are skipped silently and can be exported later if you widen scope on a subsequent Start.
What to expect in the Log panel
-
[StartupExport] Repeater Tabs:— startup walk scheduled and session opened. -
[SnapshotExport] Repeater Tabs:- per-pass capture and delivery counts. Acapture completeline withdelivery_pending=truemeans Burp tab discovery has finished while queued destination delivery is still settling. The aggregate Traffic startup completion line refreshes those counters before reporting the final reconciled totals. - DEBUG startup-pass lines report Repeater tab containers, selection changes, and logical-slot capture counts separately. A container count is traversal structure, not the number of exported tabs.
- TRACE
[RepeaterTabs]lines — per-tab capture decisions (useful when tab metadata is missing or ambiguous).
Repeater Tabs startup captures do not appear in the [LiveTraffic] summary on Stop — that line is for live tool traffic only.
Repeater trace fields:
-
startupSessionties one Repeater Tabs startup walk together across its scheduling, per-tab observations, and pass summaries. It helps separate one Start cycle from another in long logs. -
metadataSourceexplains which signal won: — Repeater Tabs:startup_slotmeans a logical startup tab slot was available, so identical traffic in two visible tabs can still export twice;startup_fingerprintmeans dedupe/capture used only the request+response+annotation fingerprint. — Live Repeater:request_identity,request_hash, andexchange_hashare tracker-based signals;ui_fallbackmeans the tracker had no confident match and the current UI selection was consulted;request_stage_reusemeans response-stage export reused earlier confident request-stage metadata;ambiguous_nullmeans Burp exposed multiple plausible recent matches and the exporter intentionally left tab/group fields empty instead of guessing. - The Stats panel "Repeater Metadata Sources" row and exporter
stats_snapshotdocs summarize those livemetadataSourcecounts in aggregate. They are useful when a user run is too sensitive to reproduce but the trace vocabulary still shows which correlation path dominated. -
captureKey/fingerprint— see Repeater Tabs (slot vs fingerprint dedupe). TRACE may also showcapturePath(request_editor,response_editor,context_menu). - Startup summary lines may also include
alreadyCapturedSlotHighlights. That is the coalesced roll-up for repeated duplicate-slot observations when a large Repeater set would otherwise spam the same trace line over and over. The detailed per-observation trace is still emitted for the first few repeats per slot/path. - Concurrent live gaps are expected when Burp exposes neither a stable request object identity nor a unique request/exchange byte pattern. In that case, Swing inspection is only a best-effort current-selection view, so the exporter intentionally prefers
ambiguous_nullover reusing whichever tab happened to be focused later. - Trace logs identify the signal that supplied tab/group labels, whether the exporter reused earlier confident metadata, and whether null metadata reflects an ambiguous live request.
| Path | Source selection | Delivery |
|---|---|---|
| Proxy History WebSocket | Proxy History | One-shot bulk on Start |
| Proxy live WebSocket | Proxy | Proxy callback → traffic queue |
| Other tools live | Repeater, Intruder, etc. (not Proxy) | Live handler → traffic queue |
Historic Proxy WebSocket rows are exported only when Proxy History is selected; selecting Proxy alone does not replay old WebSocket History. Live Proxy frames are exported only while Proxy is selected and the run is active. The non-Proxy live handler skips duplicate Proxy registrations. Scope-filtered frames are skipped silently.
Second card: Burp Suite's, Custom (up to 100 host or regex rows), or All. The custom grid supports plain strings and regex (toggle per row, live validation). Scope applies together with your source and destination picks from Start onward.
Index Base Name plus per-index field trees (Settings, Sitemap, Findings, Traffic, Exporter). Hover the base-name field and every section/leaf for suffixes, date variables, tri-state groups, and field paths. Resolved names are fixed for the run from Start until Stop. Default is tool-burp (blank also falls back to tool-burp), so traffic lands in tool-burp-traffic; examples below use INDEX_BASE_NAME as the placeholder for your run's resolved base.
User-facing feature on traffic, sitemap, and findings HTTP shapes. Hover Fields tooltips on body.b64, body.decoded_b64, body.content_encoding.*, and body.text for control detail.
-
Captured wire bytes stay in
body.b64;body.lengthalways records the original captured length. Use this representation for exact replay. Files retain the full body even when database pressure fitting later shortens the search copy. -
Deepest decoded bytes land in
body.decoded_b64after at least one declaredContent-Encodinglayer is removed. Successful outer-layer work is retained even if a later layer is unsupported, malformed, exceeds the expansion bound, or the result is still binary. -
Encoding-chain evidence records decode-order tokens in
body.content_encoding.appliedand unapplied tokens in.remaining;.completeis true only when every non-identity declared layer was removed. Up to 8 layers are attempted, with an 8 MiB expanded-output cap per step. Supported tokens:gzip,x-gzip,deflate,br,zstd,compress, andx-compress;identityis ignored. -
Agent-readable text lands in optional
body.textonly when the deepest decoded bytes are classified as textual (skipped for mostimage/*,audio/*,video/*,font/*, andmodel/*;application/octet-streamis considered only whenContent-Encodingis present). Binary data remains available in Base64 even when text is null. -
Request-only gzip magic sniff when no
Content-Encodingbut declared form/multipart and wire starts with0x1f 0x8b. -
Supplements
request.parametersBODY rows from decompressed urlencoded forms when Burp returns none. -
Database pressure fitting can prefix-truncate body/payload and other large fields only when a prepared search document exceeds the current bulk byte budget. The indexed document sets
meta.search_truncated=trueand affected objects settruncated=true; body/payload length fields retain the original captured length. Files keep the full original document.
Indexes are created on Start with fixed, bundled mappings (not user-editable). The Fields panel controls which fields appear in exported documents (_source); it does not change the index schema.
| Index | When populated | Notes |
|---|---|---|
| INDEX_BASE_NAME-exporter | On Start; stats every 30s (configurable); log events when selected levels match | Config snapshots, stats_snapshot, forwarded log lines. Requires Exporter source + database URL. |
| INDEX_BASE_NAME-traffic | Live tool traffic; startup snapshots (Proxy History, Repeater Tabs); Proxy WebSocket History + live callbacks | Only selected traffic tools. Scope applied before queue. tool field identifies source. |
| INDEX_BASE_NAME-settings | On Start; re-export on change (30s check) | Project/User sub-options. Requires Settings source. |
| INDEX_BASE_NAME-sitemap | On Start; 30s poll for new in-scope rows | Per-run dedupe by entry fingerprint. Requires Sitemap source. |
| INDEX_BASE_NAME-findings | On Start; 30s poll for new in-scope issues | Severity sub-options; FALSE_POSITIVE / NULL never export. Disabled on Community Edition (see Community Edition limits). |
Upgrade / schema mismatch: If indexes were created under an older extension version, delete affected indexes and Start again so Start recreates them with current mappings (including body.b64, body.decoded_b64, body.content_encoding.*, and optional body.text).
Source sub-options (Config panel)
- Settings: Project, User.
-
Traffic: Proxy, Proxy History, Repeater, Repeater Tabs, Scanner, Intruder, Extensions, Burp AI, Sequencer. Scope (
All, Burp Suite, Custom) applies before queue. Proxy History = one-shot on Start; Repeater Tabs = best-effort startup snapshot; live tools stream during the run. Extensions excludes traffic to the configured OpenSearch URL (same host/port). - Issues: Critical, High, Medium, Low, Informational.
-
Exporter: log levels, Stats, Config (
Statsinterval defaults to 30s).
Orphaned requests (traffic): Proxy/Repeater requests with no response within 120s export as request-only documents (response.status == 0, response.reason_phrase == "Timeout").
Schema source for contributors: search/mappings.
No cluster yet? OpenSearch wiki — Home (Docker, password, TLS). Trust pinned certificate uses stack root-ca.pem: TLS certificates.
Available destinations are Files, Database (Amazon OpenSearch, Elasticsearch, or OpenSearch, in that UI order), or both. One database destination is active at a time. Path, format, disk-limit, auth, and TLS labels provide additional detail on hover.
Test Connection sits under the Database block (visible when a database destination is selected). It probes the current URL and in-memory credentials; Amazon OpenSearch may prompt for Deployment type when the endpoint cannot be auto-detected.
Files — On-disk export under a chosen root. Start preflights the path. Format choice, append behaviour, and re-import rules: Formats.
Database — One search destination at a time. The Base URL is an absolute HTTP or HTTPS root endpoint only (scheme, host, optional port 1-65535); a trailing / is removed. Paths, query strings, fragments, and embedded credentials are rejected — for example https://opensearch.url:9200 is valid, while https://host.example/prefix or https://user:pass@host.example is not. Auth modes depend on endpoint type (Auth type filtering). Secrets stay in session memory only; re-enter after restart. Non-secrets survive Import Config / Export Config.
When Database targets a non-local endpoint (Amazon OpenSearch, a remote OpenSearch/Elasticsearch cluster, Elastic Cloud, and similar — anything that is not a local lab stack beside Burp), monitor the run actively:
- Log — watch WARN and ERROR (capacity pressure, soft outage, auth rejection, permanent drops). Level filters and search help under load.
- Stats histograms — throughput charts often lull or go quiet during shared cooldowns, flush-slot waits, or soft outage. That is intentional pacing, not a hung export. Correlate long gaps with Misc Stats Peak Cooldown Wait (ms) and Peak Flush Slot Wait (ms) under Database Run Peaks.
- Failures vs Recovered Failures - the main catch-up signal. Failures can climb while the destination is under pressure; Recovered Failures rises as the retry drain succeeds.
Resource limits on the destination are handled as gracefully as possible: shared backoff/cooldown, smaller bulks, soft outage, and retry queues — instead of hammering a struggling cluster. Shared AIMD capacity control applies across OpenSearch, Amazon OpenSearch, and Elasticsearch. The endpoint may take a while to accept traffic again. While Config still shows Running, the exporter remains active and continues pacing toward recovery.
Every adaptive search destination starts conservatively near a 1 MiB bulk budget with one snapshot flush in flight. Healthy completed bulks can grow toward 5 MiB and up to three in-flight snapshot flushes; hard 429/502/503/504 or transport pressure immediately floors the budget near 512 KiB and serializes flushes until healthy progress is re-established.
Under prolonged gateway pressure, Soft Outage can coincide with a rising Traffic Spill status when live traffic outpaces the slowed drain. Soft Outage paces the destination; Traffic Spill absorbs that live-traffic overflow until it is Full. When Traffic Spill is Full, new live traffic is no longer accepted so the earliest backlog stays contiguous (not drop-oldest). Snapshot indexes (findings/sitemap/settings) do not use disk spill.
Capacity scope cues in the Log:
- Mild per-item capacity pressure is per-index (
scope=index). - Hard gateway statuses (
429/502/503/504) remain cluster-wide (scope=cluster).
During Stop drain, shared cooldown waits are capped at 2 seconds so shutdown can finish. Graceful Stop aims for about a 20 second wall-clock budget; any retries still undrained at the deadline become Permanent Drops in the Stop summary (not silent loss). A second Stop click remains a force-abort.
Exporter log/stats single-document pushes do not clear Soft Outage or shared AIMD alone. Soft Outage / hard cooldown can pause non-final exporter pushes so tiny exporter successes do not reopen a still-sick destination.
Wait until:
- Startup/snapshot backlog lines in the Log show complete for the sources you care about, and
- Failures has caught up with Recovered Failures (outstanding near zero aside from Permanent Drops / Retry Drops you already understand).
On large remote runs this is often much longer than five minutes. A short quiet stretch - or Failures ahead of Recovered for a few minutes - commonly reflects the backlog and retry drain catching up.
Auth failures (401/403) are different: repeated failures pause Database in Authorization Recovery and retain queued work while automatic probes look for valid credentials. This can clear when a credential source refreshes; otherwise, restore the affected credentials (Credential lifetime). Capacity detail: Stats - Overview, Stats - Database Capacity, Stats - Traffic Spill, Log - Run health, Amazon OpenSearch signals.
After a few Stop / Start recovery cycles, a remaining gap between Failures and Recovered Failures can be handled with a Files-only NDJSON run (JSONL is not a Bulk API format). This path avoids adding export load to a pressured Database destination and leaves upload timing and request sizing for a period when the cluster has headroom (Formats, Manual Bulk API upload).
Tested on t3.small.search. Under capacity pressure the exporter paces via soft outage (above) rather than overwhelming the cluster. If retries still leave a gap, use File-only fallback.
Each run uses one file format:
-
NDJSON (
.ndjson) - Bulk API-compatible output. Each document is two lines: anindexaction carrying a client-generated_id, then the document body. Re-sending the same file uses the same IDs; a later export run creates new operation IDs and appends new pairs. -
JSONL (
.jsonl) - local analysis output: one JSON object per line with no bulk action metadata. It is not directly accepted by the Bulk API.
The exporter writes one append-only file per selected logical index, does not rotate files, and leaves user-selected export roots separate from its managed spill directory. Stopping before archiving or handing files to another process leaves a complete, stable artifact. During a run, the exporter locks the normalized output directory and verifies each selected file's identity and expected size. External deletion, replacement, truncation, or growth fails Files closed; a configured Database destination may continue.
After a successful Files export, upload and destination administration are outside the Burp extension. The extension guarantees line-valid Bulk NDJSON, stable action IDs within the exported file, and final artifact integrity; the user chooses request batching, authentication, retries, index lifecycle, and capacity settings appropriate for the target service.
For a successful upload:
-
.ndjsonfiles go to their matching/{index}/_bulkendpoint;.jsonlhas no Bulk action metadata, and the NDJSON action line intentionally omits_index. - A destination index with compatible mappings preserves Burp Exporter field shapes without relying on dynamic auto-creation.
- Splitting or batching retains complete action/document pairs and the final newline.
- The Bulk API response-level
errorsfield and item errors report ingestion problems;_countand a spot_searchprovide destination-side validation. - Large files can be divided into smaller requests to fit service or proxy limits. Vendor examples often use small files, and managed services publish separate production batching and request-size guidance.
Destination-specific references:
-
OpenSearch Bulk API - NDJSON shape, final newline,
Content-Type,--data-binary, item errors, and request options. - Amazon OpenSearch Service: Upload data for indexing - introductory file upload with fine-grained Basic authentication; explicitly scoped to small test data.
- Amazon OpenSearch Service: Indexing data - production ingestion and signed-request guidance.
- Amazon OpenSearch Service Lens: Evaluate bulk request size - managed-service starting guidance of roughly 3-5 MiB per bulk request.
- Elasticsearch Bulk API - Elasticsearch NDJSON requirements and curl file submission.
Authentication also belongs to the destination workflow: OpenSearch and Elasticsearch use the method accepted by that cluster; Amazon Hosted may use fine-grained Basic or IAM SigV4, while Amazon Serverless uses IAM SigV4. See Signing HTTP requests to Amazon OpenSearch Service.
In-app Auth type dropdown tooltips list vendor documentation as plain text (not clickable in Burp). Clickable equivalents:
| Auth type | Documentation |
|---|---|
| API key | OpenSearch API keys |
| Bearer token | JWT authentication, Authentication tokens |
| Certificate | Client certificate authentication |
| Basic | Basic authentication |
| Auth type | Documentation |
|---|---|
| IAM SigV4 — Profile | Signing HTTP requests to Amazon OpenSearch Service |
| IAM SigV4 — Static | Same signing doc as Profile |
| Basic | Fine-grained access control, OpenSearch Dashboards on Amazon OpenSearch Service |
| None | Unsigned data-plane requests; deployment context below |
None sends no authentication header. It is a specialized option for a Hosted domain whose data plane intentionally accepts unsigned requests because access is enforced outside OpenSearch—for example, a VPC-only or tightly IP-restricted deployment using network trust, or an upstream reverse proxy that accepts the connection and injects/signs the credentials used toward Amazon OpenSearch.
None does not configure a forward proxy, provide custom proxy headers or cookies, or bypass IAM/fine-grained access control. A reverse proxy that expects Basic, bearer, API-key, or client-certificate authentication is represented by the corresponding auth type. Amazon OpenSearch Serverless accepts IAM SigV4, and AWS service configuration API calls remain signed even when the selected data-plane auth type is None.
| Auth type | Documentation |
|---|---|
| API key | Elasticsearch API keys |
| Bearer token | Token-based authentication services |
| Certificate | PKI realm |
| Basic | HTTP/REST client security |
-
Amazon OpenSearch Serverless (
.aoss.) — IAM SigV4 Profile/Static only (no Basic/None). - Elastic Cloud Serverless — API key / Bearer only.
-
Hosted Amazon OpenSearch (
.es.), self-hosted OpenSearch, upstream OpenSearch, and hosted Elasticsearch — full auth set per destination (including Basic where the cluster supports it).
For Amazon OpenSearch Serverless, index setup adapts the bundled 5s refresh interval to the service minimum of 10s. Other deployments retain the bundled value. Start also reads one Serverless index inventory before creating selected indexes, which avoids expected not-found probes for indexes that are not present yet.
OpenSearch, Amazon OpenSearch, and Elasticsearch each show only the credential fields relevant to the selected auth type. Test Connection appears on the selected database row only.
- Credentials sit under Auth type; TLS mode stacks below (HTTPS only, after the URL field loses focus).
- Sensitive fields (password, API key, bearer token, client-key passphrase) include an inline eye toggle and stay session-only.
- Credential values are opaque: leading/trailing whitespace and punctuation are preserved exactly rather than normalized. Empty required values still mean "not configured."
- Imported pinned certificates and client certificate/private-key files are limited to 10 MiB per file, which is comfortably above normal certificate and key sizes while bounding accidental or hostile input. Imported bytes stay in session memory and temporary parse artifacts are removed.
- Default Amazon auth is IAM SigV4 — Profile (dropdown order: Profile, Static, Basic, None).
-
IAM SigV4 — Profile re-resolves credentials on every signed request. Temporary credentials renew when the AWS profile is SSO, assume-role, or
credential_processand the SDK refresh succeeds. AWS shared-config / SSO / role chains can refresh without pasting a new session token. - IAM SigV4 - Static with a session token does not renew. Profile, or Static keys with Session Token blank, are better suited to multi-day or unattended Amazon runs.
- Bearer tokens (OpenSearch / Elasticsearch) are the same short-lived paste class. API key, when available, or Basic generally suits longer runs.
- Burp does not implement STS AssumeRole auto-refresh.
- When a Static session token or Bearer token field is non-empty, the Config UI shows an inline elevated-risk warning; Test Connection / Start emit a non-blocking WARN (export is not aborted).
- Field tooltips note that expired credentials can cause push failures, retry/outage handling, and — when the live traffic in-memory queue is full — protected per-instance spill files under the managed temporary-storage root (spill is the general backlog overflow path, not unique to auth expiry).
- API key TTL and certificate expiry are not specially warned. Credentials that outlast the expected run reduce the chance of an authorization pause.
- Mid-run HTTP 401/403 bulk failures log an authentication-rejected hint. After repeated failures, Database enters Authorization Recovery instead of disabling the destination or stopping the run. Database sends and snapshot production pause, queued retry documents remain retained, and automatic probes retry with increasing backoff. Files continue normally when enabled.
- After authorization returns, the exporter revalidates selected index settings and mappings. If the cluster UUID changed or selected indexes had to be recreated, it replays reproducible Settings, Findings, Sitemap, Proxy History, and historic Proxy WebSocket snapshots to Database only; Files are not duplicated. Live traffic and retained retries then resume.
- If an Amazon endpoint does not clearly indicate hosted (
.es.) or serverless (.aoss.), Test Connection posts a status message and reveals a Deployment type selector that flashes red once before settling to a subtle red border.
OpenSearch, Amazon OpenSearch, and Elasticsearch share the same destination-scoped TLS mode model (HTTPS endpoints only):
| Mode | Behaviour |
|---|---|
| Verify | JVM/system trust store |
| Trust pinned certificate | Imported server certificate |
| Trust all certificates | Disables server-certificate and hostname verification (lab testing only) |
For Elasticsearch Test Connection, these trust modes apply across Basic, API key, bearer token, certificate, and None authentication. Certificate authentication also presents the configured client certificate/key, including RSA PKCS#1 PEM keys from common local test tooling.
Bottom card: Import / Export configuration, Start / Stop, status text, and the run indicator. Hover Start and Stop for graceful shutdown, force-stop on a second click, spill behaviour, and mid-run destination disable.
Hand-edited JSON may contain unrecognized keys. Import warns and continues for most unknowns (yellow Control status + Log [Config] skips). Clean imports confirm in status and Log. Tables below are the full rules.
-
**dataSources:** omit when every source for the current Burp edition is selected; when only some are selected, write an inclusion array in stable order (settings,sitemap,findings,traffic,exporter). MissingdataSourceson import means all sources for that edition;[]means none selected. -
**dataSourceOptions:** omit when every branch matches defaults (all settings sub-options, edition traffic-tool defaults with Repeater Tabs off, all severities, all exporter sub-options, default stats interval). When only one branch differs, export only that branch's inclusion array. Missing branch keys on import mean that branch's defaults; presenttraffic: []means no traffic tools. -
**exportFields:** omit when every index has all toggleable fields on; when any index differs, write only those indexes (inclusion arrays). Indexes not listed mean all optional fields on for that index. Empty[]for one index disables optional fields for that index only. Exclusion lists are not used.
Import stops and the Config status shows an error when any of these apply:
| Condition | Example |
|---|---|
| Invalid JSON | Truncated file, wrong root type |
| Flat sink keys at wrong nesting level |
sinks.filesEnabled, sinks.fileLimits.*, sinks.openSearchTlsMode at the wrong level |
| Wrong JSON types |
sinks.files as a string |
Invalid OpenSearch auth.type
|
Unknown type string |
| Incompatible auth field mix |
Basic with apiKeyId, None with certPath, etc. |
Error messages name the expected nested shape (sinks.files, sinks.database, sinks.database.openSearch.*, sinks.files.limits.*).
Import applies recognized settings and lists skipped items when any of these apply:
| Kind | Example |
|---|---|
| Unknown object key | Top-level unknownTopLevel, sinks.unknownSinkFlag, unknown ui.log child |
| Unknown list value |
dataSources: unknown_source; dataSourceOptions.traffic: unknown_tool
|
| Unknown export field |
exportFields.traffic: request.body.removed
|
| Unknown export index | exportFields.unknown_index |
| Unsupported file format |
sinks.files.formats: xml (only jsonl, bulkNdjson) |
| Unrecognized scope shorthand |
scope: ["custom_only"] (falls through to custom handling when possible) |
| Edition stripped | Community: findings source, scanner / burp_ai traffic tools |
Export Config — Writes current non-secret settings to a JSON file on an owned background worker. Existing files require explicit replacement confirmation. The write is transactional: content is prepared in a uniquely named sibling temporary file and then atomically replaces the destination when supported, so an interrupted preparation does not truncate the prior file. Only the newest control action may update the Config status, and extension unload cancels outstanding callbacks.
Import Config — Applies non-secret settings from a JSON file and lists skipped unknown keys in the status bar and Log panel.
Configuration lifetime — Stop leaves the current Config choices in place so the same loaded extension session can be started again deliberately. Unloading/reloading the extension or restarting Burp returns the UI to defaults; use Export Config when you want to recreate non-secret choices later. Secrets and imported certificate/key bytes are never included in that file.
Start - Validates index naming and destinations, creates indexes, runs startup snapshots for selected sources, and starts live reporters for the run. If a selected index already exists, Start compares its live shard, replica-allocation, refresh settings, and required mapping fields with the bundled index definition. Extra dynamically discovered mapping fields are allowed. A confirmed incompatible index fails Start without changing or deleting data. The next Start can proceed after the settings are aligned or the index is recreated. If a least-privilege database principal can use the index but receives HTTP 401/403 specifically when reading _settings, Log warns and Start continues without the optional settings/mapping compatibility check.
Stop — First click starts a graceful stop: new correlation intake closes immediately (indicator Stopping; status shows queued traffic, spill, and retries), while the current run token remains valid long enough for already accepted destination work to drain. Shutdown aims for about a 20 second wall-clock budget: finish admitted response callbacks, finish the in-flight traffic bulk, stop periodic reporters, drain accepted traffic, clear remaining queue/spill state, drain retries when the database is enabled (Stop-path cooldown waits capped at 2 seconds), push final exporter stats, validate selected file artifacts, log file-count and Misc Stats session summaries, discard unresolved run-scoped correlation and spill artifacts, close destination connection pools, and return to Stopped. Stop does not call database _refresh or _count; database totals remain available in the destination and the UI/Copy surfaces use session counters. Retries still undrained at the deadline become Permanent Drops in the Stop summary (not silent loss). Unresolved live-traffic state is not carried into a later Start. Cancelled pushes log at TRACE and do not add to failure counters.
Click Stop again while shutdown is still running for a force stop: remaining remote work is skipped (retry drain, final stats, file validation, connection close), you get a shorter Log summary, pools reclaim with a ~1 s cap, and status shows Force-stopped.