SaaS Security Event Collector

Palo Alto Networks SaaS Security Event Collector integration for XSIAM.

Analytics & SIEM · SaaS Security by Palo Alto Networks

Details

ID	`SaaS Security Event Collector`
Provider	Palo Alto Networks
Category	Analytics & SIEM
From Version	6.8.0
Docker Image	`demisto/python3:3.12.13.10116658`
Supported Modules	Agentix XSIAM EDR Cloud Runtime Security

README

SaaS Security is an integrated CASB (Cloud Access Security Broker) solution that helps Security teams like yours meet
the challenges of:

protecting the growing availability of sanctioned and unsanctioned SaaS applications
maintaining compliance consistently in the cloud
stopping threats to sensitive information, users, and resources

This is the default integration for this content pack when configured by the Data Onboarder in Cortex XSIAM.

Configure SaaS Security on Cortex XSIAM

Navigate to Settings > Configurations > Data Collection > Automations & Feed Integrations.
Search for SaaS Security Event Collector.

Click Add instance to create and configure a new integration instance.

Parameter	Description	Required
Your server URL	The instance configuration URL based on the server location.	True
Client ID	The SaaS Security Client ID.	True
Client Secret	The SaaS Security Secret ID.	True
Trust any certificate (not secure)	By default, SSL verification is enabled. If selected, the connection isn’t secure and all requests return an SSL error because the certificate cannot be verified.	False
Use system proxy settings	Uses the system proxy server to communicate with the integration. If not selected, the integration will not use the system proxy server.	False
The maximum number of events per fetch.	Applies only to the manual `saas-security-get-events` command. During scheduled Fetch Events, the collector drains as much of the queue as possible per cycle (bounded by The maximum number of iterations to retrieve events), so this value does not throttle live ingestion. Must be divisible by 10 due to SaaS Security API limitations. Default is 1000.	False
The maximum number of iterations to retrieve events.	Each iteration retrieves up to 100 events from the SaaS Security queue (the API’s per-request limit). This parameter caps the number of iterations per fetch execution to prevent timeouts; the collector keeps draining across consecutive executions until the queue is empty. Increase this value if ingestion lag builds up under a high event rate. Default is 900.	False
Number of concurrent fetch requests	The number of GET requests sent in parallel each iteration to drain the SaaS Security queue faster under high event rates. Maximum is 30. This is an advanced parameter. Default is 10.	False
Treat an empty Cortex XSIAM response as delivered	Whether to treat a success (200) response from Cortex XSIAM that has an empty body as a successful delivery instead of retrying it indefinitely. Truncated or otherwise invalid responses are still retried. This is an advanced parameter.	False

Click Test to validate the URLs, token, and connection.

Create the Client ID and Client Secret on SaaS Security

In the SaaS Security UI, do the following:

Navigate to Settings > External Service.
Click Add API Client.
Specify a unique name for the API client.
Authorize the API client for the required scopes. You use these scopes in the POST request to the /oauth/token endpoint. The Required Scopes are:
- Log access — Access log files. You can either provide the client log access API or add a syslog receiver.
- Incident management — Retrieve and change the incident status.
- Quarantine management — Quarantine assets and restore quarantined assets.
Copy the client ID and client secret.
Tip: Record your API client secret somewhere safe. For security purposes, it’s only shown when you create or reset the API client. If you lose your secret you must reset it, which removes access for any integrations that still use the previous secret.
Add the Client ID and Client Secret to Cortex XSOAR.
Note: For more information see the SaaS Security Administrator’s Guide

Limitations

1) Occurring events expire after one hour in the SaaS Security cache. During scheduled fetch the collector drains the queue continuously (it does not stop early at max_fetch), so under normal operation events are pulled well within the one-hour window. If the upstream event rate is very high and a single instance cannot keep up, increase The maximum number of iterations to retrieve events so each cycle drains more, and/or distribute the load across multiple instances.
2) The SaaS Security /log_events_bulk API returns at most 100 events per call. Each fetch iteration retrieves one such batch.
3) If the max_fetch is not divisible by 10, it will be rounded down to a number that is divisible by 10 due to SaaS Security API limits.
4) reset last fetch has no effect.
5) On initial activation this integration will pull events starting from one hour prior.
6) Using the saas-security-get-events command may take upwards of twenty seconds in some cases.
7) The max_fetch parameter applies only to the manual saas-security-get-events command; it does not limit the scheduled Fetch Events flow, which drains the full queue per cycle (bounded by the maximum number of iterations).
8) In case not providing the max_fetch argument to the saas-security-get-events command, the default will be 1000.

