Skip to content

v0.8.3 POST authentication fixed

Choose a tag to compare

View all tags
@LegendEvent LegendEvent released this 01 Jul 10:40
· 29 commits to main since this release
v0.8.3
2283a67

🎉 Darktrace SDK v0.8.3 Release Notes

Release Date: July 1, 2025
Previous Version: v0.8.1
Current Version: v0.8.3

🚀 Major Highlights

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

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:

  1. Signature Generation: Used json.dumps(json_body, separators=(',', ':')) → {"key":"value"}
  2. 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

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

Advanced Search POST Implementation

The Advanced Search module now properly:

  1. Builds complete query structures with search, fields, offset, timeframe, and time parameters
  2. Encodes queries as base64 using the existing encode_query() utility
  3. Sends POST requests with {"hash": "encoded_string"} body format
  4. Handles custom timeframes for both GET and POST methods
  5. 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:

  1. Check the updated examples in README.md
  2. Enable debug mode in your client for detailed logging
  3. Report issues on our GitHub repository with debug output
  4. 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! 🎉

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

Contributors

LegendEvent
Assets 2
Loading