This API endpoint is used to synchronously perform a DLP Content Inspection and retrieve the results. If the content inspection exceeds the maximum timeout of 10 seconds, a HTTP 200 is returned with the status field set to ‘timeout’. This call only supports the following verdict types: summary and details.
This endpoint has some additional limitations:
- Max File Size: 1 megabyte
- Timeout: 10 seconds
- Max DLP Profiles: 100
- Character Length of Each Profile name: 256 characters
Request Endpoint
POST
https://<appliance_ip>/inspections
Call Example
curl -X 'POST' \
'https://10.0.0.1/inspections' \
-H 'accept: multipart/mixed' \
-H 'Content-Type: multipart/form-data' \
-H 'x-netskope-generate-incidents: true' \
-F 'request={"profiles":["DLP-PCI","DLP-PII"],"content":{"id":"b1f793e4d4a26ac7b695bb1fd1fb0ce3cb5d729c401d8528f8bb92598006cf85","name":"SecretFile.txt","object_id":"AA-74GXZ","true_file_type":230},"modules":{"file_filter":{"skip":true},"drm":{"labels":[{"id":"c7d03ebd-804d-489c-94c6-8167224c3c1b","name":"chris_encryption_all_enabled","instance":"epdlpsjc1","vendor":"mip"}]}},"results":{"verdict":"summary"},"sender":{"app_name":"AWS_RDS"}}' \
-F 'content=@dlp.txt;type=text/plain'
Response Example
#200 Example Indicates a successful response, and the results are provided in multiple multipart/mixed parts.
The request header x-netskope-generate-incidents is added so that users can specify their choice for generating alerts & incidents.
The response headers have also been created: x-netskope-incidents-posted. The response header reflect whether the alerts and incidents were posted to the management plane.
Valid Query Parameters:
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » request | body | object | true | Specifies the properties of an synchronous inspection request. |
| »» profiles | body | true | A list of profiles to use during the scan. Profiles determine which DLP rules are used when searching for matches. | |
| »» content | body | true | Describes the content that is being sent to DLP as part of the request. | |
| »»» id | body | string | true | SHA256 hash of the content that has been sent. |
| »»» name | body | string | false | The name (e.g. filename) of the data. |
| »»» object_id | body | string | false | An object identifier for the data. |
| »»» true_file_type | body | integer | false | Netskope true file type (numerical ID) |
| »» modules | body | false | Specifies settings for individual DLP modules that will be used during the inspection. | |
| »»» file_filter | body | object | false | Specifies settings for the File Filter module. |
| »»»» skip | body | boolean | false | If true file filtering will be skipped. |
| »»» drm | body | object | false | Allows for explicit DRM labels to be passed into DLP. |
| »»»» labels | body | [object] | true | none |
| »»»»» id | body | string | true | The id of the label. |
| »»»»» name | body | string | false | The name of the label. |
| »»»»» instance | body | string | false | The instance of the label. |
| »»»»» vendor | body | string | true | The vendor of the label. |
| »» results | body | object | false | Specifies properties for the DLP On Demand results returned from the inspection. |
| »»» verdict | body | string | false | Specifies how much match detail should be returned. One of the following will be returned: summary – Summary of the verdict is returned. This will include the outcome, verdict type, list of the profiles, severity. details – Includes match details. Details about verdict has result matches, profile and rules per file. forensics – Includes summary, details and forensics of the matches. All match details including rule information, matched text and extracted content will be returned. Please note that this will cause a full scan of the file. If no verdict is specified, it would default to summary type and the summary of the verdict will be returned. |
| »» sender | body | false | Describes the request caller. | |
| »»» app_name | body | string | true | Application that triggered the call |
| » content | body | string(binary) | true | none |
Enumerated Values
| Parameter | Value |
|---|---|
| »»» verdict | summary |
| details |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Indicates a successful response, and the results are provided in multiple multipart/mixed parts. | Inline |
| 400 | Bad Request | The request was invalid. The response contains the error that caused the request to be rejected, if available. | string |
| 413 | Payload Too Large | The specified content is too large to be scanned. | None |
| 500 | Internal Server Error | An error occurred while performing the request. The response contains the error that caused the request to be rejected, if available. | string |
| 503 | Service Unavailable | No resources are available to perform the request. | None |
Response Schema
Status Code 200
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » result_data | false | none | Contains the overall result of the inspection. This includes the status of the inspection and any matches produced as a result of the inspection. | |
| »» status | true | none | Specifies the status of a scan request. success – The content was inspected successfully. timeout – The content inspection took too long and was timed out. error – An error occurred while performing the content inspection. | |
| »» status_info | string | false | none | Additional information about the status. For example, if status is error, this field may be present to provide details about the error that occurred. |
| »» summary | false | none | none | |
| »»» verdict | string | true | none | The verdict. One of: hit no_hit |
| »»» verdict_type | string | true | none | The verdict type. One of: full partial |
| »»» severity | string | false | none | The severity of the rule. One of: none low medium high critical |
| »»» profiles | true | none | A list of profiles to use during the scan. Profiles determine which DLP rules are used when searching for matches. | |
| »»» transaction_id | string | true | none | The transaction ID for this match. |
| »» results | [object] | false | none | When a scan completes successfully (status is success) this field may be present. It contains an array of entries – one for each file/subfile in the content that was scanned. Only files/subfiles that had rule matches or could not be scanned because they were protected will show up here. Files that were scanned but did not meet one of these two conditions do not appear here. |
| »»» bypassed_profiles | [string] | false | none | Specifies the list of profiles from the request that were bypassed because the file being scanned was protected in some way. If this field is not present, no profiles were bypassed. |
| »»» metadata | object | true | none | Metadata about the inspected content. |
| »»»» subfile | boolean | true | none | If a container file is passed to DLP, the subfiles within it are also scanned. If this field is true the match is for a subfile. If this field is false, either the content passed to DLP was not a container or the match was on the container itself. |
| »»»» file_id | integer | false | none | The internal identifier of the file/subfile. |
| »»»» name | string | false | none | The name (e.g. file name), if any, of the inspected content. |
| »»»» size | integer(uint64) | false | none | The size in bytes of the file/subfile. |
| »»»» sha256 | string | false | none | The SHA256 hash of the inspected content. |
| »»»» language | string | false | none | The detected language of the inspected content. |
| »»»» type | string | false | none | The detected type of the inspected content. |
| »»»» category | string | false | none | The detected category of the inspected content. |
| »»»» mime_type | string | false | none | The MIME type of the inspected content. |
| »»»» protection | object | false | none | The field is present when the content is protected in some way. The protection may include one or both of encryption and microsoft_aip. |
| »»»»» encryption | object | false | none | The content is encrypted. No match data can be produced for encrypted content. |
| »»»»»» file_typing | boolean | false | none | Encrypted content detected with file typing. |
| »»»»»» classification | boolean | false | none | Encrypted content detected with classification. |
| »»»»»» classification_score | number(double) | false | none | The score of encrypted content detected with classification. |
| »»»»» microsoft_aip | object | false | none | The content is Microsoft AIP protected. If the content can be unprotected, it will be inspected and match data may be produced. If it cannot be unprotected match data cannot be produced. |
| »»»»»» status | string | true | none | The Microsoft AIP protection status: protected: The content could not be unprotected, and was not inspected. unsanctioned: The content was AIP protected outside of a known MIP infrastructure and therefore could not be unprotected and was not inspected. sanctioned: The content was AIP protected by a known MIP infrastructure. Such content may be uprotected and scanned. It also may have DRM labels extracted. |
| »»»» drm | object | false | none | The content is protected by a DRM system. |
| »»»»» labels | [object] | true | none | An array of DRM label objects that contain detailed DRM label information. |
| »»»»»» id | string | true | none | The id of the label. |
| »»»»»» name | string | true | none | The name of the label. |
| »»»»»» instance | string | true | none | The instance of the label. |
| »»»»»» vendor | string | true | none | The vendor of the label. |
| »»»»»» data_classification_label | string | true | none | The data classification label. |
| »»» matches | [object] | false | none | An array of match entry objects that contain detailed DLP match information. |
| »»»» id | string | false | none | The match identifier. If this is a cached match, this will be set to the id of the previous match. Otherwise this field is a new identifier that DLP will use to refer to the match if it is seen in the future. Furthermore, for a non-cached response there will be a corresponding extracted_text multipart/mixed part returned for this file and this value will be set in the name field of the Content-Disposition header for that part. |
| »»»» cached | boolean | true | none | If true, this match was found in the DLP cache, meaning the content has already been scanned for this profile and thus was not scanned as part of this request. id is set to the id that was created when the content was scanned. Because of this, there will be no forensics associated with the match as forensic data is not stored in the DLP cache. |
| »»»» profile | any | true | none | none |
allOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»»»» anonymous | false | none | The name of the profile. |
and
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»»»» anonymous | any | false | none | The profile to which the matched rules are attached. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»»» action_threshold_met | boolean | true | none | If true, the action threshold was met indicating that the DLP Client should perform the action associated with this profile. If this field is false the action threshold was not met and the action associated with this profile should not be performed. |
| »»»» maximum_severity | string | false | none | The maximum severity of the matched rules. |
| »»»» rules | [object] | false | none | none |
| »»»»» name | string | true | none | The name of the rule. |
| »»»»» severity | string | true | none | The severity of the rule: none, low, medium, high, or critical |
| »»»»» type | string | true | none | The type of the rule. One of: entity: A rule that matches when a specific entity is found. For these rule matches the entity subfields will be present. not_entity: A rule that matches when a specific entity is not found. For these rule matches the entity subfields will be present. file_filter: A file filter rule. classification A classification rule. fingerprint A fingerprint rule. For these rule matches the fingerprint subfields will be present. fingerprint_group: A fingerprint 2.0 group rule. For these rule matches the fingerprint_group subfields will be present. structured_classification: A structured classification rule. For these rule matches the structured_classification subfields will be present. |
| »»»»» entity | object | false | none | Contains details about the entity rule that matched. This field is present when type is entity or not_entity. |
| »»»»»» weighted | boolean | true | none | If true this rule is using the weighted score to determine the severity. If false, count is being used. |
| »»»»»» score | integer | true | none | The weighted score of the rule matches. |
| »»»»»» limit_reached | boolean | true | none | If true the maximum number of matches for this rule was reached. This means that some identified data was omitted from the results. |
| »»»»»» entities_summary | true | none | An array of the matched entities and the corresponding counts for those entities. | |
| »»»»»»» entity | string | true | none | The name of the entity that resulted in a match. |
| »»»»»»» count | integer | true | none | The number of times the given entity was matched. |
| »»»»»»» data_type | string | false | none | General data type describing this entity. |
| »»»»»»» sensitivity_level | string | true | none | How sensitive of a match is this entity. One of not_sensitive low medium high critical |
| »»»»»» matches_count | integer | true | none | The count of entity rule matches. |
| »»»»»» sensitivity_level | true | none | How sensitive of a match is this entity. One of: not_sensitive low medium high critical | |
| »»»»»» unique_count | integer | false | none | The number of unique entries that matched the rule. This field is only present when the profile specifies that rules should be uniquely counted. |
| »»»»» structured_classification | object | false | none | Details of a matched classification type rule |
| »»»»»» entities_summary | true | none | An array of the matched entities and the corresponding counts for those entities. | |
| »»»»»» matches_count | integer | true | none | The count of entity rule matches. |
| »»»»»» sensitivity_level | true | none | How sensitive of a match is this entity. One of not_sensitive low medium high critical | |
| »»»»»» data_type | false | none | General data type describing this entity. | |
| »»»»» fingerprint | object | false | none | This field is present when type is fingerprint. |
| »»»»»» classification | string | true | none | The classification that matched. |
| »»»»»» match | string | true | none | The file that matched. |
| »»»»»» score | integer | true | none | The score of the matched finterprint. |
| »»»»» fingerprint_group | object | false | none | This field is present when type is fingerprint_group. |
| »»»»»» match | string | true | none | The fingerprinted file that matched. |
| »»»»»» score | integer | true | none | The similarity score of matched fingerprinted file. |
| »»» forensics | object | false | none | none |
| »»»» extracted_text | string(string) | false | none | String identifier used to correlate the extracted text with its corresponding part in the multipart response |
| »»»» entity_rule_matches | string(string) | false | none | String identifier used to correlate the entity rule matches with its corresponding part in the multipart response. |
| »»»» preview_image | string(string) | false | none | String identifier used to correlate the preview image with its corresponding part in the multipart response. |
| »»»» original_subfile | string(string) | false | none | String identifier used to correlate the original subfile with its corresponding part in the multipart response. |
Enumerated Values
| Property | Value |
|---|---|
| InspectionStatus: status | success |
| timeout | |
| error | |
| verdict | hit |
| no_hit | |
| verdict_type | full |
| partial | |
| severity | none |
| low | |
| medium | |
| high | |
| critical | |
| MicrosoftAipProtectionStatus: status | protected |
| unsanctioned | |
| sanctioned | |
| severity | none |
| low | |
| medium | |
| high | |
| critical | |
| type | entity |
| not_entity | |
| file_filter | |
| classification | |
| fingerprint | |
| fingerprint_group | |
| structured_classification | |
| sensitivity_level | not_sensitive |
| low | |
| medium | |
| high | |
| critical |
This operation does not require authentication