# 🚀 Darktrace Python SDK
> **A modern, Pythonic SDK for the Darktrace Threat Visualizer API.**
---
## 🆕 Latest Updates (v0.8.5)
- **Response Format Fix**: Some functions didn't return JSON. This is fixed now!
---
## ✨ Features
- **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.
---
## 📦 Installation
```bash
pip install darktrace-sdk
```
After installation, you'll import it in Python as `darktrace`:
```python
from darktrace import DarktraceClient
```
Or clone this repository:
```bash
git clone https://github.com/yourusername/darktrace.git
cd darktrace
pip install .
```
---
## 🚦 Quick Start
```python
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)
```
---
## 📚 Documentation
Comprehensive documentation is available in the [docs](docs/) directory:
- [Main Documentation](docs/README.md) - Overview and getting started
- [Authentication](docs/modules/auth.md) - How authentication works
- [Antigena](docs/modules/antigena.md) - Managing Antigena actions
- [Devices](docs/modules/devices.md) - Working with device information
- [Model Breaches](docs/modules/breaches.md) - Handling model breach alerts
- [Status](docs/modules/status.md) - System status information
And [many more modules](docs/modules/) covering every aspect of the Darktrace API.
See the [EXAMPLES.md](EXAMPLES.md) file for additional usage examples.
---
## 🛡️ Endpoint Coverage
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 `/agemail` endpoints
> **If you find a missing endpoint, open an issue or PR and it will be added!**
---
## ⚠️ Known Issues
### /devicesummary Endpoint Returns HTTP 500
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](https://github.com/LegendEvent/darktrace-sdk/issues/37). If you encounter this, please reference the issue for updates.
---
## 📝 Contributing
Contributions are welcome! Please:
1. Fork the repo and create your branch.
2. Write clear, tested code and clean code principles.
3. Add/Update docstrings and type hints.
4. Submit a pull request with a detailed description.
---
## 📄 License
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
---
## 🙏 Acknowledgements
- Inspired by the official Darktrace API Guide
- Community contributions welcome!
---
> Made with ❤️ for the Darktrace community.
Raw data
{
"_id": null,
"home_page": "https://github.com/LegendEvent/darktrace-sdk",
"name": "darktrace-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "darktrace, sdk, api, security, threat-visualizer",
"author": "LegendEvent",
"author_email": "LegendEvent <ridge.thrill7680@eagereverest.com>",
"download_url": "https://files.pythonhosted.org/packages/75/85/a62b9bb627c4e1fe3346c89e65bd98ad619eea6191e2752bea693e6012a1/darktrace_sdk-0.8.5.tar.gz",
"platform": null,
"description": "\r\n# \ud83d\ude80 Darktrace Python SDK\r\n\r\n\r\n\r\n\r\n\r\n\r\n> **A modern, Pythonic SDK for the Darktrace Threat Visualizer API.**\r\n\r\n\r\n---\r\n\r\n## \ud83c\udd95 Latest Updates (v0.8.5)\r\n\r\n- **Response Format Fix**: Some functions didn't return JSON. This is fixed now!\r\n\r\n---\r\n\r\n\r\n## \u2728 Features\r\n\r\n- **Extensive API Coverage**: Most endpoints, parameters, and actions from the official Darktrace API Guide are implemented.\r\n- **Modular & Maintainable**: Each endpoint group is a separate Python module/class.\r\n- **Easy Authentication**: Secure HMAC-SHA1 signature generation and token management.\r\n- **Async-Ready**: Designed for easy extension to async workflows.\r\n- **Type Hints & Docstrings**: Full typing and documentation for all public methods.\r\n- **Comprehensive Documentation**: Detailed documentation for every module and endpoint.\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install darktrace-sdk\r\n```\r\n\r\nAfter installation, you'll import it in Python as `darktrace`:\r\n\r\n```python\r\nfrom darktrace import DarktraceClient\r\n```\r\n\r\nOr clone this repository:\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/darktrace.git\r\ncd darktrace\r\npip install .\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udea6 Quick Start\r\n\r\n```python\r\nfrom darktrace import DarktraceClient\r\n\r\n# Initialize the client\r\nclient = DarktraceClient(\r\n host=\"https://your-darktrace-instance\",\r\n public_token=\"YOUR_PUBLIC_TOKEN\",\r\n private_token=\"YOUR_PRIVATE_TOKEN\"\r\n)\r\n\r\n# Access endpoint groups\r\ndevices = client.devices\r\nall_devices = devices.get()\r\n\r\nantigena = client.antigena\r\nactions = antigena.get_actions()\r\n\r\n# Use Advanced Search with POST requests (Darktrace 6.1+)\r\nadvanced_search = client.advanced_search\r\nquery = {\r\n \"search\": \"@type:\\\"ssl\\\" AND @fields.dest_port:\\\"443\\\"\",\r\n \"fields\": [],\r\n \"offset\": 0,\r\n \"timeframe\": \"3600\" # 1 hour\r\n}\r\nresults = advanced_search.search(query=query, post_request=True)\r\n\r\nprint(all_devices)\r\nprint(actions)\r\nprint(results)\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udcda Documentation\r\n\r\nComprehensive documentation is available in the [docs](docs/) directory:\r\n\r\n- [Main Documentation](docs/README.md) - Overview and getting started\r\n- [Authentication](docs/modules/auth.md) - How authentication works\r\n- [Antigena](docs/modules/antigena.md) - Managing Antigena actions\r\n- [Devices](docs/modules/devices.md) - Working with device information\r\n- [Model Breaches](docs/modules/breaches.md) - Handling model breach alerts\r\n- [Status](docs/modules/status.md) - System status information\r\n\r\nAnd [many more modules](docs/modules/) covering every aspect of the Darktrace API.\r\n\r\nSee the [EXAMPLES.md](EXAMPLES.md) file for additional usage examples.\r\n\r\n---\r\n\r\n\r\n## \ud83d\udee1\ufe0f Endpoint Coverage\r\n\r\nThis SDK aims to cover **all endpoints** in the Darktrace API Guide, including:\r\n\r\n- `/advancedsearch` (search, analyze, graph)\r\n- `/aianalyst` (incidentevents, groups, acknowledge, pin, comments, stats, investigations, incidents)\r\n- `/antigena` (actions, manual, summary)\r\n- `/components`, `/cves`, `/details`, `/deviceinfo`, `/devices`, `/devicesearch`, `/devicesummary`\r\n- `/endpointdetails`, `/enums`, `/filtertypes`, `/intelfeed`, `/mbcomments`, `/metricdata`, `/metrics`, `/models`, `/modelbreaches`, `/network`, `/pcaps`, `/similardevices`, `/status`, `/subnets`, `/summarystatistics`, `/tags`, and all `/agemail` endpoints\r\n\r\n\r\n> **If you find a missing endpoint, open an issue or PR and it will be added!**\r\n\r\n---\r\n\r\n## \u26a0\ufe0f Known Issues\r\n\r\n### /devicesummary Endpoint Returns HTTP 500\r\nThe `/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.\r\n\r\n**Workaround**: There is currently no programmatic workaround. If you require this endpoint, please contact Darktrace support or use browser-based access where possible.\r\n\r\n**Status**: Tracked as [issue #37](https://github.com/LegendEvent/darktrace-sdk/issues/37). If you encounter this, please reference the issue for updates.\r\n\r\n---\r\n\r\n## \ud83d\udcdd Contributing\r\n\r\nContributions are welcome! Please:\r\n\r\n1. Fork the repo and create your branch.\r\n2. Write clear, tested code and clean code principles.\r\n3. Add/Update docstrings and type hints.\r\n4. Submit a pull request with a detailed description.\r\n\r\n---\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\r\n\r\n---\r\n\r\n## \ud83d\ude4f Acknowledgements\r\n\r\n- Inspired by the official Darktrace API Guide\r\n- Community contributions welcome!\r\n\r\n---\r\n\r\n> Made with \u2764\ufe0f for the Darktrace community.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A modern, modular, and complete Python SDK for the Darktrace API",
"version": "0.8.5",
"project_urls": {
"Bug Reports": "https://github.com/LegendEvent/darktrace-sdk/issues",
"Homepage": "https://github.com/LegendEvent/darktrace-sdk",
"Source": "https://github.com/LegendEvent/darktrace-sdk"
},
"split_keywords": [
"darktrace",
" sdk",
" api",
" security",
" threat-visualizer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "46e74b59dd243e27d5ef6b561b2edc4269e1e4e4a70f68294543fef13bbfd531",
"md5": "9ea0902a1523d4411ef2312bddbf6257",
"sha256": "200a81884cc972348b9661337ff0a86bc1fbf4b6dab6edb33a91ec7f81668dd3"
},
"downloads": -1,
"filename": "darktrace_sdk-0.8.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ea0902a1523d4411ef2312bddbf6257",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 47080,
"upload_time": "2025-07-09T15:39:41",
"upload_time_iso_8601": "2025-07-09T15:39:41.097033Z",
"url": "https://files.pythonhosted.org/packages/46/e7/4b59dd243e27d5ef6b561b2edc4269e1e4e4a70f68294543fef13bbfd531/darktrace_sdk-0.8.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7585a62b9bb627c4e1fe3346c89e65bd98ad619eea6191e2752bea693e6012a1",
"md5": "1025e98a975f38800408a539a9ec3754",
"sha256": "372f09f65af3ce41db603741b3814df6f9e532401fd021c148073fa3a32f13eb"
},
"downloads": -1,
"filename": "darktrace_sdk-0.8.5.tar.gz",
"has_sig": false,
"md5_digest": "1025e98a975f38800408a539a9ec3754",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 31970,
"upload_time": "2025-07-09T15:39:42",
"upload_time_iso_8601": "2025-07-09T15:39:42.291714Z",
"url": "https://files.pythonhosted.org/packages/75/85/a62b9bb627c4e1fe3346c89e65bd98ad619eea6191e2752bea693e6012a1/darktrace_sdk-0.8.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 15:39:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LegendEvent",
"github_project": "darktrace-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.1"
]
]
}
],
"lcname": "darktrace-sdk"
}
JSON
