Skip to main content

SaaS Security

This Integration is part of the SaaS Security Pack.#

Supported versions

Supported Cortex XSOAR versions: 6.0.0 and later.

Use the SaaS Security integration to protect against cloud‑based threats by:

  • Scanning and analyzing all your assets.
  • Applying Security policy to identify exposures, external collaborators, risky user behavior, and sensitive documents.
  • Identifying the potential risks associated with each asset.

Configure SaaS Security on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for SaaS Security.

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

    ParameterDescriptionRequired
    Server URLThe instance configuration URL based on the server location: https://api.aperture.paloaltonetworks.com (US)
    https://api.aperture-eu.paloaltonetworks.com (EU)
    https://api.aperture-apac.paloaltonetworks.com (APAC)
    True
    Client IDThe SaaS Security Client ID. See instructions below.True
    Client SecretThe SaaS Security Client Secret. See instructions below.True
    Fetch incidentsIf selected, fetches incidents from SaaS Security.False
    Incidents Fetch IntervalFrequency (in hours and minutes) by which Cortex XSOAR fetches incidents from SaaS Security when Fetch Incidents is selected.False
    Incident typeIncident type is set by this field if a classifier does not exist. If a classifier is selected, it takes precedence.False
    Incident Mirroring DirectionSelects which direction you want the incidents mirrored. You can mirror Incoming only (from SaaS Security to Cortex XSOAR), Outgoing only (from Cortex XSOAR to SaaS Security), or both Incoming And Outgoing.False
    Number of incidents per fetchMinimum is 10. Maximum is 1000.True
    First fetch timestamp (<number> <time unit>. For example, 12 hours, 7 days)False
    Fetch only incidents with matching stateFetches only incidents with matching All, Closed, or Open state. If nothing is selected, All states will be used.False
    Fetch only incidents with matching severityIf nothing is selected, All severities will be used.False
    Fetch only incidents with matching statusIf nothing is selected, All statuses will be used.False
    Fetch only incidents with matching Application IDsA comma-separated list of Application IDs. Run the saas-security-get-apps command to return the Application ID, Name, and Type for all applications.False
    Close Mirrored XSOAR IncidentIf selected, when the incident closes on SaaS Security, the incident closes in Cortex XSOAR.False
    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
  4. Click Test to validate the URLs, token, and connection.

Configure SaaS Security Incident Mirroring#

You can enable incident mirroring between Cortex XSOAR incidents and SaaS Security notables (available from Cortex XSOAR version 6.0.0). To set up mirroring.

To configure mirroring:

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for SaaS Security and select your integration instance.
  3. Enable Fetches incidents.
  4. In the Incident Mirroring Direction integration parameter, select which direction you want the incidents to be mirrored:
    • Incoming — Any changes in the following SaaS Security incidents fields (state, category, status, assigned_to, resolved_by, asset_sha256) will be reflected in Cortex XSOAR incidents.
    • Outgoing — Any changes in the following Cortex XSOAR incidents fields (state, category) will be reflected in SaaS Security incidents.
    • Incoming And Outgoing (Recommended) — Changes in Cortex XSOAR incidents and SaaS Security incidents will be reflected in both directions.
    • None — Turns off incident mirroring.
  5. (Recommended) Select the Close Mirrored XSOAR Incident integration parameter to close the Cortex XSOAR incident when the corresponding incident is closed on SaaS Security.
    - There is no closing parameter for the opposite direction (to close incidents in SaaS Security when they are closed in XSOAR). *Close Mirrored XSOAR Incident* is the only use case available for *mirrored out*, when the state and category are updated.
    Newly fetched incidents will be mirrored in the direction you select. However, this selection does not affect existing incidents.

Important Notes

  • For mirroring to work, the Incident Mirroring Direction parameter needs to be set before the incident is fetched.
  • To ensure mirroring works as expected, mappers are required for both Incoming and Outgoing to map the expected fields in Cortex XSOAR and SaaS Security.
  • The only fields that can be mirrored in from SaaS Security to Cortex XSOAR are:
    • state
    • category
    • status
    • assigned_to
    • resolved_by
    • asset_sha256
  • The only fields that can be mirrored out from XSOAR to SaaS Security are:
    • state
    • category The supported categories for closing incidents are: "misidentified", "no_reason", and "business_justified". Note: Mirroring out works only for closed incidents due to an API limitation.

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

Commands#

You can execute these commands from the Cortex XSOAR 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-incidents-get#


Retrieves incidents from the SaaS Security platform.

Base Command#

