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
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. 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 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 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
Example Incident Response
Example Remediation Response
Example Policy Violation Response
Example Admin Audit Response
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 Name | Description | Required |
|---|---|---|
| limit | The 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_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#
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