Fetch Events

Requires the scope of api_access in order to fetch log events. See Documentation
Since those events are saved only 1 hour at cache, it is highly recommended giving Events Fetch Interval in minutes rather than hours.

In case not stating a max fetch in the integration parameters, all available events will be fetched.

Log types could be one of policy_violation, activity_monitoring, remediation, incident, and admin_audit.
Every type returns a different api response that is unique.

Example Activity Monitoring Response

{
    "log_type" : "activity_monitoring",
    "item_type" : "File",
    "item_name" : "My File",
    "user" : "John Smith",
    "source_ip" : "10.10.10.10",
    "location" : "Somewhere, USA",
    "action" : "delete",
    "target_name" : null,
    "target_type" : null,
    "severity" : 1.0,
    "serial" : "mySerial",
    "cloud_app_instance" : "My Cloud App",
    "timestamp" : "2018-11-09T18:30:33.155Z"
}

Example Incident Response

{
    "log_type" : "incident",
    "severity" : 4.0,
    "item_type" : "File",
    "item_name" : "My File",
    "asset_id" : "ce7c9ed11e6f4891ae73c1601af7f741",
    "item_owner" : "John Smith",
    "container_name" : "Container",
    "item_creator" : "John Smith",
    "exposure" : "public",
    "occurrences_by_rule" : 5,
    "item_owner_email" : "owner@<--domain-->.com",
    "item_creator_email" : "creator@<--domain-->.com",
    "serial" : "mySerial",
    "cloud_app_instance" : "My Cloud App",
    "timestamp" : "2018-11-09T18:30:32.572Z",
    "incident_id" : "9610efdcd8a74a259bf031843eac0309",
    "policy_rule_name" : "PCI Policy",
    "incident_category" : "Testing",
    "incident_owner" : "John Smith"
}

Example Remediation Response

{
    "log_type" : "remediation",
    "item_type" : "File",
    "item_name" : "My File",
    "asset_id" : "ce7c9ed11e6f4891ae73c1601af7f741",
    "item_owner" : "John Smith",
    "container_name" : "Container",
    "item_creator" : "John Smith",
    "action_taken" : "quarantine",
    "action_taken_by" : "John Smith",
    "item_owner_email" : "owner@<--domain-->.com",
    "item_creator_email" : "creator@<--domain-->.com",
    "serial" : "mySerial",
    "cloud_app_instance" : "My Cloud App",
    "timestamp" : "2018-11-09T18:30:30.909Z",
    "incident_id" : "9610efdcd8a74a259bf031843eac0309",
    "policy_rule_name" : "PCI Policy"
}

Example Policy Violation Response

{
    "log_type" : "policy_violation",
    "severity" : 3.0,
    "item_type" : "File",
    "item_name" : "My File",
    "item_owner" : "John Smith",
    "item_creator" : "John Smith",
    "action_taken" : "download",
    "action_taken_by" : "John Smith",
    "asset_id" : "ce7c9ed11e6f4891ae73c1601af7f741",
    "item_owner_email" : null,
    "item_creator_email" : null,
    "serial" : "serial",
    "cloud_app_instance" : "My Cloud App",
    "timestamp" : "2017-01-06T19:04:06Z",
    "policy_rule_name" : "Policy Rule",
    "incident_id" : "1234"
}

Example Admin Audit Response

{
    "log_type" : "admin_audit",
    "admin_id" : "admin id",
    "admin_role" : "admin role",
    "ip" : "ip address",
    "event_type" : "event type",
    "item_type" : "File",
    "item_name" : "My File",
    "field" : "field",
    "action" : "action",
    "resource_value_old" : "old val",
    "resource_value_new" : "new val",
    "timestamp" : "2018-11-09T18:30:29.739Z",
    "serial" : "mySerial"
}

