Enterprise Recon v1 API

All Documentation > ER2 v1 API > Targets

Targets

List Targets By Group

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

Request

GET

https://er-master:8339/v1/groups/<group_id>/targets/{target_id}

Authorization

Basic Authentication

Path Parameters

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

Query Parameters

Parameter	Data Type	Description
target_name	string	Filter results with matching Target name. Partial matching allowed for this filter. For example, if target_name=default, response will only include results for the following Targets: Default Target and My Default.
offset	integer default: 0	The first Target to return data for. For offset=N, data will be fetched starting from the Nth Target. If no value is specified or offset=0, query will return data from the very first Target. Results are sorted by Target ID in ascending order. Not applicable if a Target ID is specified in the path.
limit	integer default: 1000 max: 100000	Maximum number of Targets to return data for, starting from the first record determined by the offset parameter value. Not applicable if a Target ID is specified in the path.

Parameter

Data Type

Description

target_name

string

Filter results with matching Target name. Partial matching allowed for this filter. For example, if target_name=default, response will only include results for the following Targets: Default Target and My Default.

offset

integer

default: 0

The first Target to return data for. For offset=N, data will be fetched starting from the Nth Target. If no value is specified or offset=0, query will return data from the very first Target. Results are sorted by Target ID in ascending order. Not applicable if a Target ID is specified in the path.

limit

integer

default: 1000

max: 100000

Maximum number of Targets to return data for, starting from the first record determined by the offset parameter value. Not applicable if a Target 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/groups/16145931871908944000/targets
Accept: application/json

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique Target ID. This ID is unique 20 digit number.
name	string	Target name.
comments	string	Comments inserted by user about the Target.
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.
errors	object	Breakdown of errors across the Target.
errors/notice	integer	Total number of Notice warnings for the Target across all Target Locations.
errors/error	integer	Total number of Errors for the Target across all Target Locations.
errors/critical	integer	Total number of Prohibited errors for the Target across all Target Locations.
matches	object	Breakdown of matches for the Target by match type.
matches/test	string	Total number of matches containing test data patterns.
matches/match	string	Total number of matches with data privacy breach patterns.
matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
platform	string example: Windows 10 64bit	Platform name. Will not be returned if platform is unknown.
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. This ID is a unique 20 digit number.
credential_id	string	Unique credential ID. Only returned if a specific login credential has been setup for the Target. This ID is unique 20 digit number.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "2486556466149932561",
    "name": "CENTOS",
    "comments": "<Comments for Target>",
    "search_time": 1523606045,
    "search_status": "none",
    "errors": {
      "notice": 6,
      "error": 60,
      "critical": 0
    },
    "matches": {
      "test": "123",
      "match": "12345",
      "prohibited": "1"
    },
    "platform": "Linux 2.6 Red Hat 64 bit"
  },
  {
    "id": "15674659100986621657",
    "name": "OPENSUSE",
    "comments": "<comments for Target>",
    "search_time": 1523839065,
    "search_status": "error",
    "errors": {
      "notice": 0,
      "error": 0,
      "critical": 1
    },
    "matches": {
      "test": "0",
      "match": "0",
      "prohibited": "0"
    },
    "platform": "Linux 2.6 Red Hat 64 bit",
    "proxy_id": "3519591954114186070",
    "credential_id": "12159567147998765820"
  }
]

List Targets

Get details about all or a specific Target. Response returns information about the most recent scan activity, alerts and notifications, and match data.

Request

GET

https://er-master:8339/v1/targets/{target_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
target_id	string	Define this parameter to retrieve data for a specific Target. If no value is specified, response returns data for all Target. target_id is the targets->id response item from the /v1/groups/all endpoint.

Query Parameters

Parameter	Data Type	Description
target_name	string	Filter results with matching Target name. Partial matching allowed for this filter. For example, if target_name=default, response will only include results for the following Targets: Default Target and My Default.
offset	integer default: 0	The first Target to return data for. For offset=N, data will be fetched starting from the Nth Target. If no value is specified or offset=0, query will return data from the very first Target. Results are sorted by Target ID in ascending order. Not applicable if a Target ID is specified in the path.
limit	integer default: 1000 max: 100000	Maximum number of Targets to return data for, starting from the first record determined by the offset parameter value. Not applicable if a Target ID is specified in the path.

Parameter

Data Type

Description

target_name

string

offset

integer

default: 0

limit

integer

default: 1000

max: 100000

Maximum number of Targets to return data for, starting from the first record determined by the offset parameter value. Not applicable if a Target 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

Request Samples

HTTP