saas-security-incidents-get

Input#

Argument NameDescriptionRequired
limitThe number of incidents to pull. Maximum is 200, minimum is 10. Default is 50. Default is 50.Optional
fromThe start time of the query, filtered by the date the incident was updated,\ \ For example, 2021-08-23T09:26:25.872Z.Optional
toThe end time of the query, filtered by the date the incident was updated. For example, 2021-08-23T09:26:25.872Z.Optional
app_idsComma-separated list of application IDs. Run the 'saas-security-get-apps' command to return the Application ID, Name, and Type for all applications.Optional
stateThe state of the incidents. If empty, retrieves all states. Possible values: "All", "Open", and "Closed". Possible values are: All, Open, Closed. Default is open.Optional
severityThe severity of the incidents. In none is selected, all severities will be pulled. Possible values: "1", "2", "3", "4", and "5". Possible values are: 1, 2, 3, 4, 5.Optional
statusThe status of the incidents. Possible values: "New", "Assigned", "In Progress", "Pending", "No Reason", "Business Justified", "Misidentified", "In The Cloud", and "Dismiss". Possible values are: New, Assigned, In Progress, Pending, No Reason, Business Justified, Misidentified, In The Cloud, Dismiss.Optional
next_pageGet the next batch of incidents. No other argument is needed when providing this.Optional

Context Output#

PathTypeDescription
SaasSecurity.Incident.incident_idNumberThe incident ID.
SaasSecurity.Incident.tenantStringThe tenant associated with the incident.
SaasSecurity.Incident.app_idStringThe application ID.
SaasSecurity.Incident.app_nameStringThe application name.
SaasSecurity.Incident.app_typeStringThe application type.
SaasSecurity.Incident.cloud_idStringThe cloud ID.
SaasSecurity.Incident.asset_nameStringThe asset name.
SaasSecurity.Incident.asset_sha256StringThe SHA256 hash value of the asset.
SaasSecurity.Incident.asset_idStringThe asset ID.
SaasSecurity.Incident.asset_page_uriStringThe asset page URI.
SaasSecurity.Incident.asset_cloud_uriStringThe asset cloud URI.
SaasSecurity.Incident.exposure_typeNumberThe exposure type (Internal/External).
SaasSecurity.Incident.exposure_levelStringThe exposure level.
SaasSecurity.Incident.policy_idStringThe policy ID.
SaasSecurity.Incident.policy_nameStringThe policy name.
SaasSecurity.Incident.policy_versionNumberThe policy version.
SaasSecurity.Incident.policy_page_uriStringThe policy page URI.
SaasSecurity.Incident.severityStringThe severity of the incident.
SaasSecurity.Incident.statusStringThe incident status.
SaasSecurity.Incident.stateStringThe incident state.
SaasSecurity.Incident.categoryStringThe incident category.
SaasSecurity.Incident.resolved_byStringThe name of the user who resolved the incident.
SaasSecurity.Incident.resolution_dateDateThe date the incident was resolved.
SaasSecurity.Incident.created_atDateThe date the incident was created, e.g., `2021-08-23T09:26:25.872Z`.
SaasSecurity.Incident.updated_atDateThe Date the incident was last updated. e.g., `2021-08-24T09:26:25.872Z`.
SaasSecurity.Incident.asset_owner_idStringThe ID of the asset owner.
SaasSecurity.Incident.asset_owner_nameStringThe name of the asset owner.
SaasSecurity.Incident.asset_owner_emailStringThe email address of the asset owner.
SaasSecurity.NextResultsPageStringThe URI for the next batch of incidents.

Command Example#

!saas-security-incidents-get limit=11 app_ids=acf49b2389c09f26ad0ccd2b1a603328 from=2021-08-23T20:25:17.495Z state=open

Context Example#

