Skip to main content

SaaS Security Event Collector

This Integration is part of the SaaS Security by Palo Alto Networks Pack.#

Supported versions

Supported Cortex XSOAR versions: 6.8.0 and later.

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

Configure SaaS Security on Cortex XSIAM#

  1. Navigate to Settings > Configurations > Data Collection > Automations & Feed Integrations.

  2. Search for Saas Security Event Collector.

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

    ParameterDescriptionRequired
    Your server URLThe instance configuration URL based on the server location.True
    Client IDThe SaaS Security Client ID.True
    Client SecretThe 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 settingsUses 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.The maximum number of events to fetch every time fetch is being executed. This number must be divisible by 100 due to Saas-Security api limitations. Default is 1000. In case this is empty, all available events will be fetched.False
    The maximum number of iterations to retrieve events.In order to prevent timeouts, set this parameter to limit the number of iterations for retrieving events. Note - the default value is the recommended value to prevent timeouts. Default is 150.False
  4. 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:

  1. Navigate to Settings > External Service.
  2. Click Add API Client.
  3. Specify a unique name for the API client.
  4. 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.
  5. 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.
  6. 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 Saas-Security cache, so setting a low limit could cause events to expire if there are a large number of events in the Saas-Security cache. 2) If the max_fetch is not dividable by 10, it will be rounded down to a number that is dividable by 10 due to SaaS Security api limits. 3) reset last fetch has no effect. 4) On initial activation this integration will pull events starting from one hour prior. 5) Using the saas-security-get-events command may take upwards of twenty seconds in some cases. 6) In some rare cases more than max_fetch events could be fetched. 7) The maximum recommended max fetch is 5000 to avoid fetch timeouts. 8) In case not providing the max_fetch argument, 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.

Base Command#

saas-security-get-events

Input#

Argument NameDescriptionRequired
limitThe maximum number of events to get. Must be divisible by 100 due to Saas-Security api limitations. Overrides the max-fetch parameter of the integration.Optional
should_push_eventsSet 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#

PathTypeDescription
SaasSecurity.Event.log_typeStringEvent type.
SaasSecurity.Event.item_typeStringItem type (File, Folder, or User).
SaasSecurity.Event.item_nameStringName of the file, folder, or user associated with the event.
SaasSecurity.Event.item_unique_idStringUnique ID number for an asset’s related asset.
SaasSecurity.Event.userStringCloud app user that performed the action.
SaasSecurity.Event.source_ipStringOriginal session source IP address.
SaasSecurity.Event.locationStringLocation of the cloud app user that performed the event.
SaasSecurity.Event.actionStringAction performed.
SaasSecurity.Event.target_nameStringTarget name.
SaasSecurity.Event.target_typeStringTarget type.
SaasSecurity.Event.serialStringSerial number of the organization using the service (tenant).
SaasSecurity.Event.cloud_app_instanceStringCloud app name (not cloud app type).
SaasSecurity.Event.timestampDateISO8601 timestamp to show when the event occurred.
SaasSecurity.Event.severityNumberSeverity (0-5).
SaasSecurity.Event.incident_idStringIncident/risk id.
SaasSecurity.Event.exposureStringExposure level (public, external, company, or internal).
SaasSecurity.Event.asset_idStringThe asset ID.
SaasSecurity.Event.item_ownerStringThe item owner.
SaasSecurity.Event.container_nameStringItem’s container name.
SaasSecurity.Event.item_creatorStringItem creator.
SaasSecurity.Event.occurrences_by_ruleNumberNumber of times the asset violated the policy.
SaasSecurity.Event.policy_rule_nameStringViolated policy’s name.
SaasSecurity.Event.incident_ownerStringIncident owner.
SaasSecurity.Event.incident_categoryStringIncident category.
SaasSecurity.Event.item_creator_emailStringItem creator’s email.
SaasSecurity.Event.action_takenStringAction taken.
SaasSecurity.Event.action_taken_byStringAction taken by.
SaasSecurity.Event.fieldStringName of field (optional).
SaasSecurity.Event.resource_value_oldStringOld resource value. (optional).
SaasSecurity.Event.resource_value_newStringNew 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#

LogTypeItemTypeItemNameTimestamp
activity_monitoringfilessn_test3.txt2022-05-30T06:40:59Z
activity_monitoringfileSP0605 copy.java.txt2022-05-30T06:40:47Z