Important
Hunting notifications are no longer showed in the web interface. Use the /api/v3/ioc_stream endpoint (with
descriptors_only=true) instead to retrieve IoC-Stream notifications.
Retrieving matching files rather than just notifications
This API endpoint retrieves lists of hunting notification objects, but you may be more interested in retrieving the actual file objects tied to those notifications, you have two different options to do this:
Ask for the file relation when retrieving the hunting notifications, this will embed the descriptor for the file in the response, which includes the file identifier. This file identifier can then be used to perform a file object lookup via the file endpoint.
Make use of the hunting notification files endpoint, which returns a lists of file objects tied to your notifications, along with metadata about the hunting notification match.
This endpoint returns the notifications triggered by your own Livehunt rulesets, or by any other rule owned by somebody else and shared with you.
The filter parameter allows to filter the notification according to the values of certain attributes. For example you can get the notifications that are tagged as my_rule with tag:my_rule. Tags are automatically generated and include the matching file's SHA-256, the ruleset's name, and the identifier for the YARA rule matching the file.
You can also filter the notifications based on the ruleset's owner. With owner:some_user, you will get notifications generated by those rules that some_user shared with you. If you are interested only on those notifications triggered by your own rules, use the owner filter with you own user name. You can also combine multiple filters by separating them with spaces, for example: filter=tag:my_rule owner:foo.
In addition, it is possible to filter by the notifications date. The date parameter accepts both UTC timestamps or %Y-%m-%d date formats with ranges (-, +). For example, filter=date:1626960086+ returns the notifications that were generated since Thu 22 Jul 2021 15:21:26 CEST, filter=date:2021-07-22- returns the notifications generated before July 22th, 2021 and filter=date:2021-07-21+ date:2021-07-23- returns notifications generated since the July 21th, 2021 and before the July 23th, 2021.
The order parameters control the order in which notifications are returned, you can get them by ascending date with date+, and by descending date with date-. If no order is specified they will be order by descending date.
For more information check the Hunting Notification API object documentation.