After extensive investigation and testing, we've successfully resolved the long-standing issue with Advanced Search POST requests that were failing with "API SIGNATURE ERROR". This was the most requested fix in the community.

🔧 Critical JSON Formatting Fix

Identified and fixed the root cause of POST request authentication failures across all SDK modules - inconsistent JSON formatting between signature generation and HTTP request bodies.

📈 Enhanced Darktrace 6.1+ Compatibility

Full support for modern Darktrace installations using POST-based Advanced Search queries.

🔧 Technical Changes

Core Authentication System (`darktrace/auth.py`)

Fixed JSON body parameter handling in signature generation
Standardized JSON serialization using separators=(',', ':') for consistent formatting
Enhanced debug output for POST request troubleshooting
Improved parameter sorting for authentication consistency

Advanced Search Module (`darktrace/dt_advanced_search.py`) - MAJOR REWRITE

✅ FIXED POST requests - Complete implementation of POST request support
Removed NotImplementedError that was blocking POST functionality
Added comprehensive query structure building for both GET and POST methods
Enhanced timeframe handling (custom, interval-based, default)
Added proper JSON body formatting with {"hash": "encoded_string"} structure
Improved error handling and debug output
Full backward compatibility with existing GET request usage

Statistics: +74 insertions, -23 deletions

Model Breaches Module (`darktrace/dt_breaches.py`)

Fixed POST requests for add_comment(), acknowledge(), and unacknowledge() methods
Standardized JSON serialization across all POST endpoints
Added comprehensive debug output for response tracking
Enhanced error handling with status code logging

Statistics: +93 insertions, -4 deletions

AI Analyst Module (`darktrace/dt_analyst.py`)

Fixed POST requests for add_comment() and create_investigation() methods
Improved JSON body handling for consistent authentication
Added debug response logging
Enhanced error tracking capabilities

Antigena Actions Module (`darktrace/dt_antigena.py`)

Fixed multiple POST endpoints:
- activate_action()
- extend_action()
- clear_action()
- reactivate_action()
- create_manual_action()
Standardized error handling across all POST methods
Improved debug output for troubleshooting
Enhanced response status tracking

Additional Module Fixes

Devices Module (dt_devices.py): Fixed update() POST method
Intel Feed Module (dt_intelfeed.py): Fixed create() POST method
Email Module (dt_email.py): Fixed email_action() and search_emails() POST methods
Model Breach Comments (dt_mbcomments.py): Fixed add() POST method

📊 Summary Statistics

Total Changes: 13 files modified
Lines Added: 271 insertions
Lines Removed: 119 deletions
Net Addition: +152 lines

Key Modules Updated:

✅ Authentication System - Core fixes
✅ Advanced Search - Complete POST implementation
✅ Model Breaches - 3 POST methods fixed
✅ AI Analyst - 2 POST methods fixed
✅ Antigena Actions - 5 POST methods fixed
✅ Devices, Intel Feed, Email, Comments - 1-2 POST methods each

🛠️ Breaking Changes

None. This release maintains full backward compatibility. All existing code will continue to work unchanged.

POST Request Upgrade: Users can now optionally use post_request=True parameter for Advanced Search and other POST-enabled endpoints, but this is entirely optional.

🔍 Technical Deep Dive

Root Cause Analysis

The core issue was discovered to be inconsistent JSON formatting between:

Signature Generation: Used json.dumps(json_body, separators=(',', ':')) → {"key":"value"}
HTTP Request Body: Used json.dumps(body) → {"key": "value"} (note the space)

This subtle difference caused Darktrace's strict signature verification to fail, resulting in "API SIGNATURE ERROR" responses.

Solution Implementation

Standardized JSON serialization across all POST endpoints
Updated authentication helper to handle JSON bodies consistently
Enhanced debug output to track request/response details
Added comprehensive test coverage for POST functionality

Advanced Search POST Implementation

The Advanced Search module now properly:

Builds complete query structures with search, fields, offset, timeframe, and time parameters
Encodes queries as base64 using the existing encode_query() utility
Sends POST requests with {"hash": "encoded_string"} body format
Handles custom timeframes for both GET and POST methods
Provides extensive debug logging for troubleshooting

