Enterprise Recon v1 API
Investigate Query
Use this set of APIs to create queries to the Master Server, and retrieve a filtered list of Targets and Target locations that match those queries.
Create a New Query
Create a new Master Server query. Define the filters and sorting parameters in the request body to only return Target locations that fulfil those criteria. If no filters are defined, the query will include all Targets and locations.
The "OR" operator is used to evaluate multiple filter selections within a single filter category, where a match location is included in the result set if it matches any of the filter selections within a filter category.
The "AND" operator is used to evaluate filter selections across multiple filter categories, where a match location is only included in the result set if it matches at least one filter selection across all filter categories.
Request
POST
https://er-master:8339/v1/query
Authorization
Request Schema
Response Item | Data Type | Description |
---|---|---|
prefix |
string <array> enum: file mariadb memory https |
Array of location prefix or protocol values. Match locations that match any of the specified location prefixes will be returned in the query results set. For the list of Enterprise Recon supported protocols, refer to Protocols. |
search |
string example: table_ |
Specify a search string. Match locations that contain the specified string in the path will be returned in the query results set. |
risk_profile |
string <array> |
Array of risk_profile_id values. Match locations associated with the specified risk profiles will be returned in the query results set. risk_profile_id is the profile_id response item from the /v1/risk/profiles endpoint. Only available in Enterprise Recon PRO Edition. |
meta |
object <array> |
List of metadata types. |
meta/label |
string enum: Document Creator Document Created Document Modified Sender Date File Owner File Created File Modified |
Specify the label for the metadata type. Required if using the meta filter. |
meta/value |
string |
Specify the metadata value. Required if label is File Owner, Document Creator, or Sender. Example:
|
meta/start_date |
string <YYYYMMDD> |
Specify the first day for the metadata date range. Required if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the end_date parameter. Example 1:
Example 2:
To specify a 1-day range, set start_date = end_date.
|
meta/end_date |
string <YYYYMMDD> |
Last day for the metadata date range. Required if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the start_date parameter. Example:
To specify a 4-day range, set the
start_date and
end_date values as below.
|
classification_mip |
object |
List of methods and labels for the Data Classification with MIP feature. Only available in Enterprise Recon PRO Edition. |
classification_mip/method |
string <array> enum: Discovered Classified No classification |
Array of MIP classification methods / types. Match locations associated with the specified classification method will be returned in the query results set. Only available in Enterprise Recon PRO Edition. |
classification_mip/label |
string <array> |
Array of MIP Classification label_id values. Match locations associated with the specified classification labels will be returned in the query results set. label_id is the id response item from the /v1/classification/mip/labels endpoint. Only available in Enterprise Recon PRO Edition. |
target |
string <array> |
Array of target_id values. Match locations in any of the specified Targets will be returned in the query results set. target_id is the targets->id response item from the /v1/groups/all endpoint. |
group |
string <array> |
Array of group_id values. Match locations in any of the specified Groups will be returned in the query results set. group_id is the id response item from the /v1/groups/all endpoint. |
data_type |
string <array> example: Passport Number |
Array of data type name values. Match locations that match any of the specified data types will be returned in the query results set. Refer to the name response item from the /v1/datatypes/builtins endpoint. |
content_type |
string <array> example: Adobe Portable Document |
Array of content type or format values. Match locations in any of the specified content types or file formats will be returned in the query results set. For the possible values for the format field, refer to /v1/summary/fileformats. |
remediation_status |
string <array> example: False Match |
Array of remediation statuses. Match locations that match any of the specified remediation statuses will be returned in the query results set. See Operation Status for the full list of supported Enterprise Recon operation statuses. |
afconfig |
string <array> example: [Visa] OR [Mastercard] > 3 |
Array of advanced filter expressions. Match locations that
contain the data type combinations specified in the array of advanced
filters will be returned in the query results set.
See the Advanced Filters
documentation for more information.
You can use the \n
newline character to create multi-line Advanced Filters.
|
order |
string enum: location owner matches status signoff |
Sort the results by location path, owner, match count, remediation status, or sign-off. By default records are sorted by location. |
direction |
string default: asc enum: asc desc |
Set as asc to sort the results set in ascending order. Set as desc to sort the results set in descending order. |
Request Samples
Query to filter match locations by prefixes, targets, data types and remediation statuses. Returned results set will be sorted by location path in ascending order.
HTTP
POST /v1/query
Content-Type: application/json
{
"prefix": [
"file",
"memory",
"awss",
"http",
"https",
"mariadb",
"dropbox"
],
"target": [
"10772317491401920633",
"12455049915341638520",
"1760587494204816323",
"7011787595524148620"
],
"data_type": [
"American Express",
"Email addresses",
"JCB",
"Maestro",
"Mastercard",
"Visa",
"IP Address",
"Personal Names (English)"
],
"remediation_status": [
"confirmed match",
"manually remediated",
"masked",
"false match",
"test data",
"pending delete"
],
"order": "location",
"direction": "asc"
}
cURL
curl --request POST 'https://er-master:8339/v1/query' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
"prefix": [
"file",
"memory",
"awss",
"http",
"https",
"mariadb",
"dropbox"
],
"target": [
"10772317491401920633",
"12455049915341638520",
"1760587494204816323",
"7011787595524148620"
],
"data_type": [
"American Express",
"Email addresses",
"JCB",
"Maestro",
"Mastercard",
"Visa",
"IP Address",
"Personal Names (English)"
],
"remediation_status": [
"confirmed match",
"manually remediated",
"masked",
"false match",
"test data",
"pending delete"
],
"order": "location",
"direction": "asc"
}'
Query to filter match locations by content type or file formats, groups, and advanced filters. Returned results set will be sorted by match count in descending order.
HTTP
POST /v1/query
Content-Type: application/json
{
"content_type": [
"HTML/XML Document",
"ZIP Archive",
"Adobe Portable Document"
],
"group": [
"1586459843904882889",
"2579944969418384580",
"5200879556227018373",
"7740912712351551464",
"12498974227283943426"
],
"afconfig": [
"SET CHD_Data ([Visa], [Mastercard], [JCB], [Discover], [American Express]) \n MATCH (2, CHD_Data)"
],
"order": "matches",
"direction": "desc"
}
cURL
curl --request POST 'https://er-master:8339/v1/query' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
"content_type": [
"HTML/XML Document",
"ZIP Archive",
"Adobe Portable Document"
],
"group": [
"1586459843904882889",
"2579944969418384580",
"5200879556227018373",
"7740912712351551464",
"12498974227283943426"
],
"afconfig": [
"SET CHD_Data ([Visa], [Mastercard], [JCB], [Discover], [American Express]) \n MATCH (2, CHD_Data)"
],
"order": "matches",
"direction": "desc"
}'
Query to filter match locations by Enterprise Recon PRO-specific keys (risk_profile and classification_mip), metadata types, and data types. Returned results set will be sorted by location path in ascending order.
HTTP
POST /v1/query
Content-Type: application/json
{
"risk_profile": [
"455572488728221120",
"4520499404109630813"
],
"meta": [
{
"label": "Document Created",
"start_date": "20210301"
},
{
"label": "Document Created",
"end_date": "20210309"
}
],
"classification_mip": [
{
"method": [
"Discovered",
"No classification"
],
"label": [
"b65524dd-0680-42c8-8d54-5149e8d33034",
"abcdefgh-1234-ijkl-5678-mnopqrst9012"
]
}
],
"data_type": [
"American Express",
"Email addresses",
"JCB",
"Maestro",
"Mastercard"
],
"order": "location",
"direction": "asc"
}
cURL
curl --request POST 'https://er-master:8339/v1/query' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
"risk_profile": [
"455572488728221120",
"4520499404109630813"
],
"meta": [
{
"label": "Document Created",
"start_date": "20210301"
},
{
"label": "Document Created",
"end_date": "20210309"
},
],
"classification_mip": [
{
"method": [
"Discovered",
"No classification"
],
"label": [
"b65524dd-0680-42c8-8d54-5149e8d33034",
"abcdefgh-1234-ijkl-5678-mnopqrst9012"
]
}
],
"data_type": [
"American Express",
"Email addresses",
"JCB",
"Maestro",
"Mastercard"
],
"order": "location",
"direction": "asc"
}
Response Schema
201 Created
Response Item | Data Type | Description |
---|---|---|
query_id |
string |
Query ID assigned to the newly created filter query. This Query ID will expire if idle for more than 10 minutes. |
Response Samples
201 Created
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
"query_id": "17512466853234836070"
}
400 Bad Request
Returned if the value of the meta->label field is Document Created, Document Modified, Date, File Created, or File Modified, but the value for either the meta->start_date or the meta->end_date field is not specified in the request body.
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
"message": "Missing required field for 'meta'. Require both 'start_date' and 'end_date' fields."
}
403 Forbidden
Returned if the request body contains any Enterprise Recon PRO-specific keys (e.g. risk_profile, classification_mip), but the Enterprise Recon appliance does not have the required PRO Edition license.
HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
"message": "'{key}' is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please contact licensing@groundlabs.com"
}
404 Not Found
Returned if the specified values in the request body for the risk_profile_id, target_id, and group_id fields are invalid.
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
"message": "Specified 'risk profile | target | group | data type' does not exist."
}
422 Unprocessable Entity
Returned if the specified values in the request body for the content_type, prefix, remediation_status, order, direction, and classification_mip->method fields are invalid or have unsupported format.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
"message": "Invalid value for 'content_type | prefix | remediation_status | order | direction | classification method'."
}
422 Unprocessable Entity
Returned if (i) there is a specified value in the request body for the meta->label but no corresponding value for the meta->value field, (ii) there are duplicate values for the same meta field, or (iii) the specified values in the request body for the meta fields are invalid (e.g. both the meta->start_date and the meta->end_date fields are defined in a single object within the meta array).
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
"message": "Invalid value for 'meta'."
}
List All Targets by Query
Get a list of all the Targets that match the filters for a given query.
Request
GET
https://er-master:8339/v1/query/<query_id>/targets
Authorization
Path Parameters
Parameter | Data Type | Description |
---|---|---|
query_id |
string |
Retrieve a list of Targets that match the filter parameters defined in the specified Query ID. query_id is the response item from the /v1/query endpoint. |
Request Samples
HTTP
GET /v1/query/17512466853234836070/targets
Accept: application/json
cURL
curl --request GET 'https://er-master:8339/v1/query/17512466853234836070/targets' \
--user apiuser:password123 \
--header "Accept: application/json"
Response Schema
200 OK
Response Item | Data Type | Description |
---|---|---|
- |
string <array> |
List of Target IDs for Targets that match the filter parameters defined in the Query ID. |
Response Samples
200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
"1760587494204816323",
"7011787595524148620",
"4759598330602895744"
]
404 Not Found
Returned if the specified Query ID has expired after being idle for more than 10 minutes.
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
"message": "Resource not found."
}
Get Target Summary by Query
Get the summary for a Target that matches the filters for a given query.
Request
GET
https://er-master:8339/v1/query/<query_id>/targets/<target_id>
Authorization
Path Parameters
Parameter | Data Type | Description |
---|---|---|
query_id |
string |
Specify a Query ID. query_id is the response item from the /v1/query endpoint. |
target_id |
string |
Retrieve the summary for a specific Target that matches the filter parameters defined for the Query ID. target_id is the response item from the /v1/query/<query_id>/targets endpoint. |
Request Samples
HTTP
GET /v1/query/17512466853234836070/targets/4759598330602895744
Accept: application/json
cURL
curl --request GET 'https://er-master:8339/v1/query/17512466853234836070/targets/4759598330602895744' \
--user apiuser:password123 \
--header "Accept: application/json"
Response Schema
200 OK
Response Item | Data Type | Description |
---|---|---|
location |
string example: MY-WINDOWS-SERVER |
Target name. |
platform |
string example: Windows 10 64bit |
Platform name. Will not be returned if platform is unknown. |
search_time |
number |
Time stamp of the most recent search for the Target in Unix time format. |
search_status |
string enum: none searched indexing results preparing to scan processing blocked |
Most recent search status for the Target. See Search Status for the full list of possible values. |
scan_progress |
number |
Indicates the scan progress (percentage) for the Target. |
groups |
string |
Indicates the Group that the Target belongs to. |
errors |
object |
Breakdown of errors across the Target. |
errors/low |
integer |
Total number of low errors for the Target across all Target Locations. |
errors/alert |
integer |
Total number of alert errors for the Target across all Target Locations. |
errors/critical |
integer |
Total number of critical errors for the Target across all Target Locations. |
errors/intervention |
integer |
Total number of intervention errors for the Target across all Target Locations. |
matchdata |
object <array> |
Breakdown of matches for the Target by data type. |
matchdata/label |
string |
Data type name. |
matchdata/test |
string |
Total number of matches that are test data patterns. |
matchdata/match |
string |
Total number of matches that are data privacy breach patterns. |
matchdata/prohibited |
string |
Total number of matches that are prohibited PCI data patterns. |
Response Samples
200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
"location": "MY-UBUNTU-MACHINE",
"platform": "Linux Debian Jessie/Ubuntu Trusty 64 bit",
"search_status": "none",
"search_time": 1589172285,
"scan_progress": 100.000000,
"groups": [
"LINUX"
],
"errors": {
"low": "1",
"alert": "2",
"critical": "0",
"intervention": "1"
},
"matchdata": [
{
"label": "Gender (English)",
"test": "0",
"match": "16000",
"prohibited": "0"
},
{
"label": "United States Bank Account Number",
"test": "0",
"match": "16",
"prohibited": "0"
},
{
"label": "Japanese Bank Account Number (robust)",
"test": "0",
"match": "16",
"prohibited": "0"
},
{
"label": "Australian Bank Account Number (robust)",
"test": "0",
"match": "16",
"prohibited": "0"
},
{
"label": "Personal Names (Austrian)",
"test": "0",
"match": "48",
"prohibited": "0"
},
{
"label": "Maestro",
"test": "0",
"match": "16624",
"prohibited": "0"
},
{
"label": "Credentials password",
"test": "0",
"match": "32",
"prohibited": "0"
},
{
"label": "Personal Names (English)",
"test": "0",
"match": "2976",
"prohibited": "0"
},
{
"label": "Credentials username (robust)",
"test": "0",
"match": "64",
"prohibited": "0"
},
{
"label": "French CNI (robust)",
"test": "0",
"match": "480",
"prohibited": "0"
},
{
"label": "IP Address",
"test": "0",
"match": "16176",
"prohibited": "0"
},
{
"label": "Visa",
"test": "0",
"match": "23936",
"prohibited": "0"
},
{
"label": "Diners Club",
"test": "0",
"match": "2080",
"prohibited": "0"
},
{
"label": "JCB",
"test": "0",
"match": "142656",
"prohibited": "0"
},
{
"label": "American Express",
"test": "0",
"match": "13424",
"prohibited": "0"
},
{
"label": "Luxembourg Phone Number (robust)",
"test": "0",
"match": "128",
"prohibited": "0"
},
{
"label": "Mastercard",
"test": "0",
"match": "24512",
"prohibited": "0"
},
{
"label": "Email addresses",
"test": "0",
"match": "192144",
"prohibited": "0"
},
{
"label": "United States Social Security Number (robust)",
"test": "0",
"match": "192000",
"prohibited": "0"
},
{
"label": "Personal Names (German)",
"test": "0",
"match": "48",
"prohibited": "0"
},
{
"label": "Laser",
"test": "0",
"match": "9904",
"prohibited": "0"
},
{
"label": "Personal Names (Belgian)",
"test": "0",
"match": "416",
"prohibited": "0"
},
{
"label": "Personal Names (Netherlands)",
"test": "0",
"match": "944",
"prohibited": "0"
},
{
"label": "Private Label Card",
"test": "0",
"match": "38448",
"prohibited": "0"
},
{
"label": "Personal Names (French)",
"test": "0",
"match": "144",
"prohibited": "0"
},
{
"label": "Personal Names (Portuguese)",
"test": "0",
"match": "16",
"prohibited": "0"
},
{
"label": "Login credentials",
"test": "0",
"match": "112",
"prohibited": "0"
},
{
"label": "Swiss Social Security Number (robust)",
"test": "0",
"match": "1168",
"prohibited": "0"
},
{
"label": "Personal Names (Italian)",
"test": "0",
"match": "16",
"prohibited": "0"
}
]
}
404 Not Found
Returned if the specified Query ID has expired after being idle for more than 10 minutes. Also returned if the Target ID or Target location ID specified in the request URL does not exist in the results set for a given query.
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
"message": "Resource not found."
}
List All Target Locations by Query
Get a list of all Target Locations for a specific Target that matches the filters for a given query.
Request
GET
https://er-master:8339/v1/query/<query_id>/targets/<target_id>/locations
Authorization
Path Parameters
Parameter | Data Type | Description |
---|---|---|
query_id |
string |
Specify a Query ID. query_id is the response item from the /v1/query endpoint. |
target_id |
string |
Specify a Target ID to retrieve a list of Target Locations under the Target that match the filter parameters defined for the Query ID. target_id is the response item from the /v1/query/<query_id>/targets endpoint. |
Request Samples
HTTP
GET /v1/query/17512466853234836070/targets/4759598330602895744/locations
Accept: application/json
cURL
curl --request GET 'https://er-master:8339/v1/query/17512466853234836070/targets/4759598330602895744/locations' \
--user apiuser:password123 \
--header "Accept: application/json"
Response Schema
200 OK
Response Item | Data Type | Description |
---|---|---|
- |
string <array> |
List of Target location IDs for Target Locations under the Target that match the filter parameters defined in the Query ID. |
Response Samples
200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
"1431",
"1409",
"1387",
"1365",
"589",
"401",
"260",
"871",
"985",
"1393",
"515",
"1371",
"327",
"1349"
]
404 Not Found
Returned if the specified Query ID has expired after being idle for more than 10 minutes.
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
"message": "Resource not found."
}
Get Target Location Summary by Query
Get the summary for a Target Location that matches the filters for a given query.
Request
GET
https://er-master:8339/v1/query/<query_id>/targets/<target_id>/locations/<location_id>
Authorization
Path Parameters
Parameter | Data Type | Description |
---|---|---|
query_id |
string |
Specify a Query ID. query_id is the response item from the /v1/query endpoint. |
target_id |
string |
Specify a Target ID. target_id is the response item from the /v1/query/<query_id>/targets endpoint. |
location_id |
string |
Retrieve the summary for a specific Target Location that matches the filter parameters defined for the Query ID. location_id is the response item from the /v1/query/<query_id>/targets/<target_id>/locations endpoint. |
Request Samples
HTTP
GET /v1/query/17512466853234836070/targets/4759598330602895744/locations/1431
Accept: application/json
cURL
curl --request GET 'https://er-master:8339/v1/query/17512466853234836070/targets/4759598330602895744/locations/1431' \
--user apiuser:password123 \
--header "Accept: application/json"
Response Schema
200 OK
Response Item | Data Type | Description |
---|---|---|
location |
string example: file:///home/ubuntu-user/Documents/PII-Data.zip |
Full path for the match location. |
owner |
string |
User name of the file owner. |
leaf |
boolean enum: true false |
Returns true if the match location is a sub-location or leaf node. For example, a text file within a ZIP archive. |
content_type |
string example: Rich Text Document |
File format or content type. |
risk |
object |
Returns the prioritized risk level and risk profiles mapped to the match object. Not returned if no risk profiles have been set up or no risk profile is associated with the object. |
risk/prioritized_level |
string enum: High Medium Low |
Prioritized risk level mapped to the match object. |
risk/profiles |
string <array> |
List of risk profiles mapped to the match object. |
remediation |
object |
Details on the last remedial action that was performed for a matched file. Not returned if no remedial actions have been taken. |
remediation/signoff |
string |
Details entered by user in the Sign-Off field when remedial action was taken. |
remediation/reason |
string |
Details entered by user in the Reason field when remedial action was taken. |
remediation/error |
string |
Remediation error. Not returned if there is no remediation error. |
remediation/action |
string |
Remediation action taken on the file. |
remediation/user_uid |
string |
Unique user ID for the user who performed the remedial action. user_uid is the id response item from the /v1/users endpoint. |
metadata |
object |
Meta data for the remediated file. See Metadata for the list of possible ER2 metadata values. |
metadata/label |
string |
Label describing the type of metadata. |
metadata/value |
string |
Metadata value. |
children |
string <array> |
Array of location IDs for sub-locations containing matches. Match locations can contain multiple levels of nested sub-locations. For example, a PDF within a ZIP archive. |
matchdata |
object <array> |
Breakdown of matches for the match location by data type. |
matchdata/label |
string |
Data type name. |
matchdata/test |
string |
Total number of matches that are test data patterns. |
matchdata/match |
string |
Total number of matches that are data privacy breach patterns. |
matchdata/prohibited |
string |
Total number of matches that are prohibited PCI data patterns. |
Response Samples
200 OK
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
"location": "file:///home/ubuntu-user/Documents/User (20)/PII-Data-Folder.zip",
"owner": "ubuntu-user",
"leaf": false,
"content_type": "ZIP Archive",
"risk": [
{
"prioritized_level": "High",
"profiles": [
"455572488728221120",
"4520499404109630813"
]
}
],
"remediation": [
{
"signoff": "admin",
"reason": "confirmed",
"action": "Confirmed Match",
"user_uid": 929433577347983851
}
],
"metadata": [
{
"label": "",
"value": ""
}
],
"children": [
1428,
970,
969,
968,
1429,
967,
965,
1430,
966
],
"matchdata": [
{
"label": "American Express",
"test": "0",
"match": "185",
"prohibited": "0"
},
{
"label": "Diners Club",
"test": "0",
"match": "32",
"prohibited": "0"
},
{
"label": "JCB",
"test": "0",
"match": "2121",
"prohibited": "0"
},
{
"label": "Mastercard",
"test": "0",
"match": "332",
"prohibited": "0"
},
{
"label": "Visa",
"test": "0",
"match": "369",
"prohibited": "0"
},
{
"label": "Maestro",
"test": "0",
"match": "275",
"prohibited": "0"
},
{
"label": "United States Social Security Number (robust)",
"test": "0",
"match": "4000",
"prohibited": "0"
},
{
"label": "Personal Names (English)",
"test": "0",
"match": "34",
"prohibited": "0"
},
{
"label": "Login credentials",
"test": "0",
"match": "7",
"prohibited": "0"
},
{
"label": "Email addresses",
"test": "0",
"match": "4009",
"prohibited": "0"
},
{
"label": "United States Bank Account Number",
"test": "0",
"match": "1",
"prohibited": "0"
},
{
"label": "Gender (English)",
"test": "0",
"match": "1000",
"prohibited": "0"
},
{
"label": "Credentials username (robust)",
"test": "0",
"match": "4",
"prohibited": "0"
},
{
"label": "Credentials password",
"test": "0",
"match": "2",
"prohibited": "0"
},
{
"label": "IP Address",
"test": "0",
"match": "1011",
"prohibited": "0"
}
]
}
404 Not Found
Returned if the specified Query ID has expired after being idle for more than 10 minutes. Also returned if the Target ID or Target location ID specified in the request URL does not exist in the results set for a given query.
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
"message": "Resource not found."
}