Get Alerts Data - Netskope Knowledge Portal

Important

This Netskope REST API v1 endpoint will be retired on 10/15/2024. Refer to End of Life (EOL) for Specific REST API v1 Endpoints for more details.

This endpoint returns alerts generated by Netskope, including policy, DLP, and watch list alerts. Policy alerts are triggered when traffic matches policy. DLP alerts are generated when there is a DLP violation triggered by the policy. Watch list alerts are triggered when watchlist matches.

Request Endpoint

https://<tenant-URL>/api/v1/alerts

Valid query parameters are:

Key

Value

Description

token

string

Required. The token obtained from the REST API page in the Netskope UI ( Settings > Tools > Rest API v1) is required. We recommend that you place the token in the body of the request, not in the endpoint URL.

query

Valid alert query.

Examples:

query=compliance_standards.standard%20eq%20%27CSA-CCM-3.0.1%27%29
See Example Requests with Responses below to see how single and multiple compliance values are used inside the query parameter.
query=alert_type%20in%20%5B%20'anomaly',%20'Compromised%20Credential'%20%5D
query=alert_name%20like%20'test'
query=action%20in%20%5B%20'alert'%20%5D

This acts as a filter for all the cloud app alerts in the events database.

type

Selects Policy, DLP, Quarantine, Watchlist, etc. alerts. If nothing is passed, then it gets alerts of all types.

acked

true | false

Selects the type of alerts. If nothing is passed, then it gets alerts of all types.

timeperiod

3600 | 86400 | 604800 | 2592000

Only use one of these parameters at a time, not a combination: timeperiod, or starttime/endtime, or insertionstarttime/insertionendtime.

starttime

Unix epoch time

Restrict alerts to those that have timestamps greater than this. Needed only if timeperiod or insertionstarttime/insertionendtime is not passed.

Only use one of these parameters at a time, not a combination: timeperiod, or starttime/endtime, or insertionstarttime/insertionendtime.

endtime

Unix epoch time

Restrict alerts to those that have timestamps less than or equal to this. Needed only if timeperiod or insertionstarttime/insertionendtimeis not passed.

insertionstarttime

Unix epoch time

Restrict alerts which have been inserted into the database after the specified time. Needed only if timeperiod or starttime/endtime is not passed.

Only use one of these parameters at a time, not a combination: timeperiod, or starttime/endtime, or insertionstarttime/insertionendtime.

insertionendtime

Unix epoch time

Restrict alerts which have been inserted into the database before the specified time. Needed only if timeperiod or starttime/endtime is not passed.

limit

Positive integer less than 5000

REST API responses can return up to 10000 alerts in a single response. You can use pagination to retrieve more results.

skip

Positive integer

Skip over some of the alerts (useful for pagination in combination with limit).

unsorted

true | false

If true, the returned data will not be sorted (useful for improved performance).

to of

Page of

Response

For response information, refer to REST API Events and Alerts Response Descriptions.

Example Requests with Responses

Filter by single Compliance Standard

POST 'https://<tenant-URL>/api/v1/alerts?timeperiod=86400&type=Security%20Assessment&limit=1&stimeperiod=2592000&query=%28compliance_standards.standard%20eq%20%27CSA-CCM-3.0.1%27%29
{    
    "token": "f32a973eddd7bc1602fc0f48dc0a"
}

