Get Results of Prior DLP Inspection

This API is used to get the results of a previous DLP inspection of content by checking the DLP cache. No content is sent in this request so sending it before starting an inspection job can result in a significant savings both in time and bandwidth. This endpoint only works for verdict type: summary or 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/cachelookup

Call Example

curl -X 'POST' \
  'https://10.0.0.1/inspections/cachelookup' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "profiles": [
    "DLP-PCI",
    "DLP-PII"
  ],
  "content_ids": [
    "b1f793e4d4a26ac7b695bb1fd1fb0ce3cb5d729c401d8528f8bb92598006cf85"
  ],
  "results": {
    "verdict": "verdict"
  }
}'

Response Example

#200 Response

[
  {
    "content_id": "b1f793e4d4a26ac7b695bb1fd1fb0ce3cb5d729c401d8528f8bb92598006cf85",
    "cached_profiles": [
      "string"
    ],
    "uncached_profiles": [
      "string"
    ],
    "result_data": {
      "status": "success",
      "status_info": "Text extraction was skipped.",
      "summary": {
        "verdict": "hit",
        "verdict_type": "full",
        "severity": "low",
        "profiles": [
          "DLP-PCI",
          "DLP-PII"
        ],
        "transaction_id": "93434304"
      },
      "results": [
        {
          "bypassed_profiles": [
            "DLP-PCI",
            "DLP-PII"
          ],
          "metadata": {
            "subfile": false,
            "file_id": 1,
            "name": "pci-hit.txt",
            "size": 811,
            "sha256": "b2e68f87b6d17de54f4ab8a1e59f36619211558ab0f301f921c4b575edc792ea",
            "language": "ENGLISH",
            "type": "Plain Text file",
            "category": "Text",
            "mime_type": "text/plain",
            "protection": {
              "encryption": {
                "file_typing": true,
                "classification": true,
                "classification_score": 0.95
              },
              "microsoft_aip": {
                "status": "protected"
              }
            },
            "drm": {
              "labels": [
                {
                  "id": "c7d03ebd-804d-489c-94c6-8167224c3c1b",
                  "name": "chris_encryption_all_enabled",
                  "instance": "epdlpsjc1",
                  "vendor": "mip",
                  "data_classification_label": "mip/epdlpsjc1/chris_encryption_all_enabled"
                }
              ]
            }
          },
          "matches": [
            {
              "id": "4826568926313255945",
              "cached": false,
              "profile": "string",
              "action_threshold_met": true,
              "maximum_severity": "low",
              "rules": [
                {
                  "name": "Name-Credit Card (CC)",
                  "severity": "low",
                  "type": "entity",
                  "entity": {
                    "weighted": "false",
                    "score": 1,
                    "limit_reached": false,
                    "entities_summary": [],
                    "matches_count": 2,
                    "sensitivity_level": "high",
                    "unique_count": 8
                  },
                  "structured_classification": {
                    "entities_summary": [],
                    "matches_count": 2,
                    "sensitivity_level": "high",
                    "data_type": "Personal Names"
                  },
                  "fingerprint": {
                    "classification": "tbd",
                    "match": "tbd",
                    "score": 1
                  },
                  "fingerprint_group": {
                    "match": "/path/to/matched/file.txt",
                    "score": 90
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful.	Inline
400	Bad Request	The request was invalid. The response contains the error that caused the request to be rejected, if available.	string
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 performing the request.	None

Response Schema

Status Code 200

An array of inspection results, one for each content ID specified in the request.

Name	Type	Required	Restrictions	Description
» content_id		true	none	SHA256 hash of the content that has been sent.
» cached_profiles	[string]	true	none	The list of profiles that were found in the cache for this content ID.
» uncached_profiles	[string]	true	none	The list of profiles that were not found in the cache for this content ID.
» result_data	object	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 hit. 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. 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	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