{
"SaasSecurity": {
"Incident": [
{
"app_id": "acf49b2389c09f26ad0ccd2b1a603328",
"app_name": "Box 1",
"app_type": "box",
"asset_cloud_uri": "https://www.box.com/files/0/f/114948778953/1/f_675197457403",
"asset_id": "61099dc26b544e38fa3ce06d",
"asset_name": "SP0605 copy 6.java",
"asset_owner_email": "xsoartest@cirrotester.com",
"asset_owner_id": "22FD054D362DC548A9C22F25782E1DAEED03C12F3898CD0F2E2A1B4CF728D04BD644B3CC010FDAC3D10EC0D408F4F79AC147E3D56415D1052BCFCD899A8E249F",
"asset_owner_name": "Xsoar test",
"asset_page_uri": "https://xsoartest.staging.cirrotester.com/cloud_assets/61099dc26b544e38fa3ce06d",
"asset_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"category": "business_justified",
"cloud_id": "675197457403",
"collaborators": [],
"created_at": "2021-08-03T20:25:15.417Z",
"data_patterns": [],
"exposure_level": "internal",
"exposure_type": 8,
"group_ids": [],
"incident_id": 4,
"policy_id": "6109a5d0e64152534b240f48",
"policy_page_uri": "https://xsoartest.staging.cirrotester.com/data_policies/6109a5d0e64152534b240f48",
"policy_version": 1,
"policy_name": "policy name",
"resolution_date": "2021-08-24T07:44:21.608Z",
"resolved_by": "api",
"severity": "Low",
"state": "closed",
"status": "Closed-Business Justified",
"tenant": "xsoartest",
"updated_at": "2021-08-24T07:44:21.608Z"
},
{
"app_id": "acf49b2389c09f26ad0ccd2b1a603328",
"app_name": "Box 1",
"app_type": "box",
"asset_cloud_uri": "https://www.box.com/files/0/f/114948778953/1/f_675197556380",
"asset_id": "61099dbe6b544e38fa3cc9b8",
"asset_name": "SP0605 copy 2.java",
"asset_owner_email": "xsoartest@cirrotester.com",
"asset_owner_id": "22FD054D362DC548A9C22F25782E1DAEED03C12F3898CD0F2E2A1B4CF728D04BD644B3CC010FDAC3D10EC0D408F4F79AC147E3D56415D1052BCFCD899A8E249F",
"asset_owner_name": "Xsoar test",
"asset_page_uri": "https://xsoartest.staging.cirrotester.com/cloud_assets/61099dbe6b544e38fa3cc9b8",
"asset_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"category": "business_justified",
"cloud_id": "675197556380",
"collaborators": [],
"created_at": "2021-08-03T20:25:12.000Z",
"data_patterns": [],
"exposure_level": "internal",
"exposure_type": 8,
"group_ids": [],
"incident_id": 1,
"policy_id": "6109a5d0e64152534b240f48",
"policy_page_uri": "https://xsoartest.staging.cirrotester.com/data_policies/6109a5d0e64152534b240f48",
"policy_version": 1,
"resolution_date": "2021-08-24T08:19:57.429Z",
"resolved_by": "api",
"severity": "Low",
"status": "Closed-Business Justified",
"tenant": "xsoartest",
"updated_at": "2021-08-24T08:19:57.429Z"
}
]
}
}

Human Readable Output#

Incidents#

Incident IdApp IdApp NameAsset NameExposure LevelSeverityCategoryCreated AtUpdated At
4acf49b2389c09f26ad0ccd2b1a603328Box 1SP0605 copy 6.javainternalLowbusiness_justified2021-08-03T20:25:15.417Z2021-08-24T07:44:21.608Z
1acf49b2389c09f26ad0ccd2b1a603328Box 1SP0605 copy 2.javainternalLowbusiness_justified2021-08-03T20:25:12.000Z2021-08-24T08:19:57.429Z
5acf49b2389c09f26ad0ccd2b1a603328Box 1SP0605 copy 7.javainternalLowaperture2021-08-03T20:25:16.842Z2021-08-24T17:08:51.022Z
8acf49b2389c09f26ad0ccd2b1a603328Box 1ml_file.javainternalLowaperture2021-08-03T20:25:17.043Z2021-08-24T17:10:37.433Z
3acf49b2389c09f26ad0ccd2b1a603328Box 1SP0605 copy 5.javainternalLowmisidentified2021-08-03T20:25:13.770Z2021-08-25T14:29:42.288Z

saas-security-incident-get-by-id#


Gets an incident by its ID.

Base Command#

saas-security-incident-get-by-id

Input#

Argument NameDescriptionRequired
idThe incident ID.Required

Context Output#

