Skip to content

README.md

Latest commit

 

History

History
124 lines (100 loc) · 5.25 KB

README.md

File metadata and controls

124 lines (100 loc) · 5.25 KB

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
)