{
    "alert_type": "Security Assessment",
    "region_id": "westeurope",
    "sa_profile_name": "CIS Azure Foundations Benchmark v1.0.0",
    "app": "Microsoft Azure",
    "object_type": "Instance",
    "compliance_standards": [
        {
            "control": "02",
            "description": "Security Incident Management, E-Discovery, & Cloud Forensics: Incident Management | Policies and procedures shall be established, and supporting business processes and technical measures implemented, to triage security-related events and ensure timely and thorough incident management, as per established IT service management policies and procedures.",
            "section": "SEF",
            "standard": "CSA-CCM-3.0.1",
            "reference_url": "https://cloudsecurityalliance.org/research/cloud-controls-matrix/",
            "id": -91402
        }
    ],
    "account_name": "iaas-qe",
    "region_name": "West Europe",
    "category": "IaaS/PaaS",
    "timestamp": 1603870162,
    "sa_profile_id": -2001000,
    "sa_rule_id": -2067,
    "iaas_remediated": "false",
    "access_method": "API Connector",
    "policy": "azure_81_policy",
    "sa_rule_name": "Personnel know response roles/operations: Ensure that 'Send Alerts to' is set for SQL Servers",
    "type": "nspolicy",
    "account_id": "e3813397-1fff-46b0-a59f-5c2130aac115",
    "iaas_asset_tags": [],
    "sa_rule_severity": "High",
    "object": "automation1603868619",
    "alert": "yes",
    "user": "admin@netskope.com",
    "device": "other",
    "count": 1,
    "asset_object_id": "016044c5aeb1bf9c3af75357",
    "instance_id": "azure80",
    "alert_name": "Personnel know response roles/operations: Ensure that 'Send Alerts to' is set for SQL Servers",
    "activity": "Introspection Scan",
    "action": "alert",
    "browser": "unknown",
    "os": "unknown",
    "resource_category": "Database",
    "policy_id": 2,
    "organization_unit": "",
    "userkey": "admin@netskope.com",
    "ur_normalized": "admin@netskope.com",
    "site": "Windows Azure",
    "traffic_type": "CloudApp",
    "ccl": "excellent",
    "acked": "false",
    "_insertion_epoch_timestamp": 1603967916,
    "_id": "d3a03deeb9ec657d18f48a43",
    "cci": 96,
    "sa_rule_remediation": "<html>nt<body>nt    <b>Azure Console:</b>n        <ol>n            <li>Go to <code>SQL servers</code></li>n            <li>For each server instance</li>n            <li>Click on <code>Auditing & Threat Detection</code></li>n            <li>Set <code>Send alerts to</code> as appropriate</li>n        </ol>n        n        <b>Azure PowerShell:</b>n        <p>n            Get the list of all SQL Servers<br>n            <code><pre>n    Get-AzureRmSqlServern            </pre></code>n            For each Server, set <code>Send alerts to</code>.<br>n            <code><pre>n    Set-AzureRmSqlServerThreatDetectionPolicy -ResourceGroupName &lt;resource group name&gt; -ServerName &lt;server name&gt; -NotificationRecipientsEmails "&lt;Recipient Email ID&gt;"n            </pre></code>n        </p>n        n        <b>Default Value:</b><br>n        <p>n            By default, <code>Send alerts to</code> is not set.n        </p>nt</body>n</html>n",
    "appcategory": "IaaS/PaaS"
}

Filter by multiple Compliance Standards

POST 'https://<tenant-URL>/api/v1/alerts?timeperiod=2592000&query=%28compliance_standards.standard%20in%20%5B%27CSA-CCM-3.0.1%27%2C%20%27NIST-CSF-1.1%27%2C%20%27CIS-AZRFND-1.0.0%27%5D%29
{    
    "token": "f32a973eddd7bc1602fc0f48dc0a"
}