for more information see documentation

Commands

You can execute these commands from the Cortex XSIAM CLI as part of an automation or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

saas-security-get-events

Manual command to fetch events and display them. Use this command for development and debugging only, as it may produce duplicate events, exceed API rate limits, or disrupt the fetch mechanism.

Base Command

saas-security-get-events

Input

Argument Name	Description	Required
limit	The maximum number of events to get. Must be divisible by 10 due to SaaS Security API limitations. Overrides the max-fetch parameter of the integration.	Optional
should_push_events	Set this argument to True in order to create events, otherwise the command will only display them. If setting to ‘False’ The returned events will be lost. Possible values are: True, False. Default is False.	Required

Context Output

Path	Type	Description
SaasSecurity.Event.log_type	String	Event type.
SaasSecurity.Event.item_type	String	Item type (File, Folder, or User).
SaasSecurity.Event.item_name	String	Name of the file, folder, or user associated with the event.
SaasSecurity.Event.item_unique_id	String	Unique ID number for an asset’s related asset.
SaasSecurity.Event.user	String	Cloud app user that performed the action.
SaasSecurity.Event.source_ip	String	Original session source IP address.
SaasSecurity.Event.location	String	Location of the cloud app user that performed the event.
SaasSecurity.Event.action	String	Action performed.
SaasSecurity.Event.target_name	String	Target name.
SaasSecurity.Event.target_type	String	Target type.
SaasSecurity.Event.serial	String	Serial number of the organization using the service (tenant).
SaasSecurity.Event.cloud_app_instance	String	Cloud app name (not cloud app type).
SaasSecurity.Event.timestamp	Date	ISO8601 timestamp to show when the event occurred.
SaasSecurity.Event.severity	Number	Severity (0-5).
SaasSecurity.Event.incident_id	String	Incident/risk id.
SaasSecurity.Event.exposure	String	Exposure level (public, external, company, or internal).
SaasSecurity.Event.asset_id	String	The asset ID.
SaasSecurity.Event.item_owner	String	The item owner.
SaasSecurity.Event.container_name	String	Item’s container name.
SaasSecurity.Event.item_creator	String	Item creator.
SaasSecurity.Event.occurrences_by_rule	Number	Number of times the asset violated the policy.
SaasSecurity.Event.policy_rule_name	String	Violated policy’s name.
SaasSecurity.Event.incident_owner	String	Incident owner.
SaasSecurity.Event.incident_category	String	Incident category.
SaasSecurity.Event.item_creator_email	String	Item creator’s email.
SaasSecurity.Event.action_taken	String	Action taken.
SaasSecurity.Event.action_taken_by	String	Action taken by.
SaasSecurity.Event.field	String	Name of field (optional).
SaasSecurity.Event.resource_value_old	String	Old resource value. (optional).
SaasSecurity.Event.resource_value_new	String	New resource value. (optional).

Command example

!saas-security-get-events limit=200 should_push_events=False

Context Example

{
    "SaasSecurity": {
        "Event": [
            {
                "action": "preview",
                "cloud_app_instance": "Box 1",
                "item_name": "ssn_test3.txt",
                "item_type": "file",
                "item_unique_id": "123",
                "location": "somewhere, usa",
                "log_type": "activity_monitoring",
                "serial": null,
                "severity": 1,
                "source_ip": "2.2.2.2",
                "target_name": null,
                "target_type": "",
                "timestamp": "2022-05-30T06:40:59Z",
                "user": "some email"
            },
            {
                "action": "preview",
                "cloud_app_instance": "Box 1",
                "item_name": "SP0605 copy.java.txt",
                "item_type": "file",
                "item_unique_id": "1234",
                "location": "somewhere usa, Israel",
                "log_type": "activity_monitoring",
                "serial": null,
                "severity": 1,
                "source_ip": "1.1.1.1",
                "target_name": null,
                "target_type": "",
                "timestamp": "2022-05-30T06:40:47Z",
                "user": "some email"
            }
        ]
    }
}

Human Readable Output

SaaS Security Logs

LogType ItemType ItemName Timestamp

activity_monitoring file ssn_test3.txt 2022-05-30T06:40:59Z

