Enterprise Recon v1 API

All Documentation > Enterprise Recon v1 API > Match Details

Match Details

Use this set of APIs to retrieve detailed information about matches and match chunks found in files.

List Objects with Matches

Get detailed information about folder and files that contain matches for a given Target. Returned results include object details, remediation log, summary of matches found within the file (e.g. breakdown by match type and data type), and a list of all the match locations within the file.

Request

GET

https://er-master:8339/v1/targets/<target_id>/matchobjects

Authorization

Basic Authentication

User Permissions

Pre-requisite: Allow API Access
Global permissions: Global Admin, Classification Admin
Resource permissions: Classification, Access Control, Reporting - Detailed Reporting, Remediate

Path Parameters

Parameter	Data Type	Description
target_id	string	Specify Target to retrieve data for. target_id is the targets->id response item from the /v1/groups/all endpoint.

Query Parameters

Parameter	Data Type	Description
location_id	string	Filter results for a specific Target Location. If no value is specified, response returns data for all Target Locations under the given target_id. location_id is the targets->locations->id response item from the /v1/groups/all endpoint.
data_types	string example: data_types=Email+addresses	List results for specific matched data types. If the data type value is not valid, results will be returned for all data types. Refer to the name response item from the /v1/datatypes/builtins endpoint.
remediation_status	string example: remediation_status=partially+masked	Filter results for specific remediation or operation status. If the remediation or operation status value is not valid, results will be returned for all statuses. See Operation Status for the full list of supported Enterprise Recon operation statuses.
sort_by	string enum: label owner matches status example: sort_by=status	Sort file records by path label, owner, match count or remediation status. By default records are sorted by label.
descending	boolean default: false enum: true false	Set true to sort records in descending order.
file_name	string	Filter results by matching file names.
offset	integer default: 0	The first file containing matches to return data for. For offset=N, data will be fetched starting from the Nth file containing matches. If no value is specified or offset=0, query will return data from the very first file containing matches. Sorting of records is dependent on the sort_by and descending parameter values.
limit	integer <days> default: 1000 max: 100000	Maximum number of file containing matches to return data for, starting from the first record determined by the offset parameter value.
details	boolean default: false	Show (true) or hide (false) certain details for matched files (e.g. summary of remedial actions and summary of matched data types).

Header Parameters

Parameter	Data Type	Description
Accept-Encoding	string enum: gzip deflate	Specify the compression algorithm to use on the response object. Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Parameter

Data Type

Description

Accept-Encoding

string

enum: gzip deflate

Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP

