This API is an asynchronous endpoint for scheduling DLP (Data Loss Prevention) content inspection jobs. This API accepts content for inspection and returns either a job ID for asynchronous processing or immediate results from cache if available.
This endpoint has some additional limitations:
- Max File Size: 1 megabyte
- Max DLP Profiles: 100
- Character Length of Each Profile name: 256 characters
Request Endpoint
POST
https://<appliance_ip>/inspections/jobs
Call Example
curl -X 'POST' \
'https://10.0.0.1/inspections/jobs' \
-H 'accept: multipart/form-data' \
-H 'x-netskope-generate-incidents: true' \
-H 'Content-Type: multipart/form-data' \
-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=@SecretFile.txt;type=text/txt'
Response Example
#A cached hit was found, therefore no job was scheduled. The results are returned in json.
#200 Response
HTTP/1.1 200 OK
Content-Type: multipart/form-data; boundary=8b9eb155309408d78d1886c2af2803fdba94a7bea3dac274b3da5fa31e92
--8b9eb155309408d78d1886c2af2803fdba94a7bea3dac274b3da5fa31e92
Content-Disposition: form-data; name="result_data"
Content-Type: application/json
{"status":"success","summary":{"profiles":["DLP-PCI","DLP-PII"],"transaction_id":"3947352303853909965","verdict":"hit","verdict_type":"full"}}
--8b9eb155309408d78d1886c2af2803fdba94a7bea3dac274b3da5fa31e92--
#No prior request is found and a new job is started.
#202 Response
{
"job_id": "8a426a5f-0d2e-0a2e-3595a-303202a7a2e"
}
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 are:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | none |
| » request | body | object | true | Specifies the properties of an 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 |
| »»» name | body | string | false | The name (e.g. filename) of the content. |
| »»» 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 | |
| forensics |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | A prior request is found and this is a cached response. The results are returned in json. | Inline |
| 202 | Accepted | Indicates that the request has been accepted. This is the normal, expected result. | 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 |
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 hit. One of: none low medium high 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 | false | none | General data type describing this entity. | |
| »»»»»»» sensitivity_level | true | none | The severity of the rule hit. One of: none 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 |
Status Code 202
This object is returned to the DLP On Demand Appliance for an asynchronous inspection request to indicate that DLP has accepted the request and will process it asynchronously.
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » job_id | true | none | A request-specific token. |
This operation does not require authentication