activity_monitoring file SP0605 copy.java.txt 2022-05-30T06:40:47Z

LogType	ItemType	ItemName	Timestamp
activity_monitoring	file	ssn_test3.txt	2022-05-30T06:40:59Z
activity_monitoring	file	SP0605 copy.java.txt	2022-05-30T06:40:47Z

Configuration parameters

url — Your server URL (required)
credentials — Client ID (required)
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
max_fetch — The maximum number of events per fetch.
max_iterations — The maximum number of iterations to retrieve events
event_fetch_concurrency — Number of concurrent fetch requests
event_pass_over_empty_response — Treat an empty Cortex XSIAM response as delivered

Commands (1)

saas-security-get-events
Manual command to fetch events and display them. Use this command for development and debugging only, as it may produce duplicate events, exceed API rate limits, or disrupt the fetch mechanism.

Source

SaasSecurityEventCollector.py SaasSecurityEventCollector_test.py SaasSecurityEventCollector.yml SaasSecurityEventCollector_description.md command_examples.txt

Download History Raw

name: SaaS Security Event Collector
display: SaaS Security Event Collector
category: Analytics & SIEM
provider: Palo Alto Networks
sectionorder:
- Connect
- Collect
commonfields:
  id: SaaS Security Event Collector
  version: -1
configuration:
- additionalinfo: 'The instance configuration URL based on the server location: <br/>US: https://api.aperture.paloaltonetworks.com<br/> EU: https://api.aperture-eu.paloaltonetworks.com<br/> APAC: https://api.aperture-apac.paloaltonetworks.com'
  defaultvalue: https://api.aperture.paloaltonetworks.com
  display: Your server URL
  name: url
  required: true
  type: 0
  section: Connect
- additionalinfo: The SaaS Security Client ID and Client Secret.
  display: Client ID
  displaypassword: Client Secret
  name: credentials
  required: true
  type: 9
  section: Connect
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  required: false
  section: Connect
- display: Use system proxy settings
  name: proxy
  type: 8
  required: false
  section: Connect
- display: The maximum number of events per fetch.
  additionalinfo: 'The maximum number of events to fetch. Applies only to the manual ''saas-security-get-events'' command. During scheduled ''Fetch Events'', the collector drains as much of the queue as possible per cycle (bounded by ''The maximum number of iterations to retrieve events''), so this value does not throttle live ingestion. Must be divisible by 10 due to SaaS Security API limitations.'
  defaultvalue: 1000
  name: max_fetch
  type: 0
  required: false
  section: Collect
- display: The maximum number of iterations to retrieve events
  additionalinfo: 'The maximum number of iterations to retrieve events. Each iteration retrieves up to 100 events from the SaaS Security queue (the API''s per-request limit). This is an upper bound on iterations per fetch execution; in practice each execution stops within a safe time budget before the engine timeout, so this mainly provides headroom to keep draining a large backlog for the full budget. The collector keeps draining across consecutive executions until the queue is empty. A lower configured value is automatically raised to the required minimum.'
  defaultvalue: 900
  name: max_iterations
  type: 0
  required: false
  section: Collect
- display: Number of concurrent fetch requests
  additionalinfo: 'The number of GET requests issued concurrently against the SaaS Security queue per fetch round. Higher values increase drain throughput for high event rates. Maximum is 30. This is an advanced parameter.'
  defaultvalue: 10
  name: event_fetch_concurrency
  type: 0
  required: false
  advanced: true
  section: Collect
- display: Treat an empty Cortex XSIAM response as delivered
  additionalinfo: 'Whether to treat a send that fails only because Cortex XSIAM returned a success (200) with an empty/blank body (no JSON acknowledgement to parse) as delivered instead of being re-stashed and retried indefinitely. The events were already sent over the wire; only the acknowledgement was missing. Truncated or non-empty unparseable responses are still treated as real failures and retried. Enable this as a temporary workaround for a known server-side empty-body response; disable it to strictly require a valid acknowledgement. This is an advanced parameter.'
  defaultvalue: 'true'
  name: event_pass_over_empty_response
  type: 8
  required: false
  advanced: true
  section: Collect
