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 Analytics > Event Discovery window 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.
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:
- In the navigation pane, select System > API Access Management.
- Select Event Feed Enabled. Your account starts sending events to the Cato API server.
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 1000 events per fetch)
- accounts (eventsFeedAccountRecords) - event data for the account (array with nested queries and fields)
eventsFeed Marker
When there are more than 1000 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 2500 events, then these are the results over the fetch iterations:
- first iteration - fetchedCount = 1000 (events), marker = 1234abc
- second iteration - fetchedCount = 1000 (events), marker = 4567def
- third iteration - fetchedCount = 500 (events), marker = 8901xyz
You can ignore the marker value 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 1000.
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
These are the field names for the different types of events in Event Discovery.
- src_site - name of the site or VPN user that initiates the connection
- src_site_id - ID of the site or VPN user that initiates the connection
- dest_site - for WAN traffic, destination type: site or VPN user
- rule - rule ID for security events
- ISP_name - The ISP used for this event (when the IP address isn't provided by the ISP, then the event message is IP Addresses are assigned statically)
- socket_interface - name for Socket interface in the Cato Management Application
- custom_category - the Custom Categories for your account (Configuration > Categories)
- directory_host_name - for LDAP events, the host name
- dest_port - Internet traffic, destination port number for the destination server
- bgp_peer_asn - BGP ASN for remote peer
- user_reference_id - The reference number of an incorrect category event
- src_port - internal port number
- link_health_pkt_loss - data that measures the packet loss for a specific link
- pop_name - Name of PoP for this event
- host_ip - IP address of the host
- event_message - Cato's description of the event
- src_site_name - Name of the source site or VPN user
- domain_name - SSL SNI, HTTP host name, DNS name
- dest_ip - for Internet traffic, destination server IP address
- file_hash - for anti-malware events, file hash
- src_isp_ip - ISP IP address for site or VPN client
- authentication_type - authentication method that is connected to this event, for example: MFA or password
- rule_name - firewall rule name in the Cato Management Application
- directory_sync_result - for LDAP events, result of sync with the Domain Controller
- host_mac - MAC address of the host
- threat_type - for anti-malware events, malware type
- threat_verdict - for anti-malware events, result of the malware scan. For files that are safe, value is clean.
- device_name - PC or device name
- link_type - link type: Cato, Alt. WAN or LAG
- login_type - User portal or VPN client (VPN or site traffic)
- configured_host_name - for a host with a Static IP address, name configured in the Cato Management Application
- internalId - unique identifier for each event
- directory_sync_type - LDAP event for a sync with the DC
- vpn_user_email - VPN user email address
- client_class - type of process generating this traffic
- incident_aggregation - (MDR event) A true/false value that indicates if this event is:
- A summary that aggregates many events (true)
- Raw network flows for a single event (false)
- socket_reset - hardware or software Socket reset
- user_name - (for clientless SDP events) VPN user name
- client_version - Socket or VPN Client version
- file_size - for anti-malware events, file size
- registration_code - Registration code that is used to authenticate a VPN Client
- bgp_error_code - BGP disconnect error message
- bgp_peer_description -description for BGP neighbor
- threat_name - name of anti-malware event
- qos_reported_time - time QoS event started
- ip_protocol - network protocol for this event
- bgp_cato_asn - BGP ASN for Cato peer
- src_ip - IP address for host or VPN client
- threat_reference - for anti-malware events, malware name. For IPS events, explains the reason why the traffic was blocked
- action - firewall, QoS or LAG action
- windows_domain_name - for LDAP sync events, name of the AD domain
- risk_level - anti-malware event, risk level
- socket_old_version - Socket upgrade, old version number
- link_health_latency - data that measures the latency for a specific link
- tunnel_protocol - protocol for the tunnel connection
- socket_new_version - Socket upgrade, new version number
- link_health_jitter - data that measures the jitter for a specific link
- upgrade_start_time - time the Socket upgrade started
- bgp_cato_ip - BGP IP address for Cato peer
- categories - Cato category for website or app
- rule_id - internal ID for Cato Management Application rule - firewall, network, and so on
- throttled_event_sub_type - For events that are repeated multiple times, there is a quota limit for this event type. When this event type passes the quota limit, the event is throttled. The subtype value shows the type of event that was throttled
- socket_role - for Socket high availability events, indicates if the Socket is primary or secondary
- targets_cardinality - (MDR event) amount of targets (servers) for a given incident
- upgrade_initiated_by - Socket upgrade initiated by Cato or as part of scheduled maintenance
- dest_is_site_or_vpn - destination type: site or VPN user
- bgp_peer_ip - BGP IP address for remote peer
- src_is_site_or_vpn - source type is: site or VPN user
- ad_name - Active Directory name
- link_health_is_congested - data that measures the congestion for a specific link
- subnet_name - name for subnet in the Cato Management Application
- os_version - version for host OS or tunnel device
- event_sub_type - sub-type for Routing, Security, Connectivity, System or Sockets Management event
- os_type - Host OS or tunnel device
- traffic_direction - Inbound or outbound
- bgp_suberror_code - BGP disconnect error message
- bgp_route_cidr - CIDR for BGP route
- incident_id - (MDR event) ID that identifies a security incident
- application - app used in Internet Firewall
- upgrade_end_time - time stamp that Socket upgrade completed
- socket_interface_id - Socket interface ID
- custom_categories - Custom Category for the account
- src_country - country based on public IP
- event_count - count for events that are repeated multiple times during one minute
- file_name - anti-malware event, file name
- directory_ip - LDAP event, IP address for the DC
- time - time stamp for the event
- url - URL for Internet traffic
- dest_country - for Internet traffic, destination server location
- flows_cardinality - amount of flows for a given incident
- dest_site_name - name of destination site or VPN user
- event_type - Routing, Security, Connectivity, System or Sockets Management event
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 8500 events, then these are the results over the first three fetch iterations:
- first iteration - fetchedCount = 1000 (events), marker = 1234abc
- second iteration - fetchedCount = 1000 (events), marker = 4567def
- third iteration - fetchedCount = 1000 (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.
Comments
7 comments
Question: how can we obtain the latest marker within the chain? This will speed up recovery processes instead of refetching all 7 days.
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
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
I only need to get the latest 60 seconds of events, can you please advise what the "marker" string should be in that case
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
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?
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
Please sign in to leave a comment.