.png)
Darktrace Integration Guide
Connect Darktrace deployments to enterprise security workflows through deployment-specific REST APIs, selective outbound notifications, and SIEM-oriented event forwarding.
Darktrace integration options at a glance
Darktrace primarily integrates through deployment-specific REST APIs for retrieving devices, model breaches, incidents, alerts, models, and metrics where the product, license, version, and permissions allow. Selected security events can be delivered through outbound webhook-style notifications, while some deployments support SIEM-oriented forwarding such as syslog or structured formats including CEF. There is no confirmed public GraphQL, SOAP, bulk, or direct database interface. Martini can consume the Darktrace REST API, receive supported notifications, enrich events, map them to enterprise schemas, expose normalized APIs, and orchestrate scheduled reconciliation with idempotency, retries, and operational logging.
| Integration point | Supported by Darktrace? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve devices, model breaches, incidents, alerts, models, and metrics, and interact with supported platform capabilities. Endpoint availability depends on the deployment, product, version, licensing, and permissions. | Martini can consume the deployment-specific REST API, store the base URL and token as environment configuration, paginate or window requests, transform responses, and orchestrate downstream actions. |
| Webhooks / outbound callbacks | Limited | Deliver selected alert, model breach, investigation, or response-related notifications to an external endpoint. Coverage is event- and product-dependent rather than universal. | Martini can expose an API endpoint to receive supported Darktrace notifications, validate and normalize payloads, enrich them through REST calls, and apply idempotency and retry handling. |
| SIEM-oriented event forwarding | Limited | Some deployments can forward security events using syslog or structured formats such as CEF, subject to product and configuration support. | Martini can receive or process supported event deliveries, map them to a target SIEM schema, and route them to platforms such as Splunk or Microsoft Sentinel. The exact format must be confirmed for the deployment. |
| Authentication | Yes | API access uses deployment-configured credentials or tokens, authorization headers, and permissions associated with a Darktrace user or service account. | Martini can keep the Darktrace base URL and token in secure environment configuration, use HTTPS, and apply controlled access to exposed receiving APIs. |
| Bulk / async / batch APIs | Not confirmed | No broadly documented public bulk or asynchronous API was confirmed. Large retrievals may require pagination, time windows, reporting, or deployment-specific exports. | Martini can orchestrate bounded REST requests, scheduled reconciliation, pagination, overlap windows, and optional file or messaging steps when the surrounding architecture provides them. |
| File / attachment APIs | Not confirmed | Investigations may contain contextual data, links, or evidence, but a general-purpose public file or attachment API was not confirmed. | Martini can process files supplied by a confirmed export mechanism, but workflows should not assume that Darktrace exposes a general file API. |
| Database / analytics access | Not confirmed | Direct access to the underlying Darktrace database was not confirmed and should not be used as the default integration approach. | Martini can use documented APIs, configured event forwarding, or approved exports instead of connecting directly to the Darktrace appliance database. |
| GraphQL APIs | Not confirmed | No official public Darktrace GraphQL API documentation was verified. | Martini can consume REST and other confirmed endpoints; a GraphQL workflow should not be designed unless Darktrace provides a deployment-specific interface. |
How Darktrace exposes data and business events
Darktrace REST APIs
Darktrace provides deployment-specific REST APIs for accessing platform data and interacting with supported capabilities. REST access is the primary integration mechanism, but endpoints and resource coverage vary by product, deployment, version, licensing, and permissions.
Martini implementation pattern
Martini implementation pattern: Martini stores the Darktrace base URL and token securely, invokes the relevant REST operation, handles pagination or bounded time windows, maps the response into a canonical security model, and invokes downstream systems through a workflow.
Implementation sequence
Darktrace outbound notifications
Darktrace supports outbound notification and integration mechanisms for selected security events, including some alerts, model breaches, investigations, or response-related notifications. These notifications are selective and are not a universal stream of every event.
Martini implementation pattern
Martini implementation pattern: Martini exposes a controlled receiving API, validates the notification, applies idempotency, and calls the Darktrace REST API when the notification requires a complete or current resource representation before routing it to an enterprise destination.
Implementation sequence
SIEM-oriented forwarding
Some Darktrace deployments can forward security events through syslog or structured formats such as CEF. Exact formats, event coverage, and configuration depend on the relevant Darktrace product and deployment.
Martini implementation pattern
Martini implementation pattern: Martini processes the configured event delivery or receives the event through an approved endpoint, parses the selected format, normalizes security fields, and sends the result to a SIEM or security workflow.
Implementation sequence
Scheduled REST reconciliation
Scheduled API retrieval complements selective notifications when complete synchronization is required. Historical or high-volume retrieval may require pagination, bounded time windows, overlap periods, and deployment-aware polling intervals.
Martini implementation pattern
Martini implementation pattern: a scheduler starts a workflow that retrieves Darktrace objects incrementally, uses a watermark with an overlap window, upserts target records using stable source identifiers, and records checkpoints and failures for the next run.
Implementation sequence
Common Darktrace integration patterns
Pattern 1: Route Darktrace alerts to ServiceNow
When to use this pattern
Use this pattern when security operations needs Darktrace detections represented as ServiceNow incidents, security cases, tasks, or related CMDB context. It combines low-latency notifications with API enrichment and duplicate-safe upserts.
Integration direction
Example Mapping
| Darktrace Field | Canonical Field | Target Field |
|---|---|---|
| alertId or modelBreachId | sourceEventId | correlation_id |
| severity or priority | securitySeverity | priority |
| device identifier | affectedAssetId | cmdb_ci |
| model name | detectionName | short_description or detection field |
Martini implementation pattern
Martini receives a supported Darktrace notification, validates the identifier, and retrieves the complete incident, model breach, device, or metric context through the REST API. Mapping and business rules translate Darktrace severity and confidence into ServiceNow values, while the source identifier prevents duplicate incidents. Transient API and target failures are retried, and malformed or unauthorized events are sent to review handling.
Martini capabilities used
- workflows
- API consumption
- API exposure
- data mapping
- business rules
- idempotency
- error handling
Pattern 2: Send Darktrace detections to a SIEM
When to use this pattern
Use this pattern when an organization wants Darktrace detections and investigation context correlated with broader security telemetry in Splunk or Microsoft Sentinel. Notifications can provide low latency, while scheduled polling fills gaps in selective event coverage.
Integration direction
Example Mapping
| Darktrace Field | Canonical Field | Target Field |
|---|---|---|
| incident or alert identifier | eventId | vendor event identifier |
| device name or identifier | assetId | device or entity field |
| model name | detectionRule | rule name |
| source timestamp | eventTimeUtc | event time |
Martini implementation pattern
A Martini workflow accepts Darktrace notifications or retrieves data on a schedule, enriches events with device and model details, converts fields to the target SIEM schema, and sends the normalized event. It preserves original Darktrace values for auditability, uses stable event identifiers for deduplication, and records failed deliveries for controlled retry.
Martini capabilities used
- webhook consumption
- scheduled workflows
- API consumption
- data mapping
- JSON handling
- retry and error handling
Pattern 3: Synchronize Darktrace devices to a CMDB
When to use this pattern
Use this pattern when asset and monitored-device information must be reconciled into a CMDB or operational inventory. It is appropriate for recurring synchronization where devices may change state or disappear from the source result set.
Integration direction
Example Mapping
| Darktrace Field | Canonical Field | Target Field |
|---|---|---|
| device identifier | externalAssetId | correlation_id |
| device name | assetName | name |
| site | siteCode | location |
| device status | lifecycleStatus | install_status |
Martini implementation pattern
A scheduler invokes the Darktrace REST API using pagination or bounded time windows. Martini maps device attributes, performs create-or-update operations using the stable Darktrace identifier, and applies an agreed policy for devices no longer returned. Checkpoints, overlap windows, and retry handling reduce missed or duplicated updates.
Martini capabilities used
- scheduler triggers
- workflows
- API consumption
- pagination orchestration
- data mapping
- business rules
- checkpoint handling
Pattern 4: Enrich and route high-priority investigations
When to use this pattern
Use this pattern when only selected Darktrace incidents or model breaches should generate collaboration messages, escalation tasks, or response workflows. It supports severity, confidence, site, and affected-device routing without automatically taking containment actions.
Integration direction
Example Mapping
| Darktrace Field | Canonical Field | Target Field |
|---|---|---|
| severity and confidence | routingPriority | channel or notification priority |
| incident identifier | investigationId | message correlation |
| affected device | assetContext | message detail |
| investigation status | workflowStatus | notification status |
Martini implementation pattern
Martini receives a supported event or retrieves it through the REST API, applies explicit routing rules, obtains supplementary context, and sends a concise notification to Microsoft Teams or Slack. Lower-priority events can be aggregated or logged. Response actions remain disabled unless separately authorized, exposed by the Darktrace deployment, and audited.
Martini capabilities used
- webhook consumption
- API consumption
- conditional routing
- data enrichment
- business rules
- audit logging
- error handling
Applications commonly integrated with Darktrace
Darktrace data can be routed into security operations, incident management, collaboration, issue tracking, and retention platforms. Availability of a particular native export or receiving endpoint should be confirmed for the customer’s Darktrace deployment and target application; Martini can provide the orchestration, transformation, and control layer between them.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| ServiceNow | Create and update security incidents, security cases, tasks, or CMDB records from Darktrace detections and investigation context. | Darktrace → Martini → ServiceNow | Receive a supported Darktrace notification or poll the REST API, enrich the event with incident, model breach, and device context, then upsert a ServiceNow record using the Darktrace identifier as an external key. Route approved status or response updates back only when the relevant Darktrace endpoint and permissions are available. |
| Splunk | Centralize Darktrace detections and investigation context alongside other security telemetry for search, correlation, and reporting. | Darktrace → Martini → Splunk | Consume notifications or scheduled REST results, normalize timestamps, severity, device, model, and incident fields, and deliver the resulting event schema to Splunk. Apply bounded retries and retain failed deliveries for review. |
| Microsoft Sentinel | Bring Darktrace alerts into Microsoft security operations workflows, analytics, and incident correlation. | Darktrace → Martini → Microsoft Sentinel | Use a Martini webhook or scheduled workflow to retrieve and enrich Darktrace alerts, map them to the agreed Sentinel ingestion format, and send them through the target ingestion endpoint with correlation and duplicate handling. |
| Microsoft Teams | Notify security teams about high-priority Darktrace model breaches, incidents, or investigation changes. | Darktrace → Martini → Microsoft Teams | Apply severity, confidence, affected-device, and site rules in Martini, format a concise notification, and deliver only qualifying events to the Teams-supported receiving endpoint. Record the source identifier and delivery outcome. |
| Slack | Route selected Darktrace alerts to security operations channels for rapid triage and collaboration. | Darktrace → Martini → Slack | Receive or retrieve Darktrace events, apply channel-routing and deduplication rules, transform the payload into the agreed Slack message structure, and retry transient delivery failures without creating duplicate notifications. |
| Jira | Create investigation, remediation, or follow-up issues from Darktrace findings. | Darktrace → Martini → Jira | Map qualifying incidents or model breaches to Jira issue fields, preserve original Darktrace identifiers and severity values, and use an upsert or duplicate-check workflow to make retries safe. |
| Amazon S3 | Store normalized alert archives, periodic exports, or investigation data for retention and downstream analysis. | Darktrace → Martini → Amazon S3 | Retrieve approved Darktrace data through the API, normalize it into an agreed JSON or file representation, and write it to Amazon S3 with partitioning by date, deployment, and object type. Direct Darktrace-to-S3 export must be confirmed separately. |
How to build a Darktrace integration in Martini
Objective
Establish controlled access to the customer’s Darktrace deployment and target systems without embedding deployment details or secrets in workflow logic.
Instructions in Martini
- Confirm the Darktrace base URL, product scope, API version, site scope, and permitted resources
- Create or obtain a least-privilege Darktrace service account or API token
- Store the base URL and credentials in Martini secure environment configuration
- Use HTTPS and validate network, certificate, and allowlisting requirements
- Configure authentication for the selected target APIs
Objective
Select an event-driven, scheduled, or hybrid trigger based on Darktrace notification coverage and synchronization completeness requirements.
Instructions in Martini
- Use a Martini API endpoint for supported Darktrace notifications
- Use a scheduler for device, incident, alert, or metric reconciliation
- Combine notifications with scheduled polling when selective event coverage is insufficient
- Define polling intervals that respect appliance or service capacity
- Set an overlap window and checkpoint strategy for scheduled retrieval
Objective
Obtain the complete Darktrace object needed for downstream processing rather than relying on a partial notification payload.
Instructions in Martini
- Validate the incoming event or retrieve the next REST page or time window
- Call permitted Darktrace resources for incident, model breach, device, model, or metric context
- Handle pagination, sorting, timestamp semantics, and incomplete results
- Preserve source identifiers and original timestamps
- Avoid assuming that every product or deployment exposes identical fields
Objective
Coordinate validation, enrichment, business rules, target calls, checkpointing, and failure handling in a maintainable Martini workflow.
Instructions in Martini
- Create a workflow for the selected Darktrace integration path
- Separate notification intake, enrichment, transformation, and delivery responsibilities where useful
- Apply correlation IDs and record source and target identifiers
- Use conditional branches for severity, site, product, and authorization rules
- Keep response or containment actions behind explicit approval controls
Objective
Convert Darktrace-specific objects and values into the canonical and target schemas required by enterprise systems.
Instructions in Martini
- Map Devices, Alerts, Model breaches, Incidents, Models, and Metrics explicitly
- Normalize timestamps to UTC while preserving the original source value
- Map severity, confidence, priority, and model scores using agreed business rules
- Retain original Darktrace identifiers and values for auditability
- Handle optional fields defensively across products and deployment versions
Objective
Control routing, deduplication, authorization, and lifecycle behavior before writing to downstream systems.
Instructions in Martini
- Use a stable alert, model breach, incident, or device identifier as the idempotency key
- Filter or route events by severity, confidence, site, and affected device
- Define behavior for stale, inactive, or no-longer-returned devices
- Require explicit authorization for any response or containment operation
- Validate required fields before downstream delivery
Common Darktrace data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Devices | Represent network, cloud, email, or other monitored entities identified by Darktrace; commonly used for asset inventory, enrichment, and routing. | ServiceNow CMDB, Splunk, Microsoft Sentinel, Jira | Martini retrieves devices through REST requests, handles pagination or time windows, maps stable identifiers and attributes to the target model, and performs create-or-update synchronization. |
| Model breaches | Represent activity that matched a Darktrace detection model and may require investigation or response. | ServiceNow, Splunk, Microsoft Sentinel, Microsoft Teams, Slack | Martini receives a supported notification or polls for breaches, retrieves complete context when needed, maps severity and model data, and uses the breach identifier for idempotency. |
| Incidents | Represent correlated security investigations or AI Analyst findings that group related activity. | ServiceNow, Microsoft Sentinel, Jira, Splunk | Martini enriches incident notifications with related devices, alerts, and model information, preserves source timestamps and identifiers, and routes according to explicit business rules. |
| Alerts | Represent security notifications or detection outputs generated for operational triage. | Splunk, Microsoft Sentinel, ServiceNow, Microsoft Teams, Slack | Martini validates and normalizes alert payloads, applies severity and destination rules, optionally retrieves additional Darktrace data, and retries downstream delivery safely. |
| Models | Represent detection and behavioral-analysis models used to identify suspicious activity and explain model breaches. | Security data lakes, Splunk, ServiceNow | Martini can retrieve model information where permitted and associate it with breaches or incidents while preserving the original model name and identifiers. |
| Metrics | Provide telemetry and security measurements for monitoring, reporting, and analysis. | Splunk, Microsoft Sentinel, Amazon S3, reporting platforms | Martini retrieves permitted metric data using bounded requests, normalizes timestamps and dimensions, and writes results to the selected analytics or retention destination. |
Authentication and security considerations
Deployment-specific access
Darktrace API access is normally associated with a customer deployment rather than a single shared endpoint. Confirm the base URL, product scope, API version, site restrictions, enabled resources, and required permissions before implementation.
Credentials and transport
Use a dedicated least-privilege service account or API token and send requests over HTTPS. Store the base URL and token in Martini secure environment configuration rather than workflow source or mapped payloads.
Inbound notification protection
Restrict the Martini receiving API and validate any Darktrace-supported authentication or signature mechanism for the deployed release. Network allowlisting, TLS validation, and API gateway controls may also be appropriate.
Response authorization
Containment or other response actions should require explicit business authorization, appropriate Darktrace permissions, and strong audit logging. Do not invoke response APIs solely because an alert was received.
Operational considerations for Darktrace integrations
Rate limits and capacity
Universal Darktrace rate-limit values were not confirmed. Use bounded requests and conservative polling intervals coordinated with the deployment administrator to avoid unnecessary appliance or service load.
Pagination and watermarks
Large device or detection collections may require pagination, time windows, and overlap periods. Confirm page behavior, sort order, timestamp semantics, and cursor or offset support for the deployed API.
Idempotency and consistency
Use stable Darktrace identifiers for deduplication. A notification may arrive before complete incident or model breach details are available, so workflows may need a short retry or re-query strategy.
Schema variation
Fields can differ across Darktrace products and deployment versions. Treat optional fields defensively, preserve original values, and test mappings against representative payloads.
Monitoring and recovery
Capture the operation, status, source identifier, target identifier, retry count, correlation ID, and final outcome without logging secrets. Use review or dead-letter handling for malformed events, authorization failures, expired credentials, and persistent target errors.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini separates Darktrace intake, API enrichment, transformation, business rules, and target delivery into maintainable workflows instead of duplicating logic across scripts or point-to-point connections.
Hybrid synchronization
Selective Darktrace notifications can trigger low-latency processing while scheduled REST reconciliation covers events and objects that are not delivered through outbound notifications.
Reusable data contracts
Martini can map Darktrace-specific objects into canonical security models and expose controlled APIs for downstream consumers, reducing repeated transformation work across ServiceNow, SIEM, collaboration, and issue-management destinations.
Operational control
Workflows provide a consistent place to implement idempotency, retries, overlap windows, validation, authorization, correlation, monitoring, and review handling as deployment and schema differences evolve.
Frequently asked questions
Darktrace can integrate through deployment-specific REST APIs, selected outbound webhook-style notifications, and in some deployments SIEM-oriented forwarding such as syslog or structured formats like CEF. REST APIs are used to retrieve devices, alerts, model breaches, incidents, models, and metrics where permitted. Because event coverage and API availability vary by product and deployment, complete synchronization commonly combines notifications with scheduled REST reconciliation.
Yes. Martini can consume the Darktrace REST API, receive supported Darktrace webhook-style notifications, enrich alerts and investigations, transform data, and route normalized events to systems such as ServiceNow, Splunk, Microsoft Sentinel, Microsoft Teams, Slack, and Jira. The exact resources and event types depend on the customer’s Darktrace deployment and permissions.
No. A dedicated Darktrace connector is not required. Martini can use Darktrace’s confirmed native integration mechanisms, including deployment-specific REST APIs, supported outbound notifications, and configured event-forwarding methods, while providing the workflows, mappings, API endpoints, and error handling around them.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Darktrace. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Darktrace, cloud infrastructure, or other third-party systems depending on subscription, usage, licensing, and deployment model.
REST APIs are the primary method for retrieving deployment data and supported platform capabilities. Selective outbound notifications are useful for low-latency alerting, while scheduled REST polling or reconciliation is recommended for complete synchronization. Some deployments may also support syslog or structured SIEM-oriented forwarding. No public Darktrace GraphQL or SOAP API was confirmed.
No. Darktrace notification coverage is selective and depends on the product, event type, configured integration, and version. Notifications may cover selected alerts, model breaches, investigations, or response-related events. Martini can receive supported notifications and combine them with REST retrieval and scheduled reconciliation for data that is not delivered through notifications.
Martini can receive an event or retrieve Darktrace objects on a schedule, enrich partial payloads through REST calls, and map objects such as Devices, Alerts, Model breaches, Incidents, Models, and Metrics into canonical and target schemas. Workflows can normalize timestamps, apply severity rules, preserve source identifiers, paginate requests, and use overlap windows and checkpoints.
A robust workflow uses the Darktrace alert, model breach, incident, or device identifier as an idempotency key, rather than timestamps alone. Martini can retry transient API and target failures, log correlation and source identifiers, handle delayed resource availability with re-queries, and route malformed payloads, permission errors, expired credentials, and persistent failures to review or dead-letter handling.
Yes. Martini can expose a controlled API that normalizes selected Darktrace alerts, incidents, devices, or metrics for downstream applications. The façade can centralize authentication, field mapping, authorization, filtering, and audit behavior while Martini retrieves the underlying data from Darktrace when the relevant API resources and permissions are available.
Related Martini documentation
Workflows
Build a maintainable Darktrace integration
Use Martini to connect Darktrace APIs and supported notifications with your security operations architecture through governed workflows, reusable mappings, secure configuration, and reliable synchronization.