📋 Testing

Comprehensive Test Coverage

✅ Advanced Search POST requests tested with SSL, TCP, and HTTP queries
✅ Multiple timeframe configurations (default, custom, interval-based)
✅ All POST endpoints verified across affected modules
✅ Backward compatibility confirmed for existing GET request usage
✅ Error handling validated for various failure scenarios

Production Validation

✅ Tested against live Darktrace instances
✅ Verified with real-world query patterns
✅ Confirmed API response structure compatibility
✅ Validated authentication signature generation

🎯 Migration Guide

For Advanced Search Users

Before (v0.8.1):

# Only GET requests worked
results = client.advanced_search.search(query=my_query)

After (v0.8.3):

# Both GET and POST now work
results = client.advanced_search.search(query=my_query)  # GET (default)
results = client.advanced_search.search(query=my_query, post_request=True)  # POST (new!)

For POST Endpoint Users

All POST endpoints that were previously failing should now work correctly without any code changes. The fixes are transparent to existing users.

🐛 Bug Fixes

Fixed GitHub Issue #1: Advanced Search POST requests now work correctly
Fixed API signature errors across all POST endpoints
Fixed JSON formatting inconsistencies in authentication
Fixed parameter ordering in signature generation
Enhanced error handling and debug output across modules

📝 Documentation Updates

Updated README.md to reflect Advanced Search POST functionality
Removed "Known Issues" section about Advanced Search POST problems
Added practical examples for Advanced Search POST usage
Enhanced Quick Start guide with POST request examples
Updated version references throughout documentation

🚀 What's Next

Upcoming Features (v0.8.4+)

Additional endpoint coverage expansions
Enhanced async support preparation
Performance optimizations for large result sets
Extended test coverage for edge cases

Community Feedback

We encourage users to test the new POST functionality and report any issues. This release resolves the most significant blocking issue in the SDK.

📞 Support

If you encounter any issues with this release:

Check the updated examples in README.md
Enable debug mode in your client for detailed logging
Report issues on our GitHub repository with debug output
Reference this release when asking for support

Download: pip install darktrace-sdk==0.8.3
Repository: https://github.com/LegendEvent/darktrace-sdk
Issues: https://github.com/LegendEvent/darktrace-sdk/issues

Made with ❤️ for the Darktrace community. Happy querying! 🎉

Fix post request json formatting by @LegendEvent in #41

Full Changelog: v0.8.1...v0.8.3

Contributors

LegendEvent

Assets 2

27 Jun 16:58

LegendEvent

v0.8.1

2d1d6ed

v0.8.1

Darktrace SDK v0.8.1 - First Official Release

🎉 First Official Release

This marks the first official release of the Darktrace Python SDK, providing a comprehensive and production-ready interface to the Darktrace API.

📚 Major Documentation Overhaul

This release features a complete rewrite of all API documentation with:

✨ Enhanced Documentation Features

Accurate method signatures matching the actual Python implementation
Comprehensive parameter documentation with types and validation details
100+ realistic usage examples for real-world security operations
Complete error handling sections with HTTP status codes and recovery strategies
Performance optimization guidance and best practices

🔍 Real-World Security Workflows

The documentation now includes practical examples for:

Incident Response: Breach investigation, device isolation, threat containment
Threat Hunting: Advanced searches, IoC analysis, network monitoring
Compliance & Reporting: Audit trails, security metrics, compliance dashboards
AI/ML Operations: Model insights, Antigena actions, predictive analytics
Network Security: Device management, subnet analysis, traffic monitoring

📖 Comprehensive Module Coverage

Updated documentation for all 27 SDK modules:

advanced_search - Complex threat hunting queries
analyst - Security analyst workflows
antigena - AI-driven security actions
breaches - Incident investigation and response
components - System component management
cves - Vulnerability management
details - Deep-dive investigations
deviceinfo - Asset discovery and profiling
devices - Device management and monitoring
devicesearch - Asset search capabilities
devicesummary - Device overview and health
email - Email security analysis
endpointdetails - Endpoint security insights
enums - API constants and enumerations
filtertypes - Search and filter operations
intelfeed - Threat intelligence integration
mbcomments - Model breach annotations
metricdata - Security metrics and KPIs
metrics - Performance and health metrics
models - AI model management
network - Network topology and analysis
pcaps - Packet capture analysis
similardevices - Device clustering and analysis
status - System health and status
subnets - Network segmentation analysis
summarystatistics - Aggregate security data
tags - Asset tagging and categorization

