Skip to content

v0.8.55

Choose a tag to compare

View all tags
@LegendEvent LegendEvent released this 21 Jan 18:20
· 40 commits to main since this release
v0.8.55
aabc5b4

v0.8.55 - Feature Release: Add 13 Missing Parameters to devicesummary Endpoint

What's New

✨ Features

  • Added 13 new parameters to devicesummary endpoint - Now fully aligned with Darktrace API specification:
    • Device Identification: device_name, ip_address
    • Time Range Filtering: start_timestamp, end_timestamp (epoch time in seconds)
    • Grouping Options: devicesummary_by (field name), devicesummary_by_value (value to group by)
    • Filtering: device_type, network_location, network_location_id, peer_id, source, status

📚 Documentation

  • Updated devicesummary documentation (docs/modules/devicesummary.md):
    • Complete parameter descriptions for all 13 new options
    • Added usage examples showing time range filtering, device type filtering, and grouping
    • Updated "Known Limitations" section to clarify HTTP 500 behavior with all parameters

🐛 Known Issues

  • devicesummary HTTP 500 error persists - Confirmed that the /devicesummary endpoint returns HTTP 500 Internal Server Error when accessed with API tokens, even with the newly added filtering parameters.
    • This is a Darktrace API backend limitation, not an SDK bug
    • All new parameters are correctly sent to the API (verified via testing)
    • See Issue #37 for details

Technical Details

API Compliance

The SDK is now 100% compliant with the Darktrace API Guide specification for the /devicesummary endpoint. All 16 parameters documented in the API Guide are now available in the SDK:

Parameter Type Description
did int (required) Device ID
device_name str Device name
ip_address str IP address
start_timestamp int Start time (epoch seconds)
end_timestamp int End time (epoch seconds)
devicesummary_by str Field to group by
devicesummary_by_value str Value for grouping
device_type str Device type filter
network_location str Network location filter
network_location_id str Network location ID filter
peer_id str Peer device filter
source str Source filter
status str Device status filter
responsedata str Limit response data

Usage Examples

from darktrace import DarktraceClient
import time

client = DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN"
)

# Time range filtering (last 24 hours)
end_time = int(time.time())
start_time = end_time - (24 * 60 * 60)
summary = client.devicesummary.get(
    did=123,
    start_timestamp=start_time,
    end_timestamp=end_time
)

# Device type and status filtering
summary = client.devicesummary.get(
    did=123,
    device_type="Workstation",
    status="active"
)

# Grouping by network location
summary = client.devicesummary.get(
    did=123,
    devicesummary_by="network_location",
    devicesummary_by_value="Office Building A"
)

Migration Notes

No breaking changes. All existing code continues to work as before. The new parameters are optional and can be used as needed.

Credits

This release improves API compliance based on comprehensive comparison of all 27 SDK endpoints against the Darktrace API Guide.

Assets 2
Loading