PathTypeDescription
SaasSecurity.Incident.incident_idNumberThe Incident ID.
SaasSecurity.Incident.tenantStringThe tenant associated with the incident.
SaasSecurity.Incident.app_idStringThe application ID.
SaasSecurity.Incident.app_nameStringThe application name.
SaasSecurity.Incident.app_typeStringThe application type.
SaasSecurity.Incident.cloud_idStringThe cloud ID.
SaasSecurity.Incident.asset_nameStringThe asset name.
SaasSecurity.Incident.asset_sha256StringThe SHA256 hash value of the asset.
SaasSecurity.Incident.asset_idStringThe asset ID.
SaasSecurity.Incident.asset_page_uriStringThe asset page URI.
SaasSecurity.Incident.asset_cloud_uriStringThe asset cloud URI.
SaasSecurity.Incident.exposure_typeNumberThe exposure type (Internal/External).
SaasSecurity.Incident.exposure_levelStringThe exposure level.
SaasSecurity.Incident.policy_idStringThe policy ID.
SaasSecurity.Incident.policy_nameStringThe policy name.
SaasSecurity.Incident.policy_versionNumberThe policy version.
SaasSecurity.Incident.policy_page_uriStringThe policy page URI.
SaasSecurity.Incident.severityStringThe severity of the incident.
SaasSecurity.Incident.statusStringThe incident status.
SaasSecurity.Incident.stateStringThe incident state.
SaasSecurity.Incident.categoryStringThe incident category.
SaasSecurity.Incident.resolved_byStringThe name of the user who resolved the incident.
SaasSecurity.Incident.resolution_dateDateThe date the incident was resolved.
SaasSecurity.Incident.created_atDateThe date the incident was created, e.g., `2021-08-23T09:26:25.872Z`.
SaasSecurity.Incident.updated_atDateThe date the incident was last updated, e.g., `2021-08-24T09:26:25.872Z`.
SaasSecurity.Incident.asset_owner_idStringThe ID of the asset owner.
SaasSecurity.Incident.asset_owner_nameStringThe name of the asset owner.
SaasSecurity.Incident.asset_owner_emailStringThe email address of the asset owner.

Command Example#

!saas-security-incident-get-by-id id=4

Context Example#

{
"SaasSecurity": {
"Incident": {
"app_id": "acf49b2389c09f26ad0ccd2b1a603328",
"app_name": "Box 1",
"app_type": "box",
"asset_cloud_uri": "https://www.box.com/files/0/f/114948778953/1/f_675197457403",
"asset_id": "61099dc26b544e38fa3ce06d",
"asset_name": "SP0605 copy 6.java",
"asset_owner_email": "xsoartest@cirrotester.com",
"asset_owner_id": "22FD054D362DC548A9C22F25782E1DAEED03C12F3898CD0F2E2A1B4CF728D04BD644B3CC010FDAC3D10EC0D408F4F79AC147E3D56415D1052BCFCD899A8E249F",
"asset_owner_name": "Xsoar test",
"asset_page_uri": "https://xsoartest.staging.cirrotester.com/cloud_assets/61099dc26b544e38fa3ce06d",
"asset_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"category": "business_justified",
"cloud_id": "675197457403",
"collaborators": [],
"created_at": "2021-08-03T20:25:15.417Z",
"data_patterns": [],
"exposure_level": "internal",
"exposure_type": 8,
"group_ids": [],
"incident_id": 4,
"policy_id": "6109a5d0e64152534b240f48",
"policy_page_uri": "https://xsoartest.staging.cirrotester.com/data_policies/6109a5d0e64152534b240f48",
"policy_version": 1,
"resolution_date": "2021-08-26T07:04:14.598Z",
"resolved_by": "api",
"severity": "Low",
"state": "closed",
"tenant": "xsoartest",
"updated_at": "2021-08-26T07:04:14.598Z"
}
}
}

Human Readable Output#

Incident 4 details#

Incident IdApp IdApp NameAsset NameExposure LevelSeverityStateCategoryCreated AtUpdated At
4acf49b2389c09f26ad0ccd2b1a603328Box 1SP0605 copy 6.javainternal1.0closedbusiness_justified2021-08-03T20:25:15.417Z2021-08-26T07:04:14.598Z

saas-security-incident-state-update#


Closes an incident and updates its category.

Base Command#

saas-security-incident-state-update

Input#

Argument NameDescriptionRequired
idThe incident ID.Required
categoryThe reason for closing the incident. Possible values: "Misidentified", "No Reason", and "Business Justified". Possible values are: Misidentified, No Reason, Business Justified. Default is Reason for state update..Required

Context Output#

PathTypeDescription
SaasSecurity.IncidentState.incident_idStringThe incident ID.
SaasSecurity.IncidentState.stateStringThe incident state (open/closed).
SaasSecurity.IncidentState.categoryStringThe incident category.
SaasSecurity.IncidentState.resolved_byStringThe name of the user who resolved the incident.
SaasSecurity.IncidentState.resolution_dateDateThe date when the incident was resolved.

Command Example#

!saas-security-incident-state-update category="Business Justified" id=4