GET /v1/targets/5776191921548943090/matchobjects?details=true
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/targets/4759598330602895744/matchobjects?details=true&data_types=Login+credentials,Email+addresses' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
id	integer	This object ID is automatically assigned to each file when a match is found. Example: A ZIP file contains "FileA.txt" and "FileB.txt", and matches were found in both files. "FileA.txt" and "FileB.txt" would both be assigned a separate id, but no id will be returned for the ZIP file.
path	string	Path to the file containing matches.
owner	string	User name of the file owner.
last_remediation_event	object	Details on the last remedial action or operation that was performed for a matched file. Object is not returned if: No remedial actions or operations have been taken, or The location is rescanned (except for locations that have been remediated as "False Match" or "Test Data").
last_remediation_event/jobid	integer	Remediation or operation job ID. This is assigned automatically when a remediation action or operation is performed.
last_remediation_event/sign_off	string	Details entered by user in the Sign-Off field when remedial action or operation was taken.
last_remediation_event/reason	string	Details entered by user in the Reason field when the remedial action or operation was taken.
last_remediation_event/remediation_status	string	Remediation or operation status for the file. See Operation Status for the full list of supported Enterprise Recon operation statuses.
last_remediation_event/error	string	Remediation or operation error. Not returned if there is no remediation or operation error.
summary	object	Breakdown of match details found in a file and remedial action taken. Returned if details=true.
summary/data_type	string	Data type for matched pattern.
summary/remediation_status	string	Remediation status for the file.
summary/matches	object	Breakdown of matches for the by match type.
summary/matches/test	string	Total number of matches containing test data patterns.
summary/matches/match	string	Total number of matches with data privacy breach patterns.
summary/matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
summary/purge	object	Breakdown of matches that have been remediated for the file.
summary/purge/test	string	Number of matched test data patterns in the file that have been remediated.
summary/purge/match	string	Number of matched data privacy breach patterns in the file that have been remediated.
summary/purge/prohibited	string	Number of matched prohibited PCI data patterns in the file that have been remediated.
subpath	object	Detailed match information for files contained within other files. For example, matches were found in "FileA.txt" which is contained within a ZIP file. "FileA.txt" details would be listed under subpath. The details one level above would be describing the ZIP file.
subpath/id	integer	This object ID is automatically assigned to each file when a match is found. Example: A ZIP file contains "FileA.txt" and "FileB.txt", and matches were found in both files. "FileA.txt" and "FileB.txt" would both be assigned a separate id, but no id will be returned for the ZIP file.
subpath/path	string	Path to the file containing matches.
subpath/owner	string	User name of the file owner.
subpath/last_remediation_event	object	Details on the last remedial action or operation that was performed for a matched file. Object is not returned if: No remedial actions or operations have been taken, or The location is rescanned (except for locations that have been remediated as "False Match" or "Test Data").
subpath/last_remediation_event/jobid	integer	Remediation or operation job ID. This is assigned automatically when a remediation action or operation is performed.
subpath/last_remediation_event/sign_off	string	Details entered by user in the Sign-Off field when remedial action or operation was taken.
subpath/last_remediation_event/reason	string	Details entered by user in the Reason field when the remedial action or operation was taken.
subpath/last_remediation_event/remediation_status	string	Remediation or operation status for the file. See Operation Status for the full list of supported Enterprise Recon operation statuses.
subpath/last_remediation_event/error	string	Remediation or operation error. Not returned if there is no remediation or operation error.
subpath/summary	object	Breakdown of match details found in a file and remedial action taken. Returned if details=true.
subpath/summary/data_type	string	Data type for matched pattern.
subpath/summary/remediation_status	string	Remediation status for the file.
subpath/summary/matches	object	Breakdown of matches for the by match type.
subpath/summary/matches/test	string	Total number of matches containing test data patterns.
subpath/summary/matches/match	string	Total number of matches with data privacy breach patterns.
subpath/summary/matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
subpath/summary/purge	object	Breakdown of matches that have been remediated for the file.
subpath/summary/purge/test	string	Number of matched test data patterns in the file that have been remediated.
subpath/summary/purge/match	string	Number of matched data privacy breach patterns in the file that have been remediated.
subpath/summary/purge/prohibited	string	Number of matched prohibited PCI data patterns in the file that have been remediated.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
  "id": "5136",
  "path": "/usr/share/folder1/myfile.tar.gz",
  "owner": "root",
  "summary": [
    {
      "data_type": "American Express",
      "matches": {
        "match": "28",
        "test": "14"
      },
      "purge": {
        "match": "14"
      }
    },
    {
      "data_type": "Mastercard",
      "matches": {
        "match": "18"
      },
      "purge": {
        "match": "18"
      }
    },
    {
      "data_type": "SWIFT Code",
      "matches": {
        "match": "10",
        "test": "5"
      },
      "purge": {
        "match": "10"
      }
    },
    {
      "data_type": "Personal Names (English)",
      "matches": {
        "match": "8"
      },
      "purge": {
        "match": "4"
      }
    }
  ],
  "subpaths": [
    {
      "path": "(gzip)",
      "owner": "root",
      "summary": [
        {
          "data_type": "SWIFT Code",
          "matches": {
            "match": "10"
          }
        },
        {
          "data_type": "American Express",
          "matches": {
            "match": "28"
          }
        },
        {
          "data_type": "Mastercard",
          "matches": {
            "match": "18"
          }
        },
        {
          "data_type": "Personal Names (English)",
          "matches": {
            "match": "8"
          }
        }
      ],
      "subpaths": [
        {
          "id": 5168,
          "path": "BANK/SWIFT-5.txt",
          "owner": "root",
          "last_remediation_event": {
            "job_id": "1542403861",
            "sign_off": "Masked by UserA",
            "reason": "Masked data",
            "remediation_status": "masked"
          },
          "summary": {
            "data_type": "SWIFT Code",
            "matches": {
              "match": "10",
              "test": "5"
            },
            "remediation_status": "masked",
            "purge": {
              "match": "10"
            }
          }
        },
        {
          "id": 5170,
          "path": "CHD/all-51.dump",
          "owner": "root",
          "last_remediation_event": {
            "job_id": "1541633861",
            "sign_off": "Test Data marked by UserA",
            "reason": "test data",
            "remediation_status": "test data"
          },
          "summary": {
            "data_type": "American Express",
            "matches": {
              "match": "28",
              "test": "14"
            },
            "remediation_status": "test data",
            "purge": {
              "match": "14"
            }
          }
        },
        {
          "id": 5172,
          "path": "CHD/mastercard-9.csv",
          "owner": "root",
          "summary": {
            "data_type": "Mastercard",
            "matches": {
              "match": "18"
            },
            "remediation_status": "manually remediated",
            "purge": {
              "match": "18"
            }
          }
        },
        {
          "id": 5183,
          "path": "PII/EN-Names-4.txt",
          "owner": "root",
          "last_remediation_event": {
            "job_id": "1541633861",
            "sign_off": "False Match marked by UserA",
            "reason": "false match",
            "remediation_status": "false match"
          },
          "summary": {
            "data_type": "Personal Names (English)",
            "matches": {
              "match": "8"
            },
            "remediation_status": "false match",
            "purge": {
              "match": "4"
            }
          }
        }
      ]
    }
  ]
}

