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:

1. In the navigation pane, select System > API Access Management.
2. 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.