Context Example#

{
"SaasSecurity": {
"IncidentState": {
"category": "business_justified",
"incident_id": "4",
"resolution_date": "2021-08-26T07:04:14.598Z",
"resolved_by": "api",
"state": "closed"
}
}
}

Human Readable Output#

Incident 4 status details#

CategoryIncident IdResolution DateResolved ByState
business_justified42021-08-26T07:04:14.598Zapiclosed

saas-security-get-apps#


Returns the Application ID, Name, and Type for all applications.

Base Command#

saas-security-get-apps

Input#

No inputs.

Context Output#

PathTypeDescription
SaasSecurity.App.app_nameStringThe application name.
SaasSecurity.App.app_idStringThe application ID.
SaasSecurity.App.app_typeStringThe application type.

Command Example#

!saas-security-get-apps

Context Example#

{
"SaasSecurity": {
"App": [
{
"app_id": "acf49b2389c09f26ad0ccd2b1a603328",
"app_name": "Box 1",
"app_type": "box"
},
{
"app_id": "2642aaa03dc6fc44496bdfffe5e1bc74",
"app_name": "Office 365 1",
"app_type": "office365"
}
]
}
}

Human Readable Output#

Apps Info#

App IdApp NameApp Type
acf49b2389c09f26ad0ccd2b1a603328Box 1box
2642aaa03dc6fc44496bdfffe5e1bc74Office 365 1office365

saas-security-asset-remediate#


Remediates an asset.

Base Command#

saas-security-asset-remediate

Input#

Argument NameDescriptionRequired
asset_idThe ID of the asset to remediate.Required
remediation_typeThe remediation action to take. Possible values: "Remove public sharing"(only for Office365, Dropbox, Box, Google Drive apps), "Quarantine", and "Restore". Possible values are: Remove public sharing, Quarantine, Restore.Required
remove_inherited_sharingUsed when the remediation type is “Remove public sharing”. When set to true, all the parent folders with a shared URL will be removed. Possible values are: true, false. Default is false.Optional

Context Output#

PathTypeDescription
SaasSecurity.Remediation.asset_idStringThe asset ID.
SaasSecurity.Remediation.remediation_typeStringThe remediation type.
SaasSecurity.Remediation.statusStringThe remediation action status.

Command Example#

!saas-security-asset-remediate asset_id=61099dc46b544e38fa3ce89a remediation_type=Quarantine

Context Example#

{
"SaasSecurity": {
"Remediation": {
"asset_id": "61099dc46b544e38fa3ce89a",
"remediation_type": "system_quarantine",
"status": "pending"
}
}
}

Human Readable Output#

Remediation details for asset: 61099dc46b544e38fa3ce89a#

Asset IdRemediation TypeStatus
61099dc46b544e38fa3ce89asystem_quarantinepending

saas-security-remediation-status-get#


Gets the remediation status for a given asset ID.

Base Command#

saas-security-remediation-status-get

Input#

Argument NameDescriptionRequired
asset_idThe asset ID.Required
remediation_typeThe remediation action that was taken. Possible values: "Remove public sharing"(only for Office365, Dropbox, Box, Google Drive apps), "Quarantine", and "Restore". Possible values are: Remove public sharing, Quarantine, Restore.Required

Context Output#

PathTypeDescription
SaasSecurity.Remediation.asset_idStringThe asset ID.
SaasSecurity.Remediation.asset_nameStringThe asset name.
SaasSecurity.Remediation.remediation_typeStringThe remediation type.
SaasSecurity.Remediation.action_takerStringThe source of the remediation action. For example, 'api'.
SaasSecurity.Remediation.action_dateDateThe date when the remediation action was taken.
SaasSecurity.Remediation.statusStringThe remediation action status.

Command Example#

!saas-security-remediation-status-get asset_id=61099dc46b544e38fa3ce89a remediation_type=Quarantine

Context Example#

{
"SaasSecurity": {
"Remediation": {
"action_date": "2021-08-25T21:18:37.148+0000",
"action_taker": "api",
"asset_id": "61099dc46b544e38fa3ce89a",
"asset_name": "SP0605 copy.java",
"remediation_type": "system_quarantine",
"status": "success"
}
}
}

Human Readable Output#

Asset 61099dc46b544e38fa3ce89a remediation details#

Action DateAction TakerAsset IdAsset NameRemediation TypeStatus
2021-08-25T21:18:37.148+0000api61099dc46b544e38fa3ce89aSP0605 copy.javasystem_quarantinesuccess