GET /v1/targets/2486556466149932561
Accept: application/json

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique Target ID. This ID is unique 20 digit number.
name	string	Target name.
comments	string	Comments inserted by user about the Target.
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.
errors	object	Breakdown of errors across the Target.
errors/notice	integer	Total number of Notice warnings for the Target across all Target Locations.
errors/error	integer	Total number of Errors for the Target across all Target Locations.
errors/critical	integer	Total number of Prohibited errors for the Target across all Target Locations.
matches	object	Breakdown of matches for the Target by match type.
matches/test	string	Total number of matches containing test data patterns.
matches/match	string	Total number of matches with data privacy breach patterns.
matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
platform	string example: Windows 10 64bit	Platform name. Will not be returned if platform is unknown.
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. This ID is a unique 20 digit number.
credential_id	string	Unique credential ID. Only returned if a specific login credential has been setup for the Target. This ID is unique 20 digit number.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "2486556466149932561",
    "name": "CENTOS",
    "comments": "<Comments for Target>",
    "search_time": 1523606045,
    "search_status": "none",
    "errors": {
      "notice": 6,
      "error": 60,
      "critical": 0
    },
    "matches": {
      "test": "123",
      "match": "12345",
      "prohibited": "1"
    },
    "platform": "Linux 2.6 Red Hat 64 bit"
  }
]

Update a Target

Update the settings for a specific Target. See Add Targets for Target-specific requirements when updating and configuring each Target type.

Request

PUT

https://er-master:8339/v1/targets/<target_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.

Request Schema

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

Response Item	Data Type	Description
group_id	string	Group ID of the Group to assign the Target to. group_id is the id response item from the /v1/groups/all endpoint.
credential_id	string	Credential ID of the credentials to be used for the Target. 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. proxy_id is the id response item from the /v1/agents endpoint.
platform	string	Platform description or operating system of the Target. Set platform to Remote Access Only for cloud Targets. For the list of supported Platform values, refer to ER2 Platforms. Ensure that you select the correct operating system for the Target host. Certain features in ER2 (e.g. PRO Data Classification with MIP, PRO Data Access Management) may not work as expected if the selected operating system is incorrect or is set to "Remote Access Only".
comments	string	Comments inserted by user about the Target.

Request Samples

HTTP

PUT /v1/targets/2486556466149932561
Content-Type: application/json
{
  "group_id": "16145931871908944000",
  "credential_id": "103",
  "proxy_id": "3519591954114186070",
  "platform": "Remote Access Only",
  "comments": "Comments about My Target."
}

cURL

curl --request PUT 'https://er-master:8339/v1/targets/2486556466149932561' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "group_id": "16145931871908944000",
  "credential_id": "103",
  "proxy_id": "3519591954114186070",
  "platform": "Remote Access Only",
  "comments": "Comments about My Target."
}'

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 Target

Delete a Target permanently from ER2.

Deleting a Target permanently removes all data and records associated with the Target from ER2.

The Ground Labs End User License Agreement only allows you to delete a Target if it has been permanently decommissioned.

Request

DELETE

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

Authorization

Basic Authentication

Path Parameters

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

Request Samples

HTTP

DELETE /v1/targets/4759598330602895744
Content-Type: application/json

cURL

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

Response Samples

204 No Content

Add a New Target

Add a new Target to the Master Server. See Add Targets for Target-specific requirements when adding and configuring each Target type.

Request

POST

https://er-master:8339/v1/targets

Authorization

Basic Authentication

Request Schema

Parameter	Data Type	Description
name	string	Name of the Target to be added. This is the Host name for a server / workstation, Azure Storage account name, Box Enterprise administrator account email address, For Enterprise Recon 2.8.0 and below. Box Inc domain, Dropbox Business / Dropbox Personal email address, Microsoft 365 domain, Google Workspace domain, Google Cloud Storage project ID, Microsoft OneNote domain, Microsoft Teams domain, OneDrive domain, Rackspace account name, Salesforce domain name, To get the domain name for your organization's Salesforce site, log in to Salesforce and go to Setup > SETTINGS > Company Settings > My Domain. Use the value in the My Domain Name field for the name parameter. SharePoint Online domain, or Exchange domain, or Descriptive label for all other Targets.
group_id	string	Group ID of the Group to assign the Target to. group_id is the id response item from the /v1/groups/all endpoint.
credential_id	string	Credential ID of the credentials to be used for the Target. 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. proxy_id is the id response item from the /v1/agents endpoint.
platform	string	Platform description or operating system of the Target. Set platform to Remote Access Only for cloud Targets. For the list of supported Platform values, refer to ER2 Platforms. Ensure that you select the correct operating system for the Target host. Certain features in ER2 (e.g. PRO Data Classification with MIP, PRO Data Access Management) may not work as expected if the selected operating system is incorrect or is set to "Remote Access Only".
comments	string	Comments inserted by user about the Target.

