Enterprise Recon v1 API

All Documentation > ER2 v1 API > Locations

Locations

List Locations Under a Target

Get details about all or specific Target Locations for a Target. Returned values are organized by Target Location name and provide information about the most recent scan activity, alerts and notifications, and match data.

Request

GET

https://er-master:8339/v1/targets/<target_id>/locations/{location_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
target_id	string	Specify the Target ID of the Target to retrieve data for. target_id is the targets->id response item from the /v1/groups/all endpoint.
location_id	string	Define this parameter to retrieve data for a specific Target Location. If no value is specified, response returns data for all Target Locations in the Target defined by the target_id. location_id is the targets->locations->id response item from the /v1/groups/all endpoint.

Query Parameters

Parameter	Data Type	Description
location_path	string	Filter results with matching Target Location path. Partial matching allowed for this filter. For example, if location_path=root, response will only include results for paths that contain the string "root".
protocol	string example: protocol=file,ssh,memory	Filter results for specific protocols. For the list of ER2 supported protocols, refer to Protocols.
offset	integer default: 0	The first Target Location to return data for. For offset=N, data will be fetched starting from the Nth Target Location. If no value is specified or offset=0, query will return data from the very first Target Location. Not applicable if a Target Location ID is specified in the path.
limit	integer default: 1000 max: 100000	Maximum number of Target Locations to return data for, starting from the first record determined by the offset parameter value. Not applicable if a Target Location ID is specified in the path.

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/4759598330602895744/locations
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/targets/4759598330602895744/locations' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
locations	object
locations/id	string	Unique Target location ID. This ID is unique 20 digit number.
locations/protocol	string	Protocol type for the Target or Target Location (e.g. Server, Dropbox, Azure Table, File). For the list of ER2 supported protocols, refer to Protocols.
locations/path	string	Search path defined for Target. Value will be blank if no search path was specified during the Scan setup.
locations/path	string	Details about the Target type.
locations/search_time	number	Time stamp of the most recent search for the Target Location in Unix time format.
locations/search_status	string enum: none searched indexing results preparing to scan processing blocked	Most recent search status for the Target Location. See Search Status for the full list of possible values.
locations/errors	object	Breakdown of errors across the Target Location.
locations/errors/notice	integer	Total number of Notice warnings for the Target Location.
locations/errors/error	integer	Total number of Errors for the Target Location.
locations/errors/critical	integer	Total number of Prohibited errors for the Target Location.
locations/matches	object	Breakdown of matches for the Target Location by match type.
locations/matches/test	string	Total number of matches containing test data patterns.
locations/matches/match	string	Total number of matches with data privacy breach patterns.
locations/matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
locations/proxy_id	string	Unique proxy Agent ID. Only returned if a specific Agent has been set to act as a proxy host for the Target Location. This ID is a unique 20 digit number.
locations/credential_id	string	Unique credential ID. Only returned if a specific login credential has been setup for the Target Location. This ID is unique 20 digit number.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "9832457584012239212",
    "protocol": "ssh",
    "path": "",
    "description": "Remote access via SSH",
    "search_time": 1523841032,
    "search_status": "none",
    "errors": {
      "notice": 0,
      "error": 0,
      "critical": 0
    },
    "matches": {
      "test": "0",
      "match": "0",
      "prohibited": "0"
    },
    "proxy_id": "1513040906398297141",
    "credential_id": "12159567147998765820"
  },
  {
    "id": "8987302884414283716",
    "protocol": "file",
    "path": "",
    "description": "All local files",
    "search_time": 1523841032,
    "search_status": "none",
    "errors": {
      "notice": 0,
      "error": 0,
      "critical": 0
    },
    "matches": {
      "test": "0",
      "match": "0",
      "prohibited": "0"
    }
  }
]

Update a Location Under a Target

Update the credentials and proxy Agent for a Target location.

Request

PUT

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

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
target_id	string	Specify the Target ID of the Target to update. target_id is the targets->id response item from the /v1/groups/all endpoint.
location_id	string	Specify the location ID of the Target Location to update. location_id is the targets->locations->id response item from the /v1/groups/all endpoint.

Request Schema

If a field is omitted in the request body, it will be cleared.

Response Item	Data Type	Description
credential_id	string	Credential ID of the credentials to be used for the Target Location. credential_id is the id response item from the /v1/credentials endpoint.
proxy_id	string	Proxy ID of the proxy agent to be assigned to scan the Target Location. proxy_id is the id response item from the /v1/agents endpoint.

Request Samples

HTTP

PUT /v1/targets/4759598330602895744/locations/9832457584012239212
Content-Type: application/json
{
  "credential_id": "15792178316638465022",
  "proxy_id": "3519591954114186070"
}

cURL

curl --request PUT 'https://er-master:8339/v1/targets/4759598330602895744/locations/9832457584012239212' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "credential_id": "15792178316638465022",
  "proxy_id": "3519591954114186070"
}'

Response Samples

204 No Content

422 Unprocessable Entity

Returned if the request body contains invalid values or formats in the input fields.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid input for '{fieldname}'."
}  

Delete a Location Under a Target

Delete an existing location path under a Target.

Request

DELETE

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

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
target_id	string	Specify the Target ID. target_id is the targets->id response item from the /v1/groups/all endpoint.
location_id	string	Specify the location ID of the Target Location to delete. location_id is the targets->locations->id response item from the /v1/groups/all endpoint.

Request Samples

HTTP

DELETE /v1/targets/4759598330602895744/locations/9832457584012239212

cURL

curl --request DELETE 'https://er-master:8339/v1/targets/4759598330602895744/locations/9832457584012239212' \
--user apiuser:password123 \
--header "Content-Type: application/json"

Response Samples

204 No Content

Add a New Target Location

Add a new location for a given Target.

Request

POST

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

Authorization

Basic Authentication

Path Parameters

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

Request Schema

Response Item	Data Type	Description
path	string	Target Location path to be added.
protocol	string	Protocol for the location path to be added. For the list of ER2 supported protocols, refer to Protocols.
credential_id	string	Credential ID of the credentials to be used for the Target Location. credential_id is the id response item from the /v1/credentials endpoint.
proxy_id	string	Proxy ID of the proxy agent to be assigned to scan the Target Location. proxy_id is the id response item from the /v1/agents endpoint.

Request Samples

HTTP

POST /v1/targets/4759598330602895744/locations
Content-Type: application/json
{
  "path": "/usr/share",
  "protocol": "file",
  "credential_id": "15792178316638465022",
  "proxy_id": "3519591954114186070"
}

cURL

curl --request POST 'https://er-master:8339/v1/targets/4759598330602895744/locations' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "path": "/usr/share",
  "protocol": "file",
  "credential_id": "15792178316638465022",
  "proxy_id": "3519591954114186070"
}'

Response Schema

201 Created

Response Item	Data Type	Description
id	string	Location ID assigned to the newly created Target Location. This ID is unique 20 digit number.

Response Samples

201 Created

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
  "id": "12345678901234567890"
}  

400 Bad Request

Returned if attempting to add a new Target Location for a deprecated protocol.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Unable to add location. Request contains deprecated protocol."
}

409 Conflict

Returned if attempting to add a location that is nested (a child path) under a location that already exists for the Target.

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: xxx
{
  "message": "A parent file path exists."
}

422 Unprocessable Entity

Returned if the request body contains invalid values or formats in the input fields.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid input for '{fieldname}'."
}  