LiveUAMap enrichment

Shadowbroker's Global Incidents layer does not depend on LiveUAMap. GDELT remains the baseline incident source; LiveUAMap adds optional map-pin enrichment when one of the providers below is available.

Provider order

Supported LiveUAMap API (optional) — preferred when an operator has a paid/contracted API endpoint. Shadowbroker does not require this service.
Browser provider (best effort) — the existing Playwright integration. This remains enabled by default on Linux/macOS/Docker when Global Incidents is active, preserving existing behavior. Windows asks once before allowing the backend to contact LiveUAMap through the browser provider.
GDELT-only — if neither LiveUAMap provider is usable, Global Incidents still turns on and continues to receive GDELT data.

A LiveUAMap provider failure must never disable the broader Global Incidents feature.

Supported API configuration

Because LiveUAMap API endpoint/auth details are supplied under the operator's service agreement, Shadowbroker does not hard-code a vendor account endpoint. Configure the HTTPS JSON/GeoJSON URL you were given:

LIVEUAMAP_API_URL=https://your-liveuamap-api-endpoint.example/events
LIVEUAMAP_API_KEY=your-key
LIVEUAMAP_API_AUTH_HEADER=Authorization
LIVEUAMAP_API_AUTH_SCHEME=Bearer
LIVEUAMAP_API_TIMEOUT_S=30

LIVEUAMAP_API_KEY is optional at the code level so deployments whose endpoint already contains/handles authentication can still use the provider. The API URL must use HTTPS. Keys are sent only in the configured request header and are not included in provider-status responses or logs.

If the API request fails, Linux/macOS/Docker may fall back to the browser provider under the existing browser-provider policy. Windows falls back only if the operator separately opted into browser contact.

Browser-provider behavior

The browser provider is best effort because it consumes an undocumented web page representation rather than a stable public schema. Shadowbroker therefore:

treats strings, wrapped objects, keyed objects, double-encoded JSON, legacy base64 payloads, and GeoJSON as bounded parser inputs;
validates point coordinates before emitting markers;
skips malformed entries instead of failing an entire region;
detects obvious access/challenge pages and fails soft;
pauses repeated browser attempts after consecutive complete failures;
logs only structural payload diagnostics, not raw upstream payloads; and
retains the existing browser/stealth profile without adding new anti-bot bypass techniques.

Docker browser location (#516)

Published backend images install Playwright browsers into the shared /ms-playwright directory through PLAYWRIGHT_BROWSERS_PATH. The image build then verifies, as the non-root runtime user, that both Chromium and the matching headless-shell bundle are present and executable. This prevents the previous root-cache/runtime-user mismatch where the browser existed under /root while Playwright searched under /app/.cache.

Operator controls

# Explicitly enable or disable only the browser provider.
SHADOWBROKER_ENABLE_LIVEUAMAP_SCRAPER=true
SHADOWBROKER_ENABLE_LIVEUAMAP_SCRAPER=false

On Windows, the first Global Incidents enable offers LiveUAMap browser enrichment. Accepting or declining never blocks Global Incidents itself. A decline is remembered so the UI does not nag on every toggle. The environment flag remains the explicit override.

On Linux/macOS/Docker, leaving the flag unset preserves the historical behavior: the browser provider may run while Global Incidents is active. Set it to false if the operator wants GDELT-only operation unless a supported API is configured.

Failure semantics

LiveUAMap data is enrichment. If Chromium is missing, the upstream schema drifts, the site presents an access challenge, the paid API is unavailable, or every region returns malformed data, the provider returns no new pins and the error is contained. GDELT fetching and the rest of the Shadowbroker data pipeline continue independently.

4.0 KiB Raw Blame History