Migration Guidance from Backstory to Chronicle API – Alternate Endpoints for Key Backstory APIs

[vishnusoni]

Hello Chronicle team,

We are currently using the following Backstory API endpoints in our integration:

• List Detections

• List Assets

• UdmSearch

As these Backstory endpoints are slated for deprecation, we want to ensure a proper and complete migration to the supported Chronicle API equivalents. Could you please help us identify the respective replacement endpoints in the Chronicle API for the above?

Specifically:

1. What are the alternate Chronicle API endpoints for:

   • Listing assets

   • Listing detections

   • Performing UDM-based searches

A mapping or official reference documentation would be very helpful in planning our transition and avoiding service interruptions.

Thank you!

[Rene_Figueroa]

Hi @vishnusoni ,

We have a "legacy" API endpoints in the Chronicle API; this can be found in our documentation:

https://cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.legacy

You can find the 3 Backstory endpoints there as well.

[vishnusoni]

Hi @Rene_Figueroa ,
Thanks for sharing the reference.

We explored potential alternatives in Chronicle v1-alpha for each of the endpoints mentioned above. Below are our findings and associated issues:

1. List Detections:
   Alternate Endpoints Found: legacyGetDetection and legacySearchCuratedDetections
   Issue: legacySearchCuratedDetections seemed more appropriate. However, it requires a ‘ruleId’ query parameter, which we do not have in our standard workflow approach.
   Status: No suitable alternative found at this time.
   
   
2. UDM Search:
   Alternate Endpoints Found: instances.udmSearch
   Implementation:
        - Required IAM permission ‘chronicle.events.udmSearch’ was assigned to the service account.
        - Endpoint was integrated and called via script following all official documentation guidelines.
   Issue: Despite correct configuration, the request consistently returns a 500 Internal Server Error, which appears to be a server-side issue.
   Status: Alternate endpoint is identified, but functionality is currently blocked due to server error.
   
   
3. List Assets:
   Alternate Endpoints Found: legacyFindAssetEvents
   Issue: Our existing implementation relies on asset indicators such as ‘destination_ip_address’, ‘domain_name’, and ‘hash_sha256’. The assetIndicator parameter in the v1-alpha endpoint does not support these required artifacts (AssetIndicator Reference).
   Status: Endpoint is not completely aligned with our requirements, as the AssetIndicator query parameter is not compatible with our needs. Out of the available fields – we can use 'asset_ip_address' for ‘destination_ip_address’ may be, but rest two (‘domain_name’, ‘hash_sha256’) we cannot utilize as we could in backstory.

We are seeking assistance in these issues and open to have a call on the same if you're available. Please let us know what time is suitable for you, we can manage our timing accordingly.

[Rene_Figueroa]

Hi @vishnusoni thanks for the update. 

1. The ruleID has always been required in our Backstory endpoints. For non-curated rules, there is a feature where the "-" can be passed instead of a rule ID and it returns all rules detections. This feature is not available for CuratedDetections though. 

https://cloud.google.com/chronicle/docs/reference/detection-engine-api#listcuratedrules

https://cloud.google.com/chronicle/docs/reference/detection-engine-api#listcuratedruledetections

So, the same parameters are required in the Chronicle API version.

2. I would be curious to see the API call. I just tested this endpoint for my instance and it works as expected.

3. This does look like a gap in the Chronicle API. Can you please open a support case for it and mention me on it, so I can take a closer look? 

Thank you!

[vishnusoni]

@Rene_Figueroa FYI, We have accomplished the migration part and here're my findings which can be helpful for future:

1. We are now fetching rules from ListRules endpoint and extracting ruleId from each rule record, and using this ruleId to fetch Detection from LegacySearchDetections endpoint.

2. UDM Search endpoint was giving me 500 Internal Server Error because of time range, this endpoint only accepts the time range of 90 Days, If I provide more than 90 Days of time range, it will throw 500 Error code. Please check this at your end, bcz I think it should be handled at server side only that User can give whatever time range prompt.

3. We're now continuing with LegacySearchArtifactEvents endpoint as it's serving our purpose.

[Rene_Figueroa · Accepted solution]

Hi @vishnusoni ,

1. Yes, you are correct. The product team also confirmed that LegacySearchDetections is the alternative.

2. Yes, UDM search only supports 90 days at the moment. We can definitely update this to provide a more useful error message back.

3. Yes, LegacySearchArtifact is the better alternative for your purposes. 

We will update our UDM search API to provide a better error message.

[vishnusoni]

Hi @Rene_Figueroa ,
Thanks for the support so far.

It would be great if the UDM Search related issue is resolved asap because it's not even documented so I had to make a lot of hits & trials for this to conclude.

Once again, thank you very much.

[Rene_Figueroa]

Hi, yes, we will work on this. We do have documentation around the 90 days limit:

https://cloud.google.com/chronicle/docs/investigation/udm-search#:~:text=Note%3A%20The%20maximum%20t....

[vishnusoni]

Thanks for sharing the reference @Rene_Figueroa 
What I meant was, it would be much more helpful if the same section could be linked in the API documentation, ideally with a Note for better visibility.