""" The @beta directive is used within the type system definition language to indicate beta portions of a GraphQL service's schema, such as beta fields, enum values, arguments or input fields. """ directive @beta on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE | OBJECT """ The @ga directive is used within the type system definition language to indicate GA portions of a GraphQL service's schema, such as GA fields, enum values, arguments or input fields. """ directive @ga on FIELD_DEFINITION """ The @ea directive is used within the type system definition language to indicate EA portions of a GraphQL service's schema. """ directive @ea on FIELD_DEFINITION """ The @rollout directive is used within the type system definition language to indicate portions of a GraphQL service's schema that is gradually rolling out. This APIs will be available to all accounts after a few weeks. """ directive @rollout on FIELD_DEFINITION type Query { accountBySubdomain( accountID: ID! """a list of required subdomains""" subdomains: [String!]! ): [AccountDataPayload!] @ga accountManagement(accountId: ID!): AccountManagementQueries """ The accountMetrics query helps you analyze the state and quality of the connections of sites and SDP users to the Cato Cloud. This data is for the traffic inside the DTLS tunnel between the site and the Cato Cloud. accountMetrics shows historical metrics, statics, and analytics for the account. """ accountMetrics( """Unique Identifier of Account.""" accountID: ID id: ID @deprecated(reason: "by accountID") """ The time frame for the data that the query returns. The argument is in the format type.time value. This argument is mandatory. """ timeFrame: TimeFrame! """ When the boolean argument groupInterfaces is set to __true__, then the data for all the interfaces are aggregated to a single interface. """ groupInterfaces: Boolean """ When the boolean argument groupDevices is set to __true__, then the analytics for all the Sockets (usually two in high availability) are aggregated as one result. For the best results for aggregated Sockets, we recommend that there is consistent names and functionality (for example Destination) for the links on both Sockets. """ groupDevices: Boolean ): AccountMetrics @ga accountRoles(accountID: ID!, accountType: AccountType): AccountRolesResult! @ga """ Current snapshot-based metrics that show near real‑time data for the account. Provides analytics that are similar to the Topology page for the account. """ accountSnapshot( """Unique Identifier of Account.""" accountID: ID id: ID @deprecated(reason: "by accountID") ): AccountSnapshot @ga admin(accountId: ID!, adminID: ID!): GetAdminPayload @ga admins(accountID: ID!, limit: Int = 50, from: Int = 0, search: String = "", sort: [SortInput], adminIDs: [ID!]): AdminsResult @ga "BETA" appStats( "Account ID" accountID: ID! timeFrame: TimeFrame! measures: [Measure] dimensions: [Dimension] filters: [AppStatsFilter!] postAggFilters: [AppStatsPostAggFilter!] sort: [AppStatsSort!] ): AppStats @ga "BETA" appStatsTimeSeries( "Account ID" accountID: ID! timeFrame: TimeFrame! measures: [Measure] dimensions: [Dimension] filters: [AppStatsFilter!] ): AppStatsTimeSeries @ga """Audit Feed for account changes""" auditFeed( """List of Unique Account Identifiers.""" accountIDs: [ID!] ids: [ID!] @deprecated(reason: "by accountIDs") timeFrame: TimeFrame! filters: [AuditFieldFilterInput!] "Marker to use to get results from" marker: String ): AuditFeed @ga catalogs(accountId: ID!): CatalogQueries container(accountId: ID!): ContainerQueries devices(accountId: ID!): DevicesQueries! @beta enterpriseDirectory(accountId: ID!): EnterpriseDirectoryQueries @ea """Lookup entities with a specific type, potentially filtered and paged""" entityLookup( """The account ID (or 0 for non-authenticated requests)""" accountID: ID! """Type of entity to lookup for""" type: EntityType! """Sets the maximum number of items to retrieve""" limit: Int = 50 """Sets the offset number of items (for paging)""" from: Int = 0 """ Return items under a parent entity (can be site, vpn user, etc), used to filter for networks that belong to a specific site for example """ parent: EntityInput """ Adds additional search parameters for the lookup. Available options: country lookup: "removeExcluded" to return only allowed countries countryState lookup: country code ("US", "CN", etc) to get country's states """ search: String = "" """ Adds additional search criteria to fetch by the selected list of entity IDs. This option is not universally available, and may not be applicable specific Entity types. If used on non applicable entity type, an error will be generated. """ entityIDs: [ID!] """ Adds additional sort criteria(s) for the lookup. This option is not universally available, and may not be applicable specific Entity types. """ sort: [SortInput] """Custom filters for entityLookup""" filters: [LookupFilterInput] """Additional helper fields""" helperFields: [String!] ): EntityLookupResult! @ga events( "Account ID" accountID: ID! timeFrame: TimeFrame! measures: [EventsMeasure] dimensions: [EventsDimension] filters: [EventsFilter!] postAggFilters: [EventsPostAggFilter!] sort: [EventsSort!] ): Events @ga """Event Feed for events paged by a topic partitions offsets marker""" eventsFeed( """List of Unique Account Identifiers.""" accountIDs: [ID!] filters: [EventFeedFieldFilterInput!] "Marker to use to get results from" marker: String ): EventsFeedData @ga eventsTimeSeries( "Account ID" accountID: ID! timeFrame: TimeFrame! measures: [EventsMeasure] dimensions: [EventsDimension] filters: [EventsFilter!] ): EventsTimeSeries @ga """Fetch group configuration for your account""" groups(accountId: ID!): GroupsQueries hardware(accountId: ID!): HardwareQueries """Retrieve the account hardware inventory""" hardwareManagement(accountId: ID!): HardwareManagementQueries """Retrieve the account(s) license inventory and license consumption""" licensing(accountId: ID!): LicensingQueries policy(accountId: ID!): PolicyQueries popLocations(accountId: ID!): PopLocationQueries sandbox(accountId: ID!): SandboxQueries @rollout servicePrincipalAdmin(accountId: ID!, adminID: ID!): GetServicePrincipalAdminPayload @ga site(accountId: ID!): SiteQueries! """ Provides historical metrics for physical and logical interfaces on Cato Sockets. This API enables detailed monitoring of LAN, WAN, Tunnel, Bypass, and Off-Cloud traffic, including throughput, bandwidth usage, and cellular signal quality. """ socketPortMetrics( "Account ID" accountID: ID! timeFrame: TimeFrame! measures: [SocketPortMetricsMeasure] dimensions: [SocketPortMetricsDimension] filters: [SocketPortMetricsFilter!] postAggFilters: [SocketPortMetricsPostAggFilter!] sort: [SocketPortMetricsSort!] ): SocketPortMetrics @ga """ Provides historical time series metrics for physical and logical interfaces on Cato Sockets. This API enables detailed monitoring of LAN, WAN, Tunnel, Bypass, and Off-Cloud traffic, including throughput, bandwidth usage, and cellular signal quality. """ socketPortMetricsTimeSeries( "Account ID" accountID: ID! timeFrame: TimeFrame! measures: [SocketPortMetricsMeasure] dimensions: [SocketPortMetricsDimension] filters: [SocketPortMetricsFilter!] ): SocketPortMetricsTimeSeries @ga """ The subdomain query helps you retrieve the URL of an account. The usage of this query supports 3 different scenarios: 1. Regular account - Return only 1 subdomain relating to the regular account 2. Reseller account - Return all subdomains including the reseller account subdomain 3. Reseller account - Return only the reseller account subdomain """ subDomains( """Unique Identifier of Account""" accountID: ID! """ When the boolean argument managedAccount is set to true (default), then the query returns all subdomains related to the account """ managedAccount: Boolean ): [SubDomain!]! @ga xdr(accountID: ID!): XDR! } type Mutation { accountManagement(accountId: ID!): AccountManagementMutations admin(accountId: ID!): AdminMutations! container(accountId: ID!): ContainerMutations enterpriseDirectory(accountId: ID!): EnterpriseDirectoryMutations @ea """Mutations for creating, updating, or deleting groups""" groups(accountId: ID!): GroupsMutations hardware(accountId: ID!): HardwareMutations licensing(accountId: ID!): LicensingMutations policy(accountId: ID!): PolicyMutations sandbox(accountId: ID!): SandboxMutations @rollout site(accountId: ID!): SiteMutations! sites(accountId: ID!): SiteMutations! @deprecated(reason: "in favor of site") xdr(accountId: ID!): XdrMutations! } """ The `MicrosoftEndpoint` object represents a comprehensive data structure used in GraphQL queries or mutations, containing fields related to security alerts, device details, threat predictions, and other metadata associated with Microsoft's security ecosystem. """ type MicrosoftEndpoint implements Endpoint & MergedIncident { alerts: [MicrosoftDefenderEndpointAlert!]! analystFeedback: AnalystFeedback categories: [IncidentCategory!]! connectionType: ConnectionTypeEnum criticality: Int description: String device: MicrosoftDeviceDetails engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! firstSignal: DateTime! id: ID! indication: String! lastSignal: DateTime! predictedThreatType: String predictedVerdict: StoryVerdictEnum producer: StoryProducerEnum! producerName: String! queryName: String research: Boolean similarStoriesData: [SimilarStoryData!]! site: SiteRef siteName: String source: String sourceIp: String status: StoryStatusEnum storyDuration: Int tags: [String!]! ticket: String user: UserRef vendor: VendorEnum } """ The `MicrosoftDeviceDetails` object represents detailed information about a Microsoft device, including its antivirus status, Azure AD device ID, device name, first seen date and time, health status, IP interfaces, logged-on users, onboarding status, operating system details, and RBAC group. """ type MicrosoftDeviceDetails implements DeviceDetails { avStatus: DeviceAvStatusEnum azureAdDeviceId: String deviceName: String externalIp: String firstSeenDateTime: DateTime healthStatus: DeviceHealthStatusEnum id: ID! ipInterfaces: [String!]! localIp: String loggedOnUsers: [EndpointUser!]! onboardingStatus: OnboardingStatusEnum osDetails: OsDetails rbacGroup: RbacGroup } enum OnboardingStatusEnum { CAN_BE_ONBOARDED INSUFFICIENT_INFO ONBOARDED } """ The `MicrosoftEndpointUser` object represents a user associated with a Microsoft endpoint, containing fields such as account name, domain name, unique identifier, user name, principal name, and user security identifier. """ type MicrosoftEndpointUser implements EndpointUser { accountName: String domainName: String id: ID! name: String! principalName: String userSid: String } """ The `MicrosoftDefenderEndpointAlert` object represents an alert generated by Microsoft Defender for Endpoint, containing details such as activities, classification, criticality, detection source, and recommended actions, among other attributes, to help in identifying and managing security threats. """ type MicrosoftDefenderEndpointAlert implements EndpointAlert { activities: [MicrosoftActivity!]! alertWebUrl: String category: String classification: AlertClassificationEnum comments: [String!]! createdDateTime: DateTime criticality: Int description: String destinationIp: String destinationUrl: String detectionSource: DetectionSourceEnum determination: AlertDeterminationEnum externalIp: String firstActivityDateTime: DateTime id: ID! lastActivityDateTime: DateTime lastUpdateDateTime: DateTime localIp: String mitreSubTechnique: [Mitre!]! mitreTechnique: [Mitre!]! ownerName: String providerAlertId: String recommendedActions: String resolvedDateTime: DateTime resources: [MicrosoftEndpointResource!]! status: MsAlertStatus threatFamilyName: String threatName: String threatType: String title: String } interface MicrosoftEndpointResource implements EndpointResource { id: ID! createdDateTime: DateTime remediationStatus: RemediationStatusEnum remediationStatusDetails: String tags: [String!]! roles: [ResourceRoleEnum!]! verdict: MsResourceVerdictEnum } """ The `MicrosoftProcessResource` object represents a process resource in a Microsoft environment, containing fields such as creation date, process ID, command line details, remediation status, roles, tags, user account information, and a verdict on the process's nature. """ type MicrosoftProcessResource implements ProcessResource & MicrosoftEndpointResource & EndpointResource { action: String createdDateTime: DateTime id: ID! imageFile: FileDetails processCommandLine: String processId: Int! remediationStatus: RemediationStatusEnum remediationStatusDetails: String roles: [ResourceRoleEnum!]! tags: [String!]! userAccount: EndpointUser verdict: MsResourceVerdictEnum } """ The `MicrosoftFileResource` object represents a file resource in a Microsoft system, containing fields such as creation date, detection and remediation status, file details, unique identifier, roles, tags, and a verdict on the file's status. """ type MicrosoftFileResource implements FileResource & MicrosoftEndpointResource & EndpointResource { createdDateTime: DateTime detectionStatus: DetectionStatusEnum fileDetails: FileDetails id: ID! remediationStatus: RemediationStatusEnum remediationStatusDetails: String roles: [ResourceRoleEnum!]! tags: [String!]! verdict: MsResourceVerdictEnum } """ The `MicrosoftRegistryResource` object represents a registry resource in a Microsoft environment, containing fields such as creation date, hive, key, remediation status, roles, tags, and verdict, which are used to manage and assess the resource's status and attributes. """ type MicrosoftRegistryResource implements RegistryResource & MicrosoftEndpointResource & EndpointResource { createdDateTime: DateTime hive: String id: ID! key: String remediationStatus: RemediationStatusEnum remediationStatusDetails: String roles: [ResourceRoleEnum!]! tags: [String!]! value: String valueName: String valueType: String verdict: MsResourceVerdictEnum } """ The `MicrosoftNetworkResource` object represents a registry resource in a Microsoft environment, containing fields such as creation date, remediation status, roles, tags, and verdict, which are used to manage and assess the resource's status and attributes. """ type MicrosoftNetworkResource implements MicrosoftEndpointResource & NetworkResource & EndpointResource { action: String createdDateTime: DateTime destinationIp: String destinationPort: Int dnsRequest: String dnsResponse: String id: ID! method: String remediationStatus: RemediationStatusEnum remediationStatusDetails: String roles: [ResourceRoleEnum!]! sourcePort: Int tags: [String!]! url: String verdict: MsResourceVerdictEnum } """ The `MicrosoftActivity` object represents an activity within Microsoft services, containing fields such as action type, timestamps for the first and last activity, and identifiers for the activity and its associated resources. """ type MicrosoftActivity implements Activity { action: String firstActivityDateTime: DateTime id: ID! lastActivityDateTime: DateTime parentResourceId: ID! resourceId: ID! } type RbacGroup { id: ID! name: String } enum MsAlertStatus { IN_PROGRESS NEW RESOLVED } enum DetectionSourceEnum { ANTIVIRUS APP_GOVERNANCE_DETECTION APP_GOVERNANCE_POLICY AUTOMATED_INVESTIGATION AZURE_AD_IDENTITY_PROTECTION CLOUD_APP_SECURITY CUSTOM_DETECTION CUSTOM_TI MANUAL MICROSOFT_DATA_LOSS_PREVENTION MICROSOFT_DEFENDER_FOR_ENDPOINT MICROSOFT_DEFENDER_FOR_IDENTITY MICROSOFT_DEFENDER_FOR_OFFICE365 MICROSOFT_THREAT_EXPERTS MICROSOFT365_DEFENDER SMART_SCREEN } enum AlertClassificationEnum { FALSE_POSITIVE INFORMATIONAL_EXPECTED_ACTIVITY TRUE_POSITIVE } enum AlertDeterminationEnum { APT COMPROMISED_ACCOUNT CONFIRMED_ACTIVITY LINE_OF_BUSINESS_APPLICATION MALICIOUS_USER_ACTIVITY MALWARE MULTI_STAGED_ATTACK NOT_ENOUGH_DATA_TO_VALIDATE NOT_MALICIOUS OTHER PHISHING SECURITY_PERSONNEL SECURITY_TESTING UNWANTED_SOFTWARE } enum MsResourceVerdictEnum { Benign Informational Malicious Suspicious } type XDR { """ Define the paging, sort, and filter arguments to define the XDR stories that are returned in the query """ stories(input: StoryInput!): StoriesData @beta """ Define either the story ID, or the incident ID and producer arguments, to query the specific XDR story """ story(storyId: ID, producer: StoryProducerEnum, incidentId: ID): Story @beta } type XdrMutations { """Post comments that help track the story investigation""" addStoryComment(input: AddStoryCommentInput!): AddStoryCommentPayload @beta """ Manage Story Actions, such as the story Verdict, Type, and Classification. You can also enter Additional Info that is relevant to the story. """ analystFeedback(input: AnalystFeedbackInput!): AnalystFeedbackPayload @beta """Delete a previously posted comment using the comment ID.""" deleteStoryComment(input: DeleteStoryCommentInput!): DeleteStoryCommentPayload @beta } type AnalystFeedbackPayload { """ Data related to the actions and information that an analyst adds to the XDR story """ story: Story } type AddStoryCommentPayload { """Add a new comment to the XDR story""" comment: StoryComment! } type DeleteStoryCommentPayload { """Delete an existing comment from an XDR story""" comment: StoryComment! } input AddStoryCommentInput { """The relevant Story""" storyId: ID! """Enter the text for the XDR story comment""" text: String! } input DeleteStoryCommentInput { """The comment ID""" commentId: ID! """The relevant Story""" storyId: ID! } type ThreatClassificationRef implements ObjectRef { id: ID! name: String! } type ThreatTypeRef implements ObjectRef { id: ID! name: String! } type AllowlistRuleRef implements ObjectRef { id: ID! name: String! } type ResponsePolicyRuleRef implements ObjectRef { id: ID! name: String! } input AnalystFeedbackInput { """ Free text for the analyst to enter additional information about the XDR story """ additionalInfo: String """Enum for analyst to assign the severity of a Malicious XDR story""" severity: SeverityEnum """Enum for the current status of the XDR story.""" status: StoryStatusEnum """The relevant Story""" storyId: ID! """ More detailed description of the type of threat. For example, the Anonymizer threatType can be assigned the Bitorrent Client threatClassification. """ threatClassification: String """Type of threat for the XDR story that is assigned by the analyst""" threatType: StoryThreatType """Enum for analyst to assign the verdict of the XDR story""" verdict: StoryVerdictEnum } input StoryThreatType { details: String name: String! recommendedAction: String } enum StoryVerdictEnum { Benign Informational Malicious Suspicious } enum TargetType { domain fqdn ip url } input StoryInput { filter: [StoryFilterInput!]! paging: PagingInput! sort: [StorySortInput!] } input StorySortInput { fieldName: StorySortFieldName! order: SortDirectionEnum } enum StorySortFieldName { accountName createdAt criticality engineType firstSignal producer queryName riskScore severity source sourceIp status updatedAt } input StoryFilterInput { accountId: AccountIdPredicate criticality: IntPredicate engineType: EngineTypePredicate incidentId: StringPredicate ioa: StringPredicate muted: BooleanPredicate producer: StoryProducerPredicate queryName: StringPredicate severity: StorySeverityPredicate source: StringPredicate sourceIp: StringPredicate status: StoryStatusPredicate storyId: StoryIdPredicate timeFrame: TimeFramePredicate! vendor: VendorPredicate verdict: StoryVerdictPredicate } input StoryVerdictPredicate { in: [StoryVerdictEnum!] not_in: [StoryVerdictEnum!] } input TimeFramePredicate { time: TimeFrame! timeFrameModifier: TimeFrameModifier } enum TimeFrameModifier { AnalystUpdate StoryCreate StoryUpdate } input AccountIdPredicate { in: [ID!] not_in: [ID!] } input StoryIdPredicate { in: [ID!] not_in: [ID!] } input StorySeverityPredicate { in: [SeverityEnum!] not_in: [SeverityEnum!] } enum SeverityEnum { High Low Medium } input StoryProducerPredicate { in: [StoryProducerEnum!] not_in: [StoryProducerEnum!] } input StoryStatusPredicate { in: [StoryStatusEnum!] not_in: [StoryStatusEnum!] } input IntPredicate { eq: Int gt: Int gte: Int in: [Int!] lt: Int lte: Int not_in: [Int!] } input StringPredicate { contains: String in: [String] not_in: [String] } input BooleanPredicate { is: String! } input EngineTypePredicate { in: [StoryEngineTypeEnum!] not_in: [StoryEngineTypeEnum!] } input VendorPredicate { in: [VendorEnum!] not_in: [VendorEnum!] } enum SortDirectionEnum { asc desc } type StoriesData { """Fields returned from the Story query""" items: [Story!]! """ Define the stories that are returned, similar to a page of stories in the Cato Management Application """ paging: Paging! } type Paging { """ Based on the filter and sort parameters, the first story that is returned """ from: Int! """ Based on the filter and sort parameters, the number of stories returned after the from. For example, the argument {from: 10, limit: 10} returns stories 10-20. """ limit: Int! """Total number of stories returned""" total: Int! } type Story { """ID for your Cato account""" accountId: Int! """Name of the account in the Cato Management Application""" accountName: String """Email address of the analyst working on the story""" analystEmail: String """Name of analyst working on the story""" analystName: String """Timestamp when the story was created""" createdAt: DateTime! """Unique Cato ID for each story""" id: ID! """ Data related to the fields and incidents that were merged to create or update the story """ incident: MergedIncident! """ URL for the playbook in the Knowledge Base to help troubleshoot the story """ playbook: String """Summary of the story""" summary: String """Data for the story timeline""" timeline: [TimelineItem!]! """Timestamp when the story was most recently updated""" updatedAt: DateTime! } enum StoryStatusEnum { Closed Monitoring Open PendingAnalysis PendingMoreInfo Reopened } """For XDR stories, items that happened during the lifetime of the story""" type TimelineItem { """Additional information about this timeline item""" additionalInfo: String """Data about the analyst for this timeline item (ie. name, email)""" analystInfo: AnalystInfo """Icon for the timeline item""" category: TimelineItemCategoryEnum """ Brief summary of action related to the timeline item (ie. Story created, Status update to) """ context: String! """Timestamp the timeline item was created""" createdAt: DateTime! """Description of the timeline item""" description: String! @deprecated(reason: "use 'descriptions' instead") """Description of the timeline item""" descriptions: [String!]! """Type of threat assigned by the analyst""" type: TimelineTypeEnum! } type AnalystInfo { """Security analyst email address""" email: String """Security analyst name""" name: String } enum TimelineTypeEnum { Action Comment Diff } enum TimelineItemCategoryEnum { Error Information Warning } type StoryComment { actor: ActorRef! createdAt: Time! id: ID! text: String! } interface MergedIncident { """Unique Cato ID for each story""" id: ID! """Timestamp for the first incident signal related to this story""" firstSignal: DateTime! """ Timestamp for the last (most recent) incident signal related to this story """ lastSignal: DateTime! """XDR engine involved with the incident""" engineType: StoryEngineTypeEnum """Vendor that identified the incident, such as Cato or Microsoft""" vendor: VendorEnum """Producer (specific XDR engine and service) involved with the incident""" producer: StoryProducerEnum! """ Full name of the Producer (specific XDR engine and service) involved with the incident """ producerName: String! """Connection for the incident""" connectionType: ConnectionTypeEnum """ An indication is a set of actions and behaviors for the Network or Security incident. Each producer has different indications. """ indication: String! """Category for the indication ID related to the story""" queryName: String """ For Network stories - The potential impact of the issue on your network. Values are from 1 (low impact) to 10 (high impact) For Security stories - Cato's risk analysis of the story. Values are from 1 (low risk) to 10 (high risk) """ criticality: Int """ For Network stories - The site where the network issue is occurring For Security stories - IP address, name of device, or SDP user on your network involved in the story """ source: String """The ticket an analyst created for this story""" ticket: String """Status for the story""" status: StoryStatusEnum """ The value is TRUE when the story is currently being researched by Security Analysts """ research: Boolean """Site name related to the story""" siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") """ Amount of time since the story was opened (no value for closed stories) """ storyDuration: Int """For Security stories, description of the threat""" description: String """ The source IP address of the device in your network sending or receiving the flow """ sourceIp: String """Fields related to analysts research of the threat incident""" analystFeedback: AnalystFeedback """Cato ID and name for the site""" site: SiteRef """Cato ID and name for the user""" user: UserRef predictedVerdict: StoryVerdictEnum predictedThreatType: String categories: [IncidentCategory!]! entities: [IncidentEntity!]! tags: [String!]! } type AnalystFeedbackThreatType { details: String name: String recommendedAction: String } type AnalystFeedback { additionalInfo: String severity: SeverityEnum threatClassification: String threatType: AnalystFeedbackThreatType verdict: StoryVerdictEnum } interface Anomalies implements MergedIncident { id: ID! firstSignal: DateTime! lastSignal: DateTime! engineType: StoryEngineTypeEnum vendor: VendorEnum producer: StoryProducerEnum! producerName: String! connectionType: ConnectionTypeEnum indication: String! queryName: String source: String criticality: Int ticket: String status: StoryStatusEnum research: Boolean siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") storyDuration: Int description: String analystFeedback: AnalystFeedback site: SiteRef user: UserRef sourceIp: String similarStoriesData: [SimilarStoryData!]! predictedVerdict: StoryVerdictEnum predictedThreatType: String categories: [IncidentCategory!]! entities: [IncidentEntity!]! tags: [String!]! direction: String } """ The `AnomalyStats` object is a GraphQL type that represents statistical data related to anomalies, including fields such as analyst feedback, connection type, criticality, device information, and various metrics, along with associated metadata like timestamps, status, and predicted verdicts. """ type AnomalyStats implements Anomalies & MergedIncident { analystFeedback: AnalystFeedback breakdownField: String categories: [IncidentCategory!]! clientClass: [String!]! connectionType: ConnectionTypeEnum criticality: Int description: String deviceName: String direction: String drillDownFilter: [StoryDrillDownFilter!] engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! extra: [Extra!] firstSignal: DateTime! gaussian: Gaussian id: ID! indication: String! lastSignal: DateTime! logonName: String macAddress: String metric: Metric metricDetails: MetricDetails mitres: [Mitre!] os: String predictedThreatType: String predictedVerdict: StoryVerdictEnum producer: StoryProducerEnum! producerName: String! queryName: String research: Boolean rules: [String!] similarStoriesData: [SimilarStoryData!]! site: SiteRef siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") source: String sourceIp: String srcSiteId: String status: StoryStatusEnum storyDuration: Int subjectType: String tags: [String!]! targets: [IncidentTargetRep!]! ticket: String timeSeries: [IncidentTimeseries!] user: UserRef vendor: VendorEnum } """ The `AnomalyEvents` object represents a data structure used in GraphQL queries or mutations, containing fields related to security anomalies, such as analyst feedback, connection type, criticality, description, and various identifiers and metrics, to provide detailed information about potential security incidents. """ type AnomalyEvents implements Anomalies & MergedIncident { analystFeedback: AnalystFeedback breakdownField: String categories: [IncidentCategory!]! clientClass: [String!]! connectionType: ConnectionTypeEnum criticality: Int description: String deviceName: String direction: String drillDownFilter: [StoryDrillDownFilter!] engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! extra: [Extra!] firstSignal: DateTime! gaussian: Gaussian id: ID! indication: String! lastSignal: DateTime! logonName: String macAddress: String metric: Metric metricDetails: MetricDetails mitres: [Mitre!] os: String predictedThreatType: String predictedVerdict: StoryVerdictEnum producer: StoryProducerEnum! producerName: String! queryName: String research: Boolean rules: [String!] similarStoriesData: [SimilarStoryData!]! site: SiteRef siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") source: String sourceIp: String srcSiteId: String status: StoryStatusEnum storyDuration: Int subjectType: String tags: [String!]! targets: [IncidentTargetRep!]! ticket: String timeSeries: [IncidentTimeseries!] user: UserRef vendor: VendorEnum } type Metric { name: String! value: Float! } type Gaussian { avg: Float n: Float ss: Float std: Float z_score: Float } type Extra { name: String! type: String! value: String! } type MetricDetails { name: String! units: String! } """ The "Threat" object represents a comprehensive data structure used in GraphQL queries or mutations to encapsulate various attributes and metadata related to a threat incident, including details about the threat's origin, nature, risk assessment, and associated network traffic flows. """ type Threat implements MergedIncident { """Fields related to analysts research of the threat incident""" analystFeedback: AnalystFeedback categories: [IncidentCategory!]! """Client Class for the traffic flow""" clientClass: [String!]! """Connection for this incident""" connectionType: ConnectionTypeEnum """ Cato's risk analysis of the story. Values are from 1 (low risk) to 10 (high risk) """ criticality: Int """Description of the threat""" description: String """Name of the device""" deviceName: String """Traffic direction for the threat""" direction: String """XDR engine involved with the incident""" engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! """Data for the Cato event for this story""" events: [Event!] """Timestamp for the first incident signal related to this story""" firstSignal: DateTime! """Data about the traffic flow for the threat""" flows: [IncidentFlow!] """Cardinality of traffic flows for the threat""" flowsCardinality: Int """Unique Cato ID for this threat""" id: ID! """ An indication is a set of actions and behaviors for the Network or Security incident. Each producer has different indications. """ indication: String! """Timestamp for the first incident signal related to this story""" lastSignal: DateTime! """Username for the device""" logonName: String """MAC address of the device""" macAddress: String """Mitre data for the story (ie. ID, name)""" mitres: [Mitre!] """OS for device or host that is the threat target""" os: String """Predicted threat type for the story based on Cato algorithm""" predictedThreatType: String """Predicted verdict of the story based on Cato algorithm""" predictedVerdict: StoryVerdictEnum """Producer (specific XDR engine and service) involved with the incident""" producer: StoryProducerEnum! """ Full name of the Producer (specific XDR engine and service) involved with the incident """ producerName: String! """Category for the indication ID related to the story""" queryName: String """ The value is TRUE when the story is currently being researched by Security Analysts """ research: Boolean """The estimated risk level of the threat (ie. Malicious, High, Low)""" riskLevel: RiskLevelEnum """Data for stories that are similar""" similarStoriesData: [SimilarStoryData!]! """Cato ID and name for the site""" site: SiteRef """Site name related to the story""" siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") """ IP address, name of device, or SDP user on your network involved in the story """ source: String """ The source IP address of the device in your network sending or receiving the flow """ sourceIp: String """Cato ID for the site that is the source of the threat""" srcSiteId: String """Status of this story""" status: StoryStatusEnum """ Amount of time since the story was opened (no value for closed stories) """ storyDuration: Int tags: [String!]! """Data about the target of the threat""" targets: [IncidentTargetRep!]! """The ticket an analyst created for this story""" ticket: String """Timeseries data for the incident""" timeSeries: [IncidentTimeseries!] """Cato ID and name for the user""" user: UserRef """Vendor that identified the incident, such as Cato or Microsoft""" vendor: VendorEnum } """ The `ThreatPrevention` object is a GraphQL type that represents the details of a threat prevention incident, including fields such as analyst feedback, client class, connection type, criticality, description, device name, and various other attributes related to the incident's signals, events, and status. """ type ThreatPrevention implements MergedIncident { analystFeedback: AnalystFeedback categories: [IncidentCategory!]! clientClass: [String!]! connectionType: ConnectionTypeEnum criticality: Int description: String deviceName: String direction: String engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! events: [Event!] firstSignal: DateTime! flowsCardinality: Int id: ID! indication: String! lastSignal: DateTime! logonName: String macAddress: String mitres: [Mitre!] os: String predictedThreatType: String predictedVerdict: StoryVerdictEnum producer: StoryProducerEnum! producerName: String! queryName: String research: Boolean riskLevel: RiskLevelEnum similarStoriesData: [SimilarStoryData!]! site: SiteRef siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") source: String sourceIp: String srcSiteId: String status: StoryStatusEnum storyDuration: Int tags: [String!]! targets: [IncidentTargetRep!]! threatPreventionsEvents: [ThreatPreventionEvents!] ticket: String timeSeries: [IncidentTimeseries!] user: UserRef vendor: VendorEnum } type SimilarStoryData { indication: String similarityPercentage: Float storyId: String threatClassification: String threatTypeName: String verdict: String } type ThreatPreventionEvents { appName: String clientClass: String createdAt: DateTime destinationCountry: String destinationGeolocation: String destinationIp: String destinationPort: Int direction: String dnsResponseIP: String domain: String fileHash: String httpResponseCode: Int ja3: String method: String referrer: String smbFileName: String sourceGeolocation: String sourceIp: String sourcePort: Int target: String tunnelGeolocation: String url: String user: String userAgent: String } enum NetworkXDREventTypeEnum { DEGRADED INSIGHT RESOLVED } enum LinkConfigPrecedenceEnum { ACTIVE LAST_RESORT PASSIVE } enum LinkStatusEnum { ACTIVE PASSIVE } enum DeviceConfigHaRoleEnum { PRIMARY SECONDARY } enum DeviceHaRoleStateEnum { BACKUP MASTER } enum NetworkEventSourceEnum { BGP_SESSION DEVICE HOST ISP LINK POP SITE } enum LinkQualityIssueTypeEnum { CONGESTION DISTANCE JITTER PACKET_LOSS } enum TrafficDirectionEnum { DOWNSTREAM UPSTREAM } type BGPConnection { catoAsn: Asn16 catoIp: String connectionName: String peerAsn: Asn32 peerIp: String } type LinkQualityIssue { current: Int direction: TrafficDirectionEnum issueType: LinkQualityIssueTypeEnum threshold: Int } type NetworkTimelineEvent { acknowledged: Boolean bgpConnection: BGPConnection created: DateTime! description: String deviceConfigHaRole: DeviceConfigHaRoleEnum deviceHaRoleState: DeviceHaRoleStateEnum eventIds: [String!]! eventType: NetworkXDREventTypeEnum hostIp: String incidentId: String isp: String linkConfigBandwidth: String linkConfigPrecedence: LinkConfigPrecedenceEnum linkId: String linkName: String linkQualityIssue: LinkQualityIssue linkStatus: LinkStatusEnum muted: Boolean networkEventSource: NetworkEventSourceEnum pop: String ruleName: String socketSerialId: String tunnelResetCount: Int validated: DateTime! } enum IlmmOnboardingStatus { COMPLETE FAILED MISSING PENDING } type IspLoaFile { fileHash: String fileName: String uploadedAt: Time } type IlmmContact { email: String name: String phone: String } type IlmmLinkDetails { activeLicense: Boolean comments: String description: String ispLinkId: String linkId: String onboardingStatus: IlmmOnboardingStatus } type IlmmIspDetails { countryCode: String description: String ispAccountId: String loaFile: IspLoaFile name: String supportEmail: String supportPhone: String } type IlmmDetails { contacts: [IlmmContact!] ispDetails: IlmmIspDetails linkDetails: IlmmLinkDetails } """ The `NetworkXDRIncident` object represents a detailed incident report within a network, containing various fields such as incident ID, description, criticality, timeline events, and associated metadata like connection type, site information, and predicted threat type, used for analyzing and managing network security incidents. """ type NetworkXDRIncident implements MergedIncident { acknowledged: Boolean analystFeedback: AnalystFeedback bgpConnection: BGPConnection categories: [IncidentCategory!]! connectionType: ConnectionTypeEnum criticality: Int description: String deviceConfigHaRole: DeviceConfigHaRoleEnum engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! firstSignal: DateTime! hostIp: String id: ID! ilmmDetails: IlmmDetails indication: String! isp: String lastSignal: DateTime! licenseBandwidth: String licenseRegion: String linkConfigPrecedence: LinkConfigPrecedenceEnum linkId: String linkName: String muted: Boolean networkIncidentTimeline: [NetworkTimelineEvent!]! occurrences: Int pop: String predictedThreatType: String predictedVerdict: StoryVerdictEnum producer: StoryProducerEnum! producerName: String! queryName: String research: Boolean ruleName: String similarStoriesData: [SimilarStoryData!]! site: SiteRef siteConfigLocation: String siteConnectionType: String siteName: String! source: String sourceIp: String status: StoryStatusEnum storyDuration: Int storyType: String! tags: [String!]! ticket: String user: UserRef vendor: VendorEnum } type AiOperationsIncident implements MergedIncident { accountOperationIncident: AccountOperationsIncident analystFeedback: AnalystFeedback categories: [IncidentCategory!]! connectionType: ConnectionTypeEnum criticality: Int description: String engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! eventsGraphQuery: EventsGraphQuery firstSignal: DateTime! flowLastTime: DateTime! @deprecated(reason: "use 'lastSignal' instead") flowStartTime: DateTime! @deprecated(reason: "use 'firstSignal' instead") id: ID! indication: String! ioa: String! @deprecated(reason: "'ioa' is deprecated, use 'indication' instead") lastSignal: DateTime! occurrences: Int predictedThreatType: String predictedVerdict: StoryVerdictEnum producer: StoryProducerEnum! producerName: String! queryName: String research: Boolean riskScore: Int! @deprecated(reason: "'riskScore' is deprecated, use 'criticality' instead") similarStoriesData: [SimilarStoryData!]! site: SiteRef siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") source: String sourceIp: String status: StoryStatusEnum storyDuration: Int tags: [String!]! ticket: String type: AiOperationsIncidentTypeEnum user: UserRef vendor: VendorEnum } type EventsGraphQuery { timeSeriesEvents: TimeSeriesEvents type: GraphType! } enum GraphType { ANALYTICS } type TimeSeriesEvents { accountID: String! buckets: Int! dimensions: [GraphEventsDimension!]! filters: [GraphEventsFilter!]! measures: [GraphEventsMeasure!]! timeFrame: TimeFrame! } type GraphEventsMeasure { aggType: String! fieldName: String! trend: Boolean } type GraphEventsDimension { fieldName: String! } type GraphEventsFilter { fieldName: String! operator: String! values: [String!]! } type AccountOperationsIncident { incidentTimeline: [AccountOperationsTimelineBase!]! metadata: [AccountOperationsMetadata!]! playbooks: [AiOperationsPlaybook!]! } interface AccountOperationsTimelineBase { id: ID! created: Time! validated: Time! description: String! type: AccountOperationsTimelineType! } type AiOperationsPlaybook { description: String! link: String title: String! } type AccountOperationsTimelineEvent implements AccountOperationsTimelineBase { created: Time! description: String! eventIds: [String!]! id: ID! muted: Boolean! type: AccountOperationsTimelineType! validated: Time! } enum AccountOperationsTimelineType { Action Event } enum AiOperationsIncidentTypeEnum { Account } type AccountOperationsMetadata { key: String! type: MetadataType! value: String! } enum MetadataType { TXT } enum ScanResult { BYPASS_BY_CONTENT_RULE BYPASS_BY_OTHER BYPASS_BY_TYPE CANCELLED CLEAN ENCRYPTED VIRUS_FOUND } type Event { action: String appId: String appName: String dnsProtectionCategory: String eventType: String ruleId: String scanResult: ScanResult severity: String signatureId: String threatName: String threatType: String virusName: String } type Mitre { id: String name: String } type IncidentTargetRep { analysisScore: Float categories: String catoPopularity: Int countryOfRegistration: String creationTime: DateTime engines: Int eventData: [Event!]! infectionSource: Boolean name: String searchHits: String threatFeeds: Int threatReference: String type: TargetType } type IncidentFlow { appName: String clientClass: String createdAt: DateTime destinationCountry: String destinationGeolocation: String destinationIp: String destinationPort: Int direction: String dnsResponseIP: String domain: String fileHash: String httpResponseCode: Int ja3: String method: String referer: String smbFileName: String sourceGeolocation: String sourceIp: String sourcePort: Int target: String tunnelGeolocation: String url: String user: String userAgent: String } type StoryDrillDownFilter { name: String! value: String! @deprecated(reason: "No longer supported") values: [String!]! } enum RiskLevelEnum { Benign High Inconclusive Low Malicious Medium nan } enum StoryProducerEnum { AnomalyEvents AnomalyExperience AnomalyStats CatoEndpointAlert EntraIdAlert MicrosoftEndpointDefender NetworkMonitor @deprecated(reason: "No longer supported") """The producer of the Site Operations stories""" NetworkXDR ThreatHunt ThreatPrevention } enum StoryEngineTypeEnum { ANOMALY ENDPOINT IDENTITY NETWORK THREAT } enum VendorEnum { CATO MICROSOFT } enum ConnectionTypeEnum { Host Site User } type IncidentTimeseries { """ Data is an array of tuples, each containing two values: [timestamp, metric], where the timestamp is in milliseconds from the epoch (1.1.1970), and the metric is a number (according to the unit type) """ data( "whether to normalize the data into per second (i.e. divide by granularity)" perSecond: Boolean = true ): [[Float!]] """The parameter by which the timeseries data is grouped""" groupBy: String """ Specific information about the timeseries, used to build its name, title etc """ info: [String!] key: TimeseriesKey "Indicates the type of the timeseries" label: String! sum: Float """ Identifies what unit of data this timeseries represents. Note that toRate is only available for particular types of data to make sense. """ units: UnitType } enum IncidentCategory { OPERATIONAL OTHER SECURITY } type IncidentEntity { data: [IncidentEntityData!]! kind: String ref: ObjectRef! role: String type: String } type IncidentEntityData { fieldName: String! values: [String!]! } type DataQuery { buckets: Int dataSource: DataSourceEnum fields: [String!]! filters: [QueryParameter!]! measures: [MeasuresParameters!]! } enum DataSourceEnum { AppStats AppStatsTimeSeries ConnectivityStats ConnectivityStatsTimeSeries DeviceHardwareMetrics Events EventsList EventsTimeSeries HardwareMetricsTimeSeries LmmTimeSeries } type MeasuresParameters { aggType: String fieldName: String unitType: MeasuresUnitType } enum MeasuresUnitType { BITS_PER_SECOND COUNT MILLISECONDS PERCENTAGE } type QueryParameter { name: String operator: String value: String values: [String!]! } type UnknownEntityRef implements ObjectRef { id: ID! name: String! } type GenericIncident implements MergedIncident { """Fields related to analysts research of the threat incident""" analystFeedback: AnalystFeedback categories: [IncidentCategory!]! """Connection for the incident""" connectionType: ConnectionTypeEnum """ For Network stories - The potential impact of the issue on your network. Values are from 1 (low impact) to 10 (high impact) For Security stories - Cato's risk analysis of the story. Values are from 1 (low risk) to 10 (high risk) """ criticality: Int """For Security stories, description of the threat""" description: String """XDR engine involved with the incident""" engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! evidences: [GenericIncidentEvidence!]! """Timestamp for the first incident signal related to this story""" firstSignal: DateTime! """Unique Cato ID for each story""" id: ID! """ An indication is a set of actions and behaviors for the Network or Security incident. Each producer has different indications. """ indication: String! """ Timestamp for the last (most recent) incident signal related to this story """ lastSignal: DateTime! mitres: [Mitre!] predictedThreatType: String predictedVerdict: StoryVerdictEnum """Producer (specific XDR engine and service) involved with the incident""" producer: StoryProducerEnum! """ Full name of the Producer (specific XDR engine and service) involved with the incident """ producerName: String! queries: [DataQuery!]! """Category for the indication ID related to the story""" queryName: String """ The value is TRUE when the story is currently being researched by Security Analysts """ research: Boolean similarStoriesData: [SimilarStoryData!]! """Cato ID and name for the site""" site: SiteRef """Site name related to the story""" siteName: String @deprecated(reason: "'siteName' is deprecated, use 'site.name' instead") """ For Network stories - The site where the network issue is occurring For Security stories - IP address, name of device, or SDP user on your network involved in the story """ source: String """ The source IP address of the device in your network sending or receiving the flow """ sourceIp: String """Status for the story""" status: StoryStatusEnum statusInfo: GenericIncidentStatusInfo """ Amount of time since the story was opened (no value for closed stories) """ storyDuration: Int tags: [String!]! """The ticket an analyst created for this story""" ticket: String """Cato ID and name for the user""" user: UserRef """Vendor that identified the incident, such as Cato or Microsoft""" vendor: VendorEnum vendorInfo: GenericIncidentVendorInfo } type GenericIncidentVendorInfo { engineType: String incidentUrl: String name: String product: String status: String } type GenericIncidentStatusInfo { classification: String incidentStatus: String verdict: StoryVerdictEnum } type GenericIncidentEvidence { data: [GenericIncidentEvidenceData!]! type: GenericIncidentEvidenceType! value: String } type GenericIncidentEvidenceData { fieldName: String! values: [String!]! } enum GenericIncidentEvidenceType { CONFIG DOMAIN FILE HASH IP METRIC OTHER URL } interface Endpoint implements MergedIncident { """Unique Cato ID for the story""" id: ID! """Timestamp for the first incident signal related to this story""" firstSignal: DateTime! """ Timestamp for the last (most recent) incident signal related to this story """ lastSignal: DateTime! """XDR engine involved with the incident""" engineType: StoryEngineTypeEnum """Vendor that identified the incident, such as Cato or Microsoft""" vendor: VendorEnum """ Enum for the Producer (specific XDR engine and service) involved with the incident """ producer: StoryProducerEnum! """ Full name of the Producer (specific XDR engine and service) involved with the incident """ producerName: String! """Enum for the connection for this incident (ie. site, host, user)""" connectionType: ConnectionTypeEnum """ An indication is a set of actions and behaviors for the Network or Security incident. Each producer has different indications. """ indication: String! """Category for the indication ID related to the story""" queryName: String """ IP address, name of device, or SDP user on your network involved in the story """ source: String criticality: Int ticket: String status: StoryStatusEnum research: Boolean siteName: String storyDuration: Int description: String sourceIp: String analystFeedback: AnalystFeedback site: SiteRef user: UserRef similarStoriesData: [SimilarStoryData!]! predictedVerdict: StoryVerdictEnum predictedThreatType: String categories: [IncidentCategory!]! entities: [IncidentEntity!]! tags: [String!]! device: DeviceDetails alerts: [EndpointAlert!]! } interface EndpointAlert { id: ID! title: String description: String threatName: String mitreTechnique: [Mitre!]! mitreSubTechnique: [Mitre!]! createdDateTime: DateTime resources: [EndpointResource!]! activities: [Activity!]! criticality: Int externalIp: String localIp: String } interface Activity { id: ID! resourceId: ID! parentResourceId: ID! } interface DeviceDetails { id: ID! deviceName: String osDetails: OsDetails loggedOnUsers: [EndpointUser!]! externalIp: String localIp: String } type OsDetails { osBuild: Int osType: String! osVersion: String } interface EndpointUser { id: ID! name: String! } enum ResourceRoleEnum { ADDED ATTACKED ATTACKER COMMAND_AND_CONTROL COMPROMISED CONTEXTUAL CREATED DESTINATION EDITED LOADED POLICY_VIOLATOR SCANNED SOURCE SUSPICIOUS } enum RemediationStatusEnum { BLOCKED CLEAN DELETED DELETED_REBOOT DISABLED DISINFECT_FAILED DISINFECTED INFECTED MOVED MOVED_REBOOT NOT_FOUND NOT_STARTED PASSWORD_PROTECTED PREVENTED REBOOT_REQUIRED REMEDIATED SCAN_FAILED SUCCESS SUSPICIOUS UNKNOWN } enum DeviceHealthStatusEnum { ACTIVE IMPAIRED_COMMUNICATION INACTIVE NO_SENSOR_DATA NO_SENSOR_DATA_IMPAIRED_COMMUNICATION } enum DeviceAvStatusEnum { DISABLED NOT_REPORTING NOT_UPDATED UPDATED } interface EndpointResource { id: ID! createdDateTime: DateTime remediationStatus: RemediationStatusEnum } interface ProcessResource implements EndpointResource { id: ID! createdDateTime: DateTime remediationStatus: RemediationStatusEnum processId: Int! processCommandLine: String imageFile: FileDetails userAccount: EndpointUser } interface FileResource implements EndpointResource { id: ID! createdDateTime: DateTime remediationStatus: RemediationStatusEnum fileDetails: FileDetails detectionStatus: DetectionStatusEnum } interface RegistryResource implements EndpointResource { id: ID! createdDateTime: DateTime remediationStatus: RemediationStatusEnum hive: String key: String value: String valueName: String valueType: String } type FileDetails { issuer: String md5: String name: String path: String publisher: String sha1: String sha256: String signer: String size: Int } enum DetectionStatusEnum { BLOCKED DETECTED PREVENTED } interface NetworkResource implements EndpointResource { id: ID! createdDateTime: DateTime remediationStatus: RemediationStatusEnum dnsRequest: String dnsResponse: String destinationIp: String destinationPort: Int sourcePort: Int url: String method: String } """ The `CatoEndpoint` object represents a comprehensive data structure used in GraphQL queries or mutations to encapsulate details about a security incident detected by an Endpoint Protection Platform (EPP). It includes fields such as threat alerts, analyst feedback, connection type, criticality score, device details, timestamps for incident signals, and various enums and strings that describe the incident's status, source, and producer. """ type CatoEndpoint implements Endpoint & MergedIncident { """Details for the threat detected by the EPP""" alerts: [CatoEndpointAlert!]! """Fields related to analysts research of the threat incident""" analystFeedback: AnalystFeedback categories: [IncidentCategory!]! """enum for the connection for this incident (ie. host, user)""" connectionType: ConnectionTypeEnum """ Cato's risk analysis of the story. Values are from 1 (low risk) to 10 (high risk) """ criticality: Int """Description of the threat""" description: String """Details for the EPP device (ie. device name, OS, MAC address)""" device: CatoEndpointDeviceDetails """enum that shows XDR engine involved with the incident""" engineType: StoryEngineTypeEnum entities: [IncidentEntity!]! """Timestamp for the first incident signal related to this story""" firstSignal: DateTime! """ID for the Endpoint Protection story""" id: ID! """ An indication is a set of actions and behaviors for the Network or Security incident. Each producer has different indications. """ indication: String! """ Timestamp for the last (most recent) incident signal related to this story """ lastSignal: DateTime! predictedThreatType: String predictedVerdict: StoryVerdictEnum """ enum for the Producer (specific XDR engine or service) involved with the incident """ producer: StoryProducerEnum! """ Full name of the Producer (specific XDR engine and service) involved with the incident """ producerName: String! """""" queryName: String """ TRUE indicates that the story is currently being researched by Security Analysts """ research: Boolean similarStoriesData: [SimilarStoryData!]! """Cato ID and name for the site""" site: SiteRef """Site name related to the story""" siteName: String """ IP address, name of device, or SDP user on your network involved in the story """ source: String """ Source IP address of the device in your network sending or receiving the flow """ sourceIp: String """Enum for the status of this story (ie. Open, Closed, Monitoring)""" status: StoryStatusEnum """ Amount of time since the story was opened (no value for closed stories) """ storyDuration: Int tags: [String!]! """The ticket for this story""" ticket: String """Cato ID and name for the site""" user: UserRef """Vendor that identified the incident, such as Cato or Microsoft""" vendor: VendorEnum } enum CatoEndpointEngineType { AntiMalware Behavioral } """ The `CatoEndpointDeviceDetails` object represents detailed information about a device, including its name, unique ID, logged-on users, MAC address, and operating system details. """ type CatoEndpointDeviceDetails implements DeviceDetails { """Name of the device""" deviceName: String externalIp: String """Unique Cato ID for this story""" id: ID! localIp: String """Data for one or more users logged in to the device""" loggedOnUsers: [EndpointUser!]! """MAC address of the device""" macAddress: String """OS data (ie. type, build, version)""" osDetails: OsDetails } """ The `CatoEndpointUser` is a GraphQL object type representing a user, with fields for a unique identifier (`id`) and a username (`name`), both of which are required. """ type CatoEndpointUser implements EndpointUser { """ID for the user""" id: ID! """Username for the user whose activity generated the indication""" name: String! } """ The `CatoEndpointAlert` object represents an alert generated by Cato's endpoint protection system, detailing information about detected threats, including associated activities, threat description, criticality level, endpoint protection profile, and remediation status. """ type CatoEndpointAlert implements EndpointAlert { """Unique Cato IDs for the activities related to the alert""" activities: [CatoActivity!]! """Timestamp that the threat was detected and the alert generated""" createdDateTime: DateTime """ Cato's risk analysis of the story. Values are from 1 (low risk) to 10 (high risk) """ criticality: Int """Description of the threat""" description: String """EPP profile that is assigned to this device""" endpointProtectionProfile: String """Enum for the EPP engine related to this story""" engineType: CatoEndpointEngineType externalIp: String """Unique Cato ID for the Endpoint Protection story""" id: ID! localIp: String """MITRE ATT&CK® sub-technique for the threat""" mitreSubTechnique: [Mitre!]! """MITRE ATT&CK® technique for the threat""" mitreTechnique: [Mitre!]! """Data for the remediation status of the alert""" resources: [CatoResource!]! """Enum for the remediation status of the EPP alert""" status: RemediationStatusEnum """Name of threat detected on the device""" threatName: String """Title of the endpoint alert""" title: String } interface CatoResource implements EndpointResource { """Unique Cato ID for this EPP resource""" id: ID! """Timestamp that the this resource was used""" createdDateTime: DateTime """Enum for the remediation status associated with this resource""" remediationStatus: RemediationStatusEnum } """ The `CatoProcessResource` is a GraphQL object type that represents a process resource, including details such as a unique Cato ID, the timestamp of usage, associated file details, command line information, process ID, remediation status, and the related user account. """ type CatoProcessResource implements ProcessResource & CatoResource & EndpointResource { """Timestamp that the this resource was used""" createdDateTime: DateTime """Unique Cato ID for this resource""" id: ID! """Details of the file related to this process""" imageFile: FileDetails """CLI command related to this process""" processCommandLine: String """ID for the process""" processId: Int! """Enum for the remediation status associated with this resource""" remediationStatus: RemediationStatusEnum """User account related to this process""" userAccount: EndpointUser } """ The `CatoFileResource` is a GraphQL object type that represents a file resource with fields for its creation timestamp, detection and remediation statuses, file details, and a unique identifier. """ type CatoFileResource implements FileResource & CatoResource & EndpointResource { """Timestamp that the this file resource was used""" createdDateTime: DateTime """Enum for the detection status of this file resource""" detectionStatus: DetectionStatusEnum """Details of the file related to this resource""" fileDetails: FileDetails """Unique Cato ID for this file resource""" id: ID! """Enum for the remediation status associated with this file resource""" remediationStatus: RemediationStatusEnum } """ CatoActivity is an object type representing an activity in a Cato alert, containing unique identifiers for the activity itself, the preceding resource, and the involved resource. """ type CatoActivity implements Activity { """Unique Cato ID for this activity""" id: ID! """ Unique Cato ID for the preceding resource (process or file) in the alert """ parentResourceId: ID! """ Unique Cato ID for the resource (process or file) involved in the alert """ resourceId: ID! } type SiteMutations { """Adds a new BGP peer to the specified site.""" addBgpPeer(input: AddBgpPeerInput!): AddBgpPeerPayload @beta """ Add a new physical connection to a cloud interconnect site.Either connect to a partner, or a non-supported public provider """ addCloudInterconnectPhysicalConnection(input: AddCloudInterconnectPhysicalConnectionInput!): AddCloudInterconnectPhysicalConnectionPayload @beta """Add a new cloud interconnect site.""" addCloudInterconnectSite(input: AddCloudInterconnectSiteInput!): AddCloudInterconnectSitePayload @beta addIpsecIkeV2Site(input: AddIpsecIkeV2SiteInput!): AddIpsecIkeV2SitePayload @beta addIpsecIkeV2SiteTunnels(siteId: ID!, input: AddIpsecIkeV2SiteTunnelsInput!): AddIpsecIkeV2SiteTunnelsPayload @beta addNetworkRange(lanSocketInterfaceId: ID!, input: AddNetworkRangeInput!): AddNetworkRangePayload @ga """Add a secondary AWS vSocket to an existing site""" addSecondaryAwsVSocket(input: AddSecondaryAwsVSocketInput!): AddSecondaryAwsVSocketPayload @beta """Add a secondary Azure vSocket to an existing site""" addSecondaryAzureVSocket(input: AddSecondaryAzureVSocketInput!): AddSecondaryAzureVSocketPayload @beta addSocketAddOnCard(input: AddSocketAddOnCardInput!): AddSocketAddOnCardPayload @rollout @beta addSocketSite(input: AddSocketSiteInput!): AddSocketSitePayload @ga addStaticHost(siteId: ID!, input: AddStaticHostInput!): AddStaticHostPayload @ga """ Assign a license to an existing site // License-to-site assignment will be removed starting in 2026 with the transition to a new pricing model. """ assignSiteBwLicense(input: AssignSiteBwLicenseInput!): AssignSiteBwLicensePayload @beta """Removes an existing BGP peer configuration from a site.""" removeBgpPeer(input: RemoveBgpPeerInput!): RemoveBgpPeerPayload @beta """Remove a physical connection from a cloud interconnect site.""" removeCloudInterconnectPhysicalConnection(input: RemoveCloudInterconnectPhysicalConnectionInput!): RemoveCloudInterconnectPhysicalConnectionPayload @beta removeIpsecIkeV2SiteTunnels(siteId: ID!, input: RemoveIpsecIkeV2SiteTunnelsInput!): RemoveIpsecIkeV2SiteTunnelsPayload @beta removeNetworkRange(networkRangeId: ID!): RemoveNetworkRangePayload @ga """Remove the secondary AWS vSocket from an existing site""" removeSecondaryAwsVSocket(socketId: ID!): RemoveSecondaryAwsVSocketPayload @beta """Remove the secondary Azure vSocket from an existing site""" removeSecondaryAzureVSocket(socketId: ID!): RemoveSecondaryAzureVSocketPayload @beta removeSite(siteId: ID!): RemoveSitePayload @ga """ Remove a license from a site // License-to-site assignment will be removed starting in 2026 with the transition to a new pricing model. """ removeSiteBwLicense(input: RemoveSiteBwLicenseInput!): RemoveSiteBwLicensePayload @beta removeSocketAddOnCard(input: RemoveSocketAddOnCardInput!): RemoveSocketAddOnCardPayload @beta removeStaticHost(hostId: ID!): RemoveStaticHostPayload @ga """ Replace an existing license of a site. This API is used to make sure the site will always have a license to avoid traffic drop for sites without licenses. // License-to-site assignment will be removed starting in 2026 with the transition to a new pricing model. """ replaceSiteBwLicense(input: ReplaceSiteBwLicenseInput!): ReplaceSiteBwLicensePayload @beta """ Requests an upgrade for multiple sites to specific versions. Returns the result of the request. """ startSiteUpgrade(input: StartSiteUpgradeInput!): StartSiteUpgradePayload @rollout @beta """Updates an existing BGP peer configuration.""" updateBgpPeer(input: UpdateBgpPeerInput!): UpdateBgpPeerPayload @beta """Update an existing physical connection at a cloud interconnect site.""" updateCloudInterconnectPhysicalConnection(input: UpdateCloudInterconnectPhysicalConnectionInput!): UpdateCloudInterconnectPhysicalConnectionPayload @beta updateHa(siteId: ID!, input: UpdateHaInput!): UpdateHaPayload @ga updateIpsecIkeV2SiteGeneralDetails(siteId: ID!, input: UpdateIpsecIkeV2SiteGeneralDetailsInput!): UpdateIpsecIkeV2SiteGeneralDetailsPayload @beta updateIpsecIkeV2SiteTunnels(siteId: ID!, input: UpdateIpsecIkeV2SiteTunnelsInput!): UpdateIpsecIkeV2SiteTunnelsPayload @beta updateNetworkRange(networkRangeId: ID!, input: UpdateNetworkRangeInput!): UpdateNetworkRangePayload @ga """Update the secondary AWS vSocket from in an existing site""" updateSecondaryAwsVSocket(input: UpdateSecondaryAwsVSocketInput!): UpdateSecondaryAwsVSocketPayload @beta """Update the secondary Azure vSocket in an existing site""" updateSecondaryAzureVSocket(input: UpdateSecondaryAzureVSocketInput!): UpdateSecondaryAzureVSocketPayload @beta """ Update the bandwidth allocation of an assigned pool license of an existing site (does not apply for site license allocation) // License-to-site assignment will be removed starting in 2026 with the transition to a new pricing model. """ updateSiteBwLicense(input: UpdateSiteBwLicenseInput!): UpdateSiteBwLicensePayload @beta updateSiteGeneralDetails(siteId: ID!, input: UpdateSiteGeneralDetailsInput!): UpdateSiteGeneralDetailsPayload @ga updateSocketInterface(siteId: ID!, socketInterfaceId: SocketInterfaceIDEnum!, input: UpdateSocketInterfaceInput!): UpdateSocketInterfacePayload @ga updateStaticHost(hostId: ID!, input: UpdateStaticHostInput!): UpdateStaticHostPayload @ga } type SiteQueries { """Retrieves available socket versions for the specified platforms.""" availableVersionList(input: AvailableVersionListInput!): AvailableVersionListPayload @rollout @beta """Retrieves details of a specific BGP peer by reference.""" bgpPeer(input: BgpPeerRefInput!): BgpPeer @beta """Retrieves a list of all BGP peers associated with the specified site.""" bgpPeerList(input: BgpPeerListInput!): BgpPeerListPayload @beta """ Check the L2 connectivity status of a cloud interconnect connection using ICMP. """ cloudInterconnectConnectionConnectivity(input: CloudInterconnectConnectionConnectivityInput!): CloudInterconnectConnectionConnectivity @beta """Get details of a physical connection at a cloud interconnect site.""" cloudInterconnectPhysicalConnection(input: CloudInterconnectPhysicalConnectionInput!): CloudInterconnectPhysicalConnection @beta """Get the ID of a physical connection at a cloud interconnect site.""" cloudInterconnectPhysicalConnectionId(input: CloudInterconnectPhysicalConnectionIdInput!): CloudInterconnectPhysicalConnectionId @beta """Retrieves details of a specific secondary AWS vSocket.""" secondaryAwsVSocket(socketId: ID!): SecondaryAwsVSocket @beta """Retrieves details of a specific secondary Azure vSocket.""" secondaryAzureVSocket(socketId: ID!): SecondaryAzureVSocket @beta """ Provides the BGP status of the specified site, including session and route details. """ siteBgpStatus(input: SiteBgpStatusInput!): SiteBgpStatus @beta siteGeneralDetails(site: SiteRefInput!): SiteGeneralDetailsPayload @beta } input AddSecondaryAwsVSocketInput { """The IP address of LAN interface""" eniIpAddress: IPAddress! """The subnet of the LAN interface""" eniIpSubnet: NetworkSubnet! """The ID of the LAN route table""" routeTableId: String! """ Information about the site where the secondary AWS VSocket is being added. """ site: SiteRefInput! } input AddSecondaryAzureVSocketInput { """The floating IP address""" floatingIp: IPAddress! """The IP address of the interface""" interfaceIp: IPAddress! """ Information about the site where the secondary Azure VSocket is being added. """ site: SiteRefInput! } type AddSecondaryAwsVSocketPayload { """The secondary socket id""" id: ID! } type AddSecondaryAzureVSocketPayload { """The secondary socket id""" id: ID! } type RemoveSecondaryAwsVSocketPayload { secondaryAwsVSocket: SecondaryAwsVSocket! } type RemoveSecondaryAzureVSocketPayload { secondaryAzureVSocket: SecondaryAzureVSocket! } type SecondaryAzureVSocket { """The floating IP address""" floatingIp: IPAddress! """The ID of the secondary vSocket""" id: ID! """The IP address of the interface""" interfaceIp: IPAddress! """ Information about the site where the secondary Azure vSocket is being added. """ site: SiteRef! } type SecondaryAwsVSocket { """The ID of the secondary vSocket""" id: ID! """The IP address of the secondary vSocket""" ipAddress: IPAddress! """The ID of the secondary vSocket route table""" routeTableId: String! """Site associated with this secondary vSocket.""" site: SiteRef! """The subnet of the secondary vSocket""" subnet: NetworkSubnet! } input UpdateSecondaryAzureVSocketInput { """The floating IP address""" floatingIp: IPAddress """The ID of the secondary vSocket""" id: ID! """The IP address of the interface""" interfaceIp: IPAddress } type UpdateSecondaryAzureVSocketPayload { """The updated secondary Azure vSocket object.""" secondaryAzureVSocket: SecondaryAzureVSocket! } input UpdateSecondaryAwsVSocketInput { """The ID of the secondary vSocket""" id: ID! """The IP address of the secondary vSocket""" ipAddress: IPAddress """The ID of the secondary vSocket route table""" routeTableId: String """The subnet of the secondary vSocket""" subnet: NetworkSubnet } type UpdateSecondaryAwsVSocketPayload { """The updated secondary AWS vSocket object.""" secondaryAwsVSocket: SecondaryAwsVSocket! } enum SocketPortMetricsFieldName { "Unique identifier of the account that owns the site." account_id "Total bytes received downstream (from the network to the device)." bytes_downstream "Combined total of upstream and downstream bytes." bytes_total "Total bytes sent upstream (from the device to the network)." bytes_upstream "Reference Signal Received Power – measures LTE/5G signal strength (dBm)." cellular_rsrp "Reference Signal Received Quality – a key LTE/5G metric for link quality (dB)." cellular_rsrq "Received Signal Strength Indicator – legacy strength metric (dBm)." cellular_rssi "Generic signal strength indicator (often maps to bars or percentage)." cellular_signal_strength "Signal to Interference + Noise Ratio – LTE/5G metric for signal clarity (dB)." cellular_sinr "Unique identifier of the Socket (Cato edge device)." device_id "Indicates the high-availability (HA) role of the device (e.g., active, standby)." ha_role "Type of physical interface (e.g., ethernet, cellular)." physical_interface_type "SIM card number (for cellular interfaces)." sim_num "Unique identifier of the site where the socket is deployed." site_id "Human-readable name of the site." site_name "The name or ID of the physical or logical interface on the Socket device (e.g., eth0, cell1)." socket_interface "Describes the interface role such as primary, backup, cellular, or none." socket_interface_role "Current download throughput in Mbps." throughput_downstream "Current upload throughput in Mbps." throughput_upstream "Type of transport used by the interface (e.g., wired, lte, 5g, wifi)." transport_type } type SocketPortMetrics { from: DateTime id: ID records(limit: Int, from: Int): [SocketPortMetricsRecord!] to: DateTime total: Int totals: Map } type SocketPortMetricsRecord { fields: [SocketPortMetricsField!] "fields in map format (see Map scalar)" fieldsMap: Map fieldsUnitTypes: [UnitType!] prevTimeFrame: Map trends: Map } type SocketPortMetricsTimeSeries { from: DateTime granularity: Int id: ID timeseries(buckets: Int!): [Timeseries!] to: DateTime } type SocketPortMetricsField { name: SocketPortMetricsFieldName! value: Value! } input SocketPortMetricsMeasure { aggType: AggregationType! fieldName: SocketPortMetricsFieldName! trend: Boolean } input SocketPortMetricsDimension { fieldName: SocketPortMetricsFieldName! } input SocketPortMetricsFilter { fieldName: SocketPortMetricsFieldName! operator: FilterOperator! values: [String!]! } input SocketPortMetricsPostAggFilter { aggType: AggregationType! filter: SocketPortMetricsFilter! } input SocketPortMetricsSort { fieldName: SocketPortMetricsFieldName! order: DirectionEnum! } input AddSocketSiteInput { """""" connectionType: SiteConnectionTypeEnum! = SOCKET_X1500 description: String """The name of the site""" name: String! """The native range of the site""" nativeNetworkRange: IPSubnet! """The location of the site""" siteLocation: AddSiteLocationInput! """Valid values are: BRANCH, HEADQUARTERS, CLOUD_DC, and DATACENTER.""" siteType: SiteType! = BRANCH translatedSubnet: IPSubnet """VLAN ID for native range""" vlan: Vlan } input AddSiteLocationInput { """optional address""" address: String """city name, must belong to the country or country and state""" city: String """country code""" countryCode: String! """optional state code""" stateCode: String """time zone""" timezone: String! } input UpdateSocketInterfaceInput { """Only relevant for ALTERNATIVE, LAYER_2_WAN""" altWan: SocketInterfaceAltWanInput """Only relevant for CATO, ALTERNATIVE, LAYER_2_WAN""" bandwidth: SocketInterfaceBandwidthInput destType: SocketInterfaceDestType! """Only relevant for LAN_LAG_MASTER, LAN_LAG_MASTER_AND_VRRP""" lag: SocketInterfaceLagInput """ Only relevant for LAN, VRRP_AND_LAN, LAN_LAG_MASTER, LAN_LAG_MASTER_AND_VRRP """ lan: SocketInterfaceLanInput name: String """Only relevant for CATO""" offCloud: SocketInterfaceOffCloudInput """Only relevant for VRRP""" vrrp: SocketInterfaceVrrpInput """Only relevant for CATO""" wan: SocketInterfaceWanInput } type UpdateSocketInterfacePayload { siteId: ID! socketInterfaceId: SocketInterfaceIDEnum! } input SocketInterfaceBandwidthInput { downstreamBandwidth: Int downstreamBandwidthMbpsPrecision: Float @beta upstreamBandwidth: Int upstreamBandwidthMbpsPrecision: Float @beta } input SocketInterfaceWanInput { precedence: SocketInterfacePrecedenceEnum! role: SocketInterfaceRole! } input SocketInterfaceLanInput { localIp: IPAddress! subnet: IPSubnet! translatedSubnet: IPSubnet } input SocketInterfaceOffCloudInput { enabled: Boolean! publicIp: IPAddress publicStaticPort: Int } input SocketInterfaceAltWanInput { privateGatewayIp: IPAddress! privateInterfaceIp: IPAddress! privateNetwork: IPSubnet! privateVlanTag: Int publicGatewayIp: IPAddress publicInterfaceIp: IPAddress publicNetwork: IPSubnet publicVlanTag: Int } input SocketInterfaceLagInput { minLinks: Int! } input SocketInterfaceVrrpInput { vrrpType: VrrpType } input AddNetworkRangeInput { """Only relevant for AZURE HA sites""" azureFloatingIp: IPAddress """Only relevant for NATIVE, VLAN rangeType""" dhcpSettings: NetworkDhcpSettingsInput """Only relevant for ROUTED_ROUTE rangeType""" gateway: IPAddress internetOnly: Boolean """ Only relevant for NATIVE, SECONDARY_NATIVE, DIRECT_ROUTE, VLAN rangeType """ localIp: IPAddress """BETA - Only relevant for NATIVE, DIRECT_ROUTE and VLAN rangeType""" mdnsReflector: Boolean name: String! rangeType: SubnetType! subnet: IPSubnet! translatedSubnet: IPSubnet """Only relevant for VLAN network rangeType""" vlan: Int } input UpdateNetworkRangeInput { """Only relevant for AZURE HA sites""" azureFloatingIp: IPAddress """Only relevant for NATIVE, VLAN rangeType""" dhcpSettings: NetworkDhcpSettingsInput """Only relevant for ROUTED_ROUTE rangeType""" gateway: IPAddress internetOnly: Boolean """ Only relevant for NATIVE, SECONDARY_NATIVE, DIRECT_ROUTE, VLAN rangeType """ localIp: IPAddress """BETA - Only relevant for NATIVE, DIRECT_ROUTE and VLAN rangeType""" mdnsReflector: Boolean name: String rangeType: SubnetType subnet: IPSubnet translatedSubnet: IPSubnet """Only relevant for NATIVE and VLAN network rangeType""" vlan: Int } input NetworkDhcpSettingsInput { """Only relevant for DHCP range""" dhcpMicrosegmentation: Boolean dhcpType: DhcpType! ipRange: IPRange relayGroupId: ID } input UpdateHaInput { primaryManagementIp: IPAddress secondaryManagementIp: IPAddress vrid: Int } input AddStaticHostInput { ip: IPAddress! macAddress: String name: String! } input UpdateStaticHostInput { ip: IPAddress macAddress: String name: String } type RemoveSitePayload { siteId: ID! } type AddSocketSitePayload { siteId: ID! } type AddNetworkRangePayload { networkRangeId: ID! } type UpdateNetworkRangePayload { networkRangeId: ID! } type RemoveNetworkRangePayload { networkRangeId: ID! } type UpdateHaPayload { siteId: ID! } type AddStaticHostPayload { hostId: ID! } type UpdateStaticHostPayload { hostId: ID! } type RemoveStaticHostPayload { hostId: ID! } enum SocketInterfacePrecedenceEnum { ACTIVE LAST_RESORT PASSIVE } enum SiteConnectionTypeEnum { SOCKET_AWS1500 SOCKET_AZ1500 SOCKET_ESX1500 SOCKET_GCP1500 SOCKET_X1500 SOCKET_X1600 SOCKET_X1600_LTE SOCKET_X1700 } enum HaRole { PRIMARY SECONDARY } """A from-to range (used for DHCP range, for example)""" scalar IPRange """ Enter the time frame for the data that the query returns. The argument is in the format \.\ This argument is mandatory. These are the supported options to define the time frame: last.\