docs

Darktrace SDK Documentation

This documentation provides detailed information about each module in the Darktrace SDK and how to use them.

Getting Started

from darktrace import DarktraceClient

# Initialize the client
client = DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN",
    debug=False,  # Set to True for verbose output
    verify_ssl=True  # SSL verification enabled by default
)

Client Options

Parameter	Type	Default	Description
host	str	required	The Darktrace instance hostname (e.g., 'https://example.darktrace.com')
public_token	str	required	Your Darktrace API public token
private_token	str	required	Your Darktrace API private token
debug	bool	False	Enable debug logging
verify_ssl	bool	True	Enable SSL certificate verification
timeout	int/float	None	Request timeout in seconds (None = no timeout)

⚠️ BREAKING CHANGE: SSL verification default changed from False to True in v0.9.0. If using self-signed certificates, you must either add them to your system trust store or set verify_ssl=False explicitly.

v0.9.0 Features

The SDK now includes several reliability and security features:

• Connection Pooling: HTTP connections are pooled via requests.Session() for better performance
• Context Manager: Use with DarktraceClient(...) as client: for proper resource cleanup
• Automatic Retry: Transient failures (5xx, 429, connection errors) are retried up to 3 times with exponential backoff (3s, 6s, 12s)
• SSRF Protection: Dangerous URL schemes (file://, ftp://, data://) are blocked; private IPs allowed

# Context manager usage (recommended)
with DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN",
    timeout=30  # Optional: 30 second timeout
) as client:
    devices = client.devices.get()
    # Connection automatically closed when exiting block

SSL Verification

SSL certificate verification is enabled by default for secure connections. For development environments with self-signed certificates:

client = DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN",
    verify_ssl=False  # Only for development/testing
)

⚠️ Warning: Disabling SSL verification is not recommended for production environments.

Available Modules

The Darktrace SDK provides access to all Darktrace API endpoints through the following modules:

1. Advanced Search - Complex search operations across the Darktrace platform
2. AI Analyst - AI Analyst incidents and investigations
3. Antigena - Antigena actions and configurations
4. Model Breaches - Model breach alerts and information
5. Components - Darktrace component information
6. CVEs - CVE information related to devices
7. Details - Detailed information about specific entities
8. Device Info - Detailed device information
9. Devices - Device management and information
10. Device Search - Search for devices with specific criteria
11. Device Summary - Summarized device information
12. Email - Darktrace Email security features
13. Endpoint Details - Endpoint-specific information
14. Enums - Enumeration values used in the Darktrace platform
15. Filter Types - Available filter types for searches
16. Intel Feed - Threat intelligence feed information
17. Model Breach Comments - Comments on model breaches
18. Metric Data - Time-series metric data
19. Metrics - Available metrics and their information
20. Models - Darktrace models and their configurations
21. Network - Network information and statistics
22. PCAPs - Packet capture functionality
23. Similar Devices - Find devices similar to a given device
24. Status - System status information
25. Subnets - Subnet information and management
26. Summary Statistics - Overall system statistics
27. Tags - Tag management for devices and entities

Authentication

The SDK handles authentication automatically using the provided public and private tokens. See Authentication for more details.

Error Handling

try:
    devices = client.devices.get()
except Exception as e:
    print(f"Error: {e}")

Debugging

Enable debug mode to see detailed API requests and responses:

client = DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN",
    debug=True  # Enable debug output
)