404 Not Found

Returned if invalid Target ID is provided.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found."
}

View Match Details by Object ID

Get detailed information about a specific file or folder that contains matches for a given Target. Returned results include objects details, remediation log, summary of matches found within the file (e.g. breakdown by match type and data type), and a list of all the match locations within the file.

Request

GET

https://er-master:8339/v1/targets/<target_id>/matchobjects/<object_id>

Authorization

Basic Authentication

User Permissions

Pre-requisite: Allow API Access
Global permissions: Global Admin, Classification Admin
Resource permissions: Classification, Access Control, Reporting - Detailed Reporting, Remediate

Path Parameters

Parameter	Data Type	Description
target_id	string	Specify Target to retrieve data for. target_id is the targets->id response item from the /v1/groups/all endpoint.
object_id	string	Get detailed match information for a specific file. object_id is the id or subpath->id response item from the /v1/targets/<target_id>/matchobjects endpoint.

Query Parameters

Parameter	Data Type	Description
data_types	string example: data_types=Email+addresses	List results for specific matched data types. If the data type value is not valid, results will be returned for all data types. Refer to the name response item from the /v1/datatypes/builtins endpoint.
remediation_status	string example: remediation_status=partially+masked	Filter results for specific remediation or operation status. If the remediation or operation status value is not valid, results will be returned for all statuses. See Operation Status for the full list of supported Enterprise Recon operation statuses.
details	boolean default: false	Show (true) or hide (false) certain meta information and match details for a file (e.g. length of matched data and contextual data for the match).

Parameter

Data Type

Description

data_types

string

example: data_types=Email+addresses

List results for specific matched data types. If the data type value is not valid, results will be returned for all data types. Refer to the name response item from the /v1/datatypes/builtins endpoint.

remediation_status

string

example: remediation_status=partially+masked

Filter results for specific remediation or operation status. If the remediation or operation status value is not valid, results will be returned for all statuses. See Operation Status for the full list of supported Enterprise Recon operation statuses.