{
  "alert_type": "Security Assessment",
  "region_id": "westeurope",
  "sa_profile_name": "CIS Azure Foundations Benchmark v1.0.0",
  "app": "Microsoft Azure",
  "object_type": "Instance",
  "compliance_standards": [
      {
          "control": "02",
          "description": "Security Incident Management, E-Discovery, & Cloud Forensics: Incident Management | Policies and procedures shall be established, and supporting business processes and technical measures implemented, to triage security-related events and ensure timely and thorough incident management, as per established IT service management policies and procedures.",
          "section": "SEF",
          "standard": "CSA-CCM-3.0.1",
          "reference_url": "https://cloudsecurityalliance.org/research/cloud-controls-matrix/",
          "id": -91402
      },
      {
          "control": "1",
          "description": "Personnel know their roles and order of operations when a response is needed",
          "section": "RS.CO",
          "standard": "NIST-CSF-1.1",
          "reference_url": "https://nvlpubs.nist.gov/nistpubs/CSWP/NIST.CSWP.04162018.pdf",
          "id": -7701
      },
      {
          "control": "1.4",
          "description": "Ensure that 'Send alerts to' is set",
          "appname": "azure",
          "section": "4",
          "standard": "CIS-AZRFND-1.0.0",
          "reference_url": "https://www.cisecurity.org/benchmark/azure/",
          "id": -5414
      }
  ],
  "account_name": "iaas-qe",
  "region_name": "West Europe",
  "category": "IaaS/PaaS",
  "timestamp": 1603870162,
  "sa_profile_id": -2001000,
  "sa_rule_id": -2067,
  "iaas_remediated": "false",
  "access_method": "API Connector",
  "policy": "azure_81_policy",
  "sa_rule_name": "Personnel know response roles/operations: Ensure that 'Send Alerts to' is set for SQL Servers",
  "type": "nspolicy",
  "account_id": "e3813397-1fff-46b0-a59f-5c2130aac115",
  "iaas_asset_tags": [],
  "sa_rule_severity": "High",
  "object": "automation1603868619",
  "alert": "yes",
  "user": "admin@netskope.com",
  "device": "other",
  "count": 1,
  "asset_object_id": "016044c5aeb1bf9c3af75357",
  "instance_id": "azure80",
  "alert_name": "Personnel know response roles/operations: Ensure that 'Send Alerts to' is set for SQL Servers",
  "activity": "Introspection Scan",
  "action": "alert",
  "browser": "unknown",
  "os": "unknown",
  "resource_category": "Database",
  "policy_id": 2,
  "organization_unit": "",
  "userkey": "admin@netskope.com",
  "ur_normalized": "admin@netskope.com",
  "site": "Windows Azure",
  "traffic_type": "CloudApp",
  "ccl": "excellent",
  "acked": "false",
  "_insertion_epoch_timestamp": 1603967916,
  "_id": "d3a03deeb9ec657d18f48a43",
  "cci": 96,
  "sa_rule_remediation": "<html>nt<body>nt    <b>Azure Console:</b>n        <ol>n            <li>Go to <code>SQL servers</code></li>n            <li>For each server instance</li>n            <li>Click on <code>Auditing & Threat Detection</code></li>n            <li>Set <code>Send alerts to</code> as appropriate</li>n        </ol>n        n        <b>Azure PowerShell:</b>n        <p>n            Get the list of all SQL Servers<br>n            <code><pre>n    Get-AzureRmSqlServern            </pre></code>n            For each Server, set <code>Send alerts to</code>.<br>n            <code><pre>n    Set-AzureRmSqlServerThreatDetectionPolicy -ResourceGroupName &lt;resource group name&gt; -ServerName &lt;server name&gt; -NotificationRecipientsEmails "&lt;Recipient Email ID&gt;"n            </pre></code>n        </p>n        n        <b>Default Value:</b><br>n        <p>n            By default, <code>Send alerts to</code> is not set.n        </p>nt</body>n</html>n",
  "appcategory": "IaaS/PaaS"
}

Filter by Type

POST 'https://<tenant-URL>/api/v1/alerts?timeperiod=86400&type=Security%20Assessment&limit=1&skip=0&ack=false'
{    
    "token": "f32a973eddd7bc1602fc0f48dc0a"

}