🔧 Technical Improvements

API Completeness

150+ documented API methods across all modules
500+ documented parameters with detailed descriptions
Comprehensive error handling for all API endpoints
Type hints and validation for better development experience

Developer Experience

Clear installation and setup instructions
Authentication and configuration examples
Best practices for API rate limiting
Performance optimization guidelines
Troubleshooting and debugging tips

🚀 Getting Started

from darktrace import DarktraceClient

# Initialize the client
client = DarktraceClient(
    base_url="https://your-darktrace-instance.com",
    public_token="your-public-token",
    private_token="your-private-token"
)

# Example: Search for suspicious devices
devices = client.devicesearch.search(
    query="anomalous activity",
    count=50,
    offset=0
)

# Example: Investigate a security breach
breach_details = client.breaches.get_breach_details(
    breach_id="12345",
    include_events=True
)

📦 Installation

pip install darktrace-sdk==0.8.1

🔗 Resources

Documentation: Comprehensive API reference in docs/modules/
Examples: Real-world usage patterns and workflows
GitHub: https://github.com/LegendEvent/darktrace-sdk
Issues: Report bugs and request features on GitHub

🙏 Acknowledgments

This release represents a significant milestone in making Darktrace's powerful API accessible to Python developers worldwide. The comprehensive documentation and examples enable security teams to quickly integrate Darktrace capabilities into their workflows.

Full Changelog: First official release with complete API documentation and examples

License: MIT License

Assets 2

0 Join discussion

Releases: LegendEvent/darktrace-sdk

v0.8.53

Uh oh!

v0.8.52

What's Changed

Contributors

Uh oh!

v0.8.51

What's Changed

Contributors

Uh oh!

v0.8.5

🆕 Latest Updates (v0.8.5)

Uh oh!

v0.8.4

Uh oh!

v0.8.3 POST authentication fixed

🎉 Darktrace SDK v0.8.3 Release Notes

🚀 Major Highlights

✅ RESOLVED: GitHub Issue #1 - Advanced Search POST Requests

🔧 Critical JSON Formatting Fix

📈 Enhanced Darktrace 6.1+ Compatibility

🔧 Technical Changes

Core Authentication System (darktrace/auth.py)

Advanced Search Module (darktrace/dt_advanced_search.py) - MAJOR REWRITE

Model Breaches Module (darktrace/dt_breaches.py)

AI Analyst Module (darktrace/dt_analyst.py)

Antigena Actions Module (darktrace/dt_antigena.py)

Additional Module Fixes

📊 Summary Statistics

🛠️ Breaking Changes

🔍 Technical Deep Dive

Root Cause Analysis

Solution Implementation

Advanced Search POST Implementation

📋 Testing

Comprehensive Test Coverage

Production Validation

🎯 Migration Guide

For Advanced Search Users

For POST Endpoint Users

🐛 Bug Fixes

📝 Documentation Updates

🚀 What's Next

Upcoming Features (v0.8.4+)

Community Feedback

📞 Support

Contributors

Uh oh!

v0.8.1

Darktrace SDK v0.8.1 - First Official Release

🎉 First Official Release

📚 Major Documentation Overhaul

✨ Enhanced Documentation Features

🔍 Real-World Security Workflows

📖 Comprehensive Module Coverage

🔧 Technical Improvements

API Completeness

Developer Experience

🚀 Getting Started

📦 Installation

🔗 Resources

🙏 Acknowledgments

Uh oh!

Core Authentication System (`darktrace/auth.py`)

Advanced Search Module (`darktrace/dt_advanced_search.py`) - MAJOR REWRITE

Model Breaches Module (`darktrace/dt_breaches.py`)

AI Analyst Module (`darktrace/dt_analyst.py`)

Antigena Actions Module (`darktrace/dt_antigena.py`)