details

boolean

default: false

Show (true) or hide (false) certain meta information and match details for a file (e.g. length of matched data and contextual data for the match).

Header Parameters

Parameter	Data Type	Description
Accept-Encoding	string enum: gzip deflate	Specify the compression algorithm to use on the response object. Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Parameter

Data Type

Description

Accept-Encoding

string

enum: gzip deflate

Request Samples

HTTP

GET /v1/targets/5776191921548943090/matchobjects/5136?details=true
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/targets/4759598330602895744/matchobjects/5136?details=true' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
id	string	The object ID for matched file.id is the id or subpath->id respose item from the /v1/targets/<target_id>/matchobjects endpoint.
target_id	string	Unique Target ID identifying the Target where the matched file belongs to. This ID is unique 20 digit number.
path	string	Path to the file containing matches.
overflow	boolean enum: true false	Returns true if there is an overflow and not all chunks or meta data is stored for all matched objects.
matches	object
matches/content	string	Matched data pattern.
matches/offset	integer	Byte offset of the matched pattern in the file.
matches/length	integer	Length of matched pattern.
matches/data_type	string	Data type for the matched pattern.
matches/severity	string enum: test match prohibited	Describes the severity of the matched data pattern. test: match contains known test data patterns. match: match contains data privacy breach data patterns. prohibited: match contains prohibited PCI data patterns.
chunks	object	Context data surrounding the matched data pattern. Returned if details=true.
chunks/content	string	Describes the number of bytes omitted before a match is found in a file and shows the contextual data surrounding the matched data pattern captured during the scan.
chunks/offset	integer	Byte offset in the file for the current chunk of data.
chunks/length	integer	Length of the data chunk.
metas	object	Meta data for the matched object. Returned if details=true. See Metadata for the list of possible ER2 metadata values.
metas/label	string	Label describing specific information about the matched file.
metas/value	string	Describes the value for a given metadata.
metas/is_aggregate	boolean enum: true false	true if the label describes a data type, false for all other labels.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
  "id": "5136",
  "target_id": "2047655813564067948",
  "path": "file:///usr/share/centos_share/BANK/data.txt",
  "overflow": false,
  "matches": [
    {
      "content": "DIBKRUMM697",
      "offset": 202,
      "length": 11,
      "data_type": "SWIFT Code",
      "severity": "match"
    },
    {
      "content": "SLHI US 3H876",
      "offset": 214,
      "length": 13,
      "data_type": "SWIFT Code",
      "severity": "match"
    },
    {
      "content": "HSBC GB2L423",
      "offset": 228,
      "length": 12,
      "data_type": "SWIFT Code",
      "severity": "match"
    },
    {
      "content": "ISRAILIJ835",
      "offset": 241,
      "length": 11,
      "data_type": "SWIFT Code",
      "severity": "match"
    },
    {
      "content": "CTBAAU2S196",
      "offset": 253,
      "length": 11,
      "data_type": "SWIFT Code",
      "severity": "match"
    }
  ],
  "chunks": [
    {
      "content": "80 bytes omitted",
      "offset": 0,
      "length": 80
    },
    {
      "content": "or a given Target. \nReturned results include objects details, remediation log, summary of matches found within the file.\n\nDIBKRUMM697\nSLHI US 3H876\nHSBC GB2L423\nISRAILIJ835\nCTBAAU2S196\n\nEnd of file.",
      "offset": 80,
      "length": 199
    }
  ],
  "metas": [
    {
      "label": "SWIFT Code",
      "value": "5",
      "is_aggregate": true
    },
    {
      "label": "File owner",
      "value": "root",
      "is_aggregate": false
    },
    {
      "label": "File modified",
      "value": "Apr, 16 2018 16:55",
      "is_aggregate": false
    },
    {
      "label": "File created",
      "value": "Apr, 16 2018 16:47",
      "is_aggregate": false
    }
  ]
}

404 Not Found

Returned if invalid Target ID or Object ID is provided.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found."
}