Get Alerts Data

Get Alerts Data

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:

KeyValueDescription
tokenstringRequired. 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.
queryValid 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.
typeanomaly | 'Compromised Credential' | policy | 'Legal Hold' | malsite | Malware | DLP | 'Security Assessment' | watchlist | quarantine | Remediation | ubaSelects Policy, DLP, Quarantine, Watchlist, etc. alerts. If nothing is passed, then it gets alerts of all types.
ackedtrue | falseSelects the type of alerts. If nothing is passed, then it gets alerts of all types.
timeperiod3600 | 86400 | 604800 | 2592000Last 60 mins | Last 24 Hrs | Last 7 Days | Last 30 Days | Last 60 days | Last 90 days

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

starttimeUnix epoch timeRestrict 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.

endtimeUnix epoch timeRestrict alerts to those that have timestamps less than or equal to this. Needed only if timeperiod or insertionstarttime/insertionendtimeis not passed.
insertionstarttimeUnix epoch timeRestrict 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.

insertionendtimeUnix epoch timeRestrict alerts which have been inserted into the database before the specified time. Needed only if timeperiod or starttime/endtime is not passed.
limitPositive integer less than 5000REST API responses can return up to 10000 alerts in a single response. You can use pagination to retrieve more results.
skipPositive integerSkip over some of the alerts (useful for pagination in combination with limit).
unsortedtrue | falseIf true, the returned data will not be sorted (useful for improved performance).

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
Share this Doc

Get Alerts Data

Or copy link

In this topic ...