Tracemill Add-on for Splunk
===========================

Polls the Tracemill platform for detection validation tasks, correlates SIEM
alerts against generated event IDs, and reports scoped pass/fail results.

Data sent to Tracemill
----------------------

All communication is outbound HTTPS (TLS-verified) from this add-on to the
Tracemill API endpoint configured on the account, authenticated with the
target-scoped validator token.

The control-plane calls (polling for validation tasks, acknowledging them,
reading task state) carry this input's own settings and no Splunk data: the
task poll reports its poll interval, its detection-inventory interval, and
whether detection-inventory reporting is enabled, so Tracemill can tell a
quiet agent from a deliberately disabled one. Beyond those settings, the only
data the add-on sends from your Splunk is these flows:

1. Detection inventory (periodic; see opt-out below). For each scheduled,
   shared saved search in the configured Curated Apps: app, owner, title,
   enabled/scheduled state, and classification signals
   (action.correlationsearch.enabled/.metadata/.annotations, presence of
   ESCU keys), plus a scan digest, scanned count, partial-visibility flag,
   the add-on version, and an instance fingerprint from
   /services/server/info (GUID, server name, Splunk version, cluster label).
2. Event observations (validation): the Tracemill-generated event ID and the
   timestamp it was observed in Splunk.
3. Alert correlation (validation): the fired detection's name, fire time,
   workload index, and a source reference (search job SID / savedsearch id).
   When the alert is correlated to a specific generated event, the matched
   Tracemill event ID is included; aggregate/result-row correlations carry
   no event ID.

Never sent: raw events or search results, SPL search strings, index names,
Splunk session keys, or any customer log data. Validation only ever searches
for events Tracemill itself generated.

Opt-out: disable "Detection Inventory Reporting" on the input to stop the
periodic version of flow 1 (flows 2-3 are the validation function itself).
While disabled, the add-on logs a detection_inventory_disabled event to
_internal instead of reporting on its own cadence. An inventory refresh
requested explicitly from Tracemill Cloud still runs, so disabling stops this
add-on's own schedule rather than every possible inventory read. To stop all of
it, disable or remove the input; clearing Curated Apps does not, since an empty
selection falls back to the default DA-ESS-ContentUpdate scope.

Third-party libraries in lib/ are vendored by the Splunk UCC build framework.
Native extensions (.so files) in lib/ are transitive dependencies of the UCC
runtime libraries (pycrypto, charset-normalizer).