{
   "msg" : "",
   "data" : [
      {
         "app" : "Amazon Web Services",
         "alert_name" : "CIS AWS Foundations Benchmark v1.2.0",
         "instance_id" : "aws61",
         "device" : "other",
         "ccl" : "excellent",
         "browser" : "unknown",
         "organization_unit" : "",
         "access_method" : "API Connector",
         "_session_begin" : 1,
         "sa_profile_name" : "CIS AWS Foundations Benchmark v1.2.0",
         "acked" : "false",
         "_id" : "1c248c457f5c2f2fb8b221f5",
         "type" : "nspolicy",
         "account_name" : "aws61",
         "alert_type" : "Security Assessment",
         "timestamp" : 1551713762,
         "activity" : "Introspection Scan",
         "object_type" : "Policy",
         "compliance_standards": [
        {
            "control": "02",
            "description": "Security Incident Management, E-Discovery, & Cloud Forensics",
            "section": "SEF",
            "standard": "CSA-CCM-3.0.1",
            "reference_url": "https://cloudsecurityalliance.org/research/cloud-controls-matrix/",
            "id": -91402
        }
 ],
         "user" : "meghana@netskope.com",
         "alert" : "yes",
         "userkey" : "meghana@netskope.com",
         "sa_rule_remediation" : "<html>n<body>n    <b>Using the Amazon unified command line interface:</b>n    <ol>n        <li>Create an IAM role for managing incidents with AWS:n            <ul style='list-style-type: circle;'>n                <li>Create a trust relationship policy document that allows &lt;iam_user&gt; to manage AWS incidents, and save it locally as /tmp/TrustPolicy.json:</li>n                <li>n                    <code>n                            {n                                'Version': '2012-10-17',n                                'Statement': [n                                                {n                                                    'Effect': 'Allow',n                                                    'Principal': { 'AWS': '&lt;iam_user&gt;'n                                                    },n                                                    'Action': 'sts:AssumeRole'n                                                }n                                            ]n                            }n                    </code>n                </li>n            </ul>n        </li>n        <li>n            <ul style='list-style-type: circle;'>n                <li>Create the IAM role using the above trust policy:</li>n                <li>aws iam create-role --role-name &lt;aws_support_iam_role&gt; --assume-role- policy-document file:///tmp/TrustPolicy.json</li>n            </ul>n        </li>n        <li>n            <ul style='list-style-type: circle;'>n                <li>Attach 'AWSSupportAccess' managed policy to the created IAM role:</li>n                <li>aws iam attach-role-policy --policy-arn &lt;iam_policy_arn&gt; --role-name &lt;aws_support_iam_role&gt;</li>n            </ul>n        </li>n    </ol>n    <p>n    <b>Impact</b><br>n        All AWS Support plans include an unlimited number of account and billing support cases,n        with no long-term contracts.<br>n        Support billing calculations are performed on a per-account basis for all plans. Enterprisen        Support plan customers have the option to include multiple enabled accounts in ann        aggregated monthly billing calculation.<br>n        Monthly charges for the Business and Enterprise support plans are based on each month'sn        AWS usage charges, subject to a monthly minimum, billed in advance<br>n   </p> n</body>n</html>n",
         "sa_rule_id" : -1001017,
         "sa_rule_name" : "CIS-AWSFND | 1.22 Ensure a support role has been created to manage incidents with AWS Support",
         "os" : "unknown",
         "resource_category" : "Identity",
         "object" : "arn:aws:iam::215406114230:policy/automation1551712932",
         "policy" : "aws61policy",
         "traffic_type" : "CloudApp",
         "count" : 1,
         "region_id" : "",
         "policy_id" : 3,
         "action" : "alert",
         "sa_rule_severity" : "2",
         "cci" : 94,
         "account_id" : "215406114230",
         "sa_profile_id" : -1001000,
         "site" : "Amazon Web Services",
         "appcategory" : null,
         "_insertion_epoch_timestamp" : 1551713763,
         "category" : null
      }
   ],
   "status" : "success"
}

Query for DLP violations grouped by user:

POST https://<tenant-URL>/api/v1/report?query=alert_type eq DLP&type=alert&groupby=user&timeperiod=2592000

Set endpoint name as report
Set query=alert_type eq DLP to query for DLP alerts
Set type=alert to query for DLP alerts
Set groupby=user