Request Samples

HTTP

POST /v1/targets
Content-Type: application/json
{
  "name": "My-New-CPU",
  "group_id": "16145931871908944000",
  "credential_id": "103",
  "proxy_id": "3519591954114186070",
  "platform": "Remote Access Only",
  "comments": "Comments about My Target."
}

cURL

curl --request POST 'https://er-master:8339/v1/targets' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "My-New-CPU",
  "group_id": "16145931871908944000",
  "credential_id": "103",
  "proxy_id": "3519591954114186070",
  "platform": "Remote Access Only",
  "comments": "Comments about My Target."
}'

Response Schema

201 Created

Response Item	Data Type	Description
id	string	Target ID assigned to the newly created Target. 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 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."
}

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}'."
}  

List Discovered Targets

Get list of discovered Targets and their platforms. Targets that have already been added will not be returned.

Request

GET

https://er-master:8339/v1/targets/discovered

Authorization

Basic Authentication

Query Parameters

Parameter	Data Type	Description
offset	integer default: 0	The first discovered Target to return data for. For offset=N, data will be fetched starting from the Nth discovered Target. If no value is specified or offset=0, query will return data from the very first discovered Target. Results are sorted alphabetically by Target name, in ascending order.
limit	integer default: 1000 max: 100000	Maximum number of discovered Targets to return data for, starting from the first record determined by the offset parameter value.

Parameter

Data Type

Description

offset

integer

default: 0

The first discovered Target to return data for. For offset=N, data will be fetched starting from the Nth discovered Target. If no value is specified or offset=0, query will return data from the very first discovered Target. Results are sorted alphabetically by Target name, in ascending order.

limit

integer

default: 1000

max: 100000

Maximum number of discovered Targets to return data for, starting from the first record determined by the offset parameter value.

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

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
name	string	Target name.
platform	string example: Windows 10 64bit	Platform name. Will not be returned if platform is unknown.

Response Item

Data Type

Description

name

string

Target name.

platform

string

example: Windows 10 64bit

Platform name. Will not be returned if platform is unknown.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "name": "Target A",
    "platform": "Linux 2.6 64bit (RPM)"
  },
  {
    "name": "Target B",
    "platform": "Solaris 10 SPARC"
  }
]

Probe Target Location

Probe the Target to see the available locations for the Target. The first 10000 locations under the Target will be returned, sorted alphabetically by the location path in ascending order.

Request

POST

https://er-master:8339/v1/targets/probing

Authorization

Basic Authentication

Request Schema

Response Item	Data Type	Description
target_name	string	Name of the Target to probe.
path	string	Location path on the Target to probe. If no value is specified, only the "/" folder will be probed.
protocol	string	Protocol of the path to probe. For the list of ER2 supported protocols, refer to Protocols.
credential_id	string	Credential ID of the credentials to be used for probing the Target location. Required for Targets without any Agent installed. credential_id is the id response item from the /v1/credentials endpoint.
proxy_id	string	Proxy ID of the Proxy Agent to be used for probing the Target location. Required for Targets without any Agent installed. proxy_id is the id response item from the /v1/agents endpoint.
platform	string	Platform description or operating system of the Target. Set platform to Remote Access Only for cloud Targets. For the list of supported Platform values, refer to ER2 Platforms.

Request Samples

HTTP

POST /v1/targets/probing
Content-Type: application/json
{
  "target_name": "My Target 1",
  "path": "/usr/share/wallpapers",
  "protocol": "file",
  "credential_id": "12159567147998765820",
  "proxy_id": "11904374752709236130",
  "platform": "Linux 2.6 Generic 64 bit"
}

cURL

curl --request POST 'https://er-master:8339/v1/targets/probing' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "target_name": "My Target 1",
  "path": "/usr/share/wallpapers",
  "protocol": "file",
  "credential_id": "12159567147998765820",
  "proxy_id": "11904374752709236130",
  "platform": "Linux 2.6 Generic 64 bit"
}'

Response Schema

201 Created

Response Item	Data Type	Description
path	string	Location path on the Target.
type	string enum: file folder empty folder	Description of the location.

Response Item

Data Type

Description

path

string

Location path on the Target.

type

string

enum: file folder empty folder

Description of the location.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "path": "/usr/share/wallpapers/file.txt",
    "type": "file"
  },
  {
    "path": "/usr/share/wallpapers/default",
    "type": "folder"
  }
]

400 Bad Request

Returned if attempting to probe a Target or Target Location for a deprecated protocol.

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