description: Palo Alto Networks SaaS Security Event Collector integration for XSIAM.
script:
  commands:
  - description: Manual command to fetch events and display them. Use this command for development and debugging only, as it may produce duplicate events, exceed API rate limits, or disrupt the fetch mechanism.
    name: saas-security-get-events
    arguments:
    - name: limit
      description: The maximum number of events to get. Must be divisible by 10 due to SaaS Security API limitations. Overrides the max-fetch parameter of the integration.
    - auto: PREDEFINED
      defaultValue: 'False'
      description: Set this argument to True in order to create events, otherwise the command will only display them. *If setting to 'False' The returned events will be lost.
      name: should_push_events
      predefined:
      - 'True'
      - 'False'
      required: true
    outputs:
    - contextPath: SaasSecurity.Event.log_type
      description: Event type.
      type: String
    - contextPath: SaasSecurity.Event.item_type
      description: Item type (File, Folder, or User).
      type: String
    - contextPath: SaasSecurity.Event.item_name
      description: Name of the file, folder, or user associated with the event.
      type: String
    - contextPath: SaasSecurity.Event.item_unique_id
      description: Unique ID number for an asset’s related asset.
      type: String
    - contextPath: SaasSecurity.Event.user
      description: Cloud app user that performed the action.
      type: String
    - contextPath: SaasSecurity.Event.source_ip
      description: Original session source IP address.
      type: String
    - contextPath: SaasSecurity.Event.location
      description: Location of the cloud app user that performed the event.
      type: String
    - contextPath: SaasSecurity.Event.action
      description: Action performed.
      type: String
    - contextPath: SaasSecurity.Event.target_name
      description: Target name.
      type: String
    - contextPath: SaasSecurity.Event.target_type
      description: Target type.
      type: String
    - contextPath: SaasSecurity.Event.serial
      description: Serial number of the organization using the service (tenant).
      type: String
    - contextPath: SaasSecurity.Event.cloud_app_instance
      description: Cloud app name (not cloud app type).
      type: String
    - contextPath: SaasSecurity.Event.timestamp
      description: ISO8601 timestamp to show when the event occurred.
      type: Date
    - contextPath: SaasSecurity.Event.severity
      description: Severity (0-5).
      type: Number
    - contextPath: SaasSecurity.Event.incident_id
      description: Incident/risk id.
      type: String
    - contextPath: SaasSecurity.Event.exposure
      description: Exposure level (public, external, company, or internal).
      type: String
    - contextPath: SaasSecurity.Event.asset_id
      description: The asset ID.
      type: String
    - contextPath: SaasSecurity.Event.item_owner
      description: The item owner.
      type: String
    - contextPath: SaasSecurity.Event.container_name
      description: Item’s container name.
      type: String
    - contextPath: SaasSecurity.Event.item_creator
      description: Item creator.
      type: String
    - contextPath: SaasSecurity.Event.occurrences_by_rule
      description: Number of times the asset violated the policy.
      type: Number
    - contextPath: SaasSecurity.Event.policy_rule_name
      description: Violated policy’s name.
      type: String
    - contextPath: SaasSecurity.Event.incident_owner
      description: Incident owner.
      type: String
    - contextPath: SaasSecurity.Event.incident_category
      description: Incident category.
      type: String
    - contextPath: SaasSecurity.Event.item_creator_email
      description: Item creator’s email.
      type: String
    - contextPath: SaasSecurity.Event.action_taken
      description: Action taken.
      type: String
    - contextPath: SaasSecurity.Event.action_taken_by
      description: Action taken by.
      type: String
    - contextPath: SaasSecurity.Event.field
      description: Name of field (optional).
      type: String
    - contextPath: SaasSecurity.Event.resource_value_old
      description: Old resource value. (optional).
      type: String
    - contextPath: SaasSecurity.Event.resource_value_new
      description: New resource value. (optional).
      type: String
  dockerimage: demisto/python3:3.12.13.10116658
  isfetchevents: true
  script: '-'
  subtype: python3
  type: python
tests:
- No tests (auto formatted)
marketplaces:
- marketplacev2
- platform
fromversion: 6.8.0
supportedModules:
- xsiam