A modern, Pythonic SDK for the Darktrace Threat Visualizer API.
- Batch operations for breaches:
acknowledge,unacknowledge, andget_commentsnow support lists of IDs and return aggregated results. - Helper methods for DeviceSearch: Added
get_tag,get_type,get_label,get_vendor,get_hostname,get_ip, andget_macfor easier device filtering. - Direct filter parameters for DeviceSearch: The
getmethod now accepts direct parameters liketag,type,hostname, etc., and auto-builds the query if no explicit query is given. - Improved error handling: A runtime error is raised if both
queryand filter parameters are set. A Sphinx warning is included in the docstring for better IDE/documentation feedback. - Best practices: SDK methods return Python objects, not JSON strings.
- Bugfixes: Improved JSON compatibility and response formats.
- Extensive API Coverage: Most endpoints, parameters, and actions from the official Darktrace API Guide are implemented.
- Modular & Maintainable: Each endpoint group is a separate Python module/class.
- Easy Authentication: Secure HMAC-SHA1 signature generation and token management.
- Async-Ready: Designed for easy extension to async workflows.
- Type Hints & Docstrings: Full typing and documentation for all public methods.
- Comprehensive Documentation: Detailed documentation for every module and endpoint.
pip install darktrace-sdkAfter installation, you'll import it in Python as darktrace:
from darktrace import DarktraceClientOr clone this repository:
git clone https://github.com/yourusername/darktrace.git
cd darktrace
pip install .from darktrace import DarktraceClient
# Initialize the client
client = DarktraceClient(
host="https://your-darktrace-instance",
public_token="YOUR_PUBLIC_TOKEN",
private_token="YOUR_PRIVATE_TOKEN"
)
# Access endpoint groups
devices = client.devices
all_devices = devices.get()
antigena = client.antigena
actions = antigena.get_actions()
# Use Advanced Search with POST requests (Darktrace 6.1+)
advanced_search = client.advanced_search
query = {
"search": "@type:\"ssl\" AND @fields.dest_port:\"443\"",
"fields": [],
"offset": 0,
"timeframe": "3600" # 1 hour
}
results = advanced_search.search(query=query, post_request=True)
print(all_devices)
print(actions)
print(results)Comprehensive documentation is available in the docs directory:
- Main Documentation - Overview and getting started
- Authentication - How authentication works
- Antigena - Managing Antigena actions
- Devices - Working with device information
- Model Breaches - Handling model breach alerts
- Status - System status information
And many more modules covering every aspect of the Darktrace API.
See the EXAMPLES.md file for additional usage examples.
This SDK aims to cover all endpoints in the Darktrace API Guide, including:
/advancedsearch(search, analyze, graph)/aianalyst(incidentevents, groups, acknowledge, pin, comments, stats, investigations, incidents)/antigena(actions, manual, summary)/components,/cves,/details,/deviceinfo,/devices,/devicesearch,/devicesummary/endpointdetails,/enums,/filtertypes,/intelfeed,/mbcomments,/metricdata,/metrics,/models,/modelbreaches,/network,/pcaps,/similardevices,/status,/subnets,/summarystatistics,/tags, and all/agemailendpoints
If you find a missing endpoint, open an issue or PR and it will be added!
The /devicesummary endpoint may return a 500 Internal Server Error when accessed with API tokens, even though it works in the browser or with session/cookie authentication. This is a known limitation of the Darktrace API backend and not a bug in the SDK or your code.
Workaround: There is currently no programmatic workaround. If you require this endpoint, please contact Darktrace support or use browser-based access where possible.
Status: Tracked as issue #37. If you encounter this, please reference the issue for updates.
Contributions are welcome! Please:
- Fork the repo and create your branch.
- Write clear, tested code and clean code principles.
- Add/Update docstrings and type hints.
- Submit a pull request with a detailed description.
This project is licensed under the MIT License. See LICENSE for details.
- Inspired by the official Darktrace API Guide
- Community contributions welcome!
Made with ❤️ for the Darktrace community.