Cato API - EventsFeed (Large Scale Event Monitoring)

We strongly recommend that before you start using the Cato API, please review the Support Policy for the Cato API.

Overview of eventsFeed

The eventsFeed query helps you analyze events generated by activities related to networking, security, Sockets, Cato Clients, and more. The event data that this query returns is similar to the Monitoring > Events page in the Cato Management Application.

For reseller accounts, you can create separate API keys inside each customer account that you are connecting to the Cato API. For more about rate limiting and the eventsFeed API query, see Understanding Cato API Rate Limiting.

Understanding Fetched Events

The eventsFeed API call is designed high volume analysis and monitoring of events in your account. The data for this API query is updated in near real-time.

Cato stores event data for the previous seven days. Every 24 hours, data that is older than seven days is deleted.

When there are more than 3000 events in the API server queue, the results are paginated. This lets you iteratively fetch events until they reach the end of the queue.

These fields are related to the pagination for the events: marker, and fetchedCount. See below for explanations of these fields.

Enabling eventsFeed for Your Account

Use the API Access Management window to enable your account to send events to the Cato API server. After you enable eventsFeed, wait about 30 minutes for the API server to collect enough events to return data for the query.

To enable eventsFeed for your account:

  1. In the navigation pane, select Administration > API & Integrations and click the Events Integration tab.
  2. Select Enable integration with Cato events. Your account starts sending events to the Cato API server.

EventFeed.png

Details for the eventsFeed Fields

These are the details that the eventsFeed fields can show for the query:

  • marker - The marker field is a unique identifier for the last event that the API query returned
  • fetchedCount - number of events fetched (maximum 3000 events per fetch)
  • accounts (eventsFeedAccountRecords) - event data for the account (array with nested queries and fields)

eventsFeed Marker

When there are more than 3000 events in the API server queue, the Marker field shows an identifier that indicates the start of a new iteration to fetch events. For example, if the query returns 7500 events, then these are the results over the fetch iterations:

  • first iteration - fetchedCount = 3000 (events), marker = 1234abc
  • second iteration - fetchedCount = 3000 (events), marker = 4567def
  • third iteration - fetchedCount = 1500 (events), marker = 8901xyz

    You can ignore the marker value for the final iteration

eventsFeed fetchedCount

The fetchedCount fields shows the total number of events in the current fetch action. The maximum value for this field is 3000.

eventsFeed Accounts

The Accounts (eventsFeedAccountRecords) fields show the account IDs and event data for this query. Use the eventsFeedAccountsRecords > EventRecord > EventFieldName argument to filter the event data that is displayed for the query. For more about the EventRecords, see Cato API - EventsFeed > EventRecord.

eventsFeed > records > EventFieldName

For more information about the EventFieldName enum values for the different types of events, see the Cato Networks GraphQL API Reference.

Arguments for the eventsFeed

These are the arguments that you can pass and define the data that is returned by the query:

  • accountIDs - account IDs (for multiple accounts, enter the IDs as an array)
  • filters (EventFieldFilterInput) - filter the event and audit log data that is queried (array with nested queries)
  • marker - only show events for a specific fetch iteration according to the marker value

eventsFeed ID Argument

Enter one or more Cato account IDs for the data that the query returns. This argument is mandatory.

This account ID isn't shown in the Cato Management Application, instead it is the number in the URL for the Cato Management Application. For example, the account ID is 26 for the following URL: https://cc2.catonetworks.com/#!/26/topology.

eventsFeed filters Argument

The filters (EventFieldFilterInput) argument lets you define the specific events that are included in the query. These are the arguments you can define:

  • fieldName > EventFeedFilterFieldName - define the event type or subtype from Event Discovery
  • operator - define how to activate the values to filter the event data
  • values - define the filter value that is used with the operator

The following filter syntax is an example of a query that is filtered to show event types with the value Security:

"filters": [
{
"fieldName": "event_type",
"operator": "is",
"values": ["Security"]
}
]

The following filter syntax is an example of a query that is filtered to only show event subtypes with the value Internet Firewall:

"filters": [
{
"fieldName": "event_sub_type",
"operator": "is",
"values": ["Internet Firewall"]
}
]

eventsFeed marker Argument

The marker argument is mandatory and lets you limit the query to the events for a specific fetch iteration. For example, if the query returns 10500 events, then these are the results over the first three fetch iterations:

  • first iteration - fetchedCount = 3000 (events), marker = 1234abc
  • second iteration - fetchedCount = 3000 (events), marker = 4567def
  • third iteration - fetchedCount = 3000 (events), marker = 8901xyz

To show only the events in the second iteration, set the marker argument to 4567def.

To fetch all the queued events, run the query with an empty marker argument (marker:"") with the initial GraphQL query.

Was this article helpful?

7 comments

  • Comment author
    Thomas Jongerius

    Question: how can we obtain the latest marker within the chain? This will speed up recovery processes instead of refetching all 7 days.

  • Comment author
    Peter Lee

    Hi Thomas,

    If you are prepared to sacrifice the events already in the queue (which you effectively are, by starting at the end of the queue) then you can always disable the event feed integration in CMA, wait 1 hour, then re-enable and start with a fresh queue.

    Cheers,

    Peter

  • Comment author
    Thomas Jongerius

    Peter Lee,

    You are correct, obtaining the marker from a specific point (datetime UTC, this way we only need to hold record of this) in time is even better. Right now we have a very limited use case for this so latest is fine. However, automatic resolution would be better in that case.

    \Thomas

  • Comment author
    Chris.Reeves

    I only need to get the latest 60 seconds of events, can you please advise what the "marker" string should be in that case

  • Comment author
    Peter Lee

    Hi Chris,

     

    The marker is based on the index of the last record read rather than a particular timestamp. The eventsFeed call does not support time-based retrieval.

     

    Regards,

     

    Peter

  • Comment author
    Chris.Reeves

    Thanks for your quick response Peter.

    We are trying to get the latest events into a SIEM, if the "eventsFeed" call cannot start from the latest, is there a different call we can make to get the latest events?

  • Comment author
    Peter Lee

    Hi Chris,

     

    Unfortunately there is no easy way to force eventsFeed to start from the end of the queue. Can you please contact us on api@catonetworks.com to further discuss?

     

    Regards,

     

    Peter

Add your comment