Enterprise Recon v1 API

All Documentation > Enterprise Recon v1 API > Groups

Groups

Use this set of APIs to retrieve information related to Groups, Targets and Target Locations. Results can be filtered according to Groups, Targets and even Target Locations.

List All Groups, Targets and Target Locations

Get details about Groups, Targets and Target Locations. Returned values are organized by Group ID and provide data about available Targets and Target Locations, information from the most recent scan activity, alerts and notifications, match data, platform ID, Agent ID and credential ID. Users can choose to retrieve data for a specific Group, Target or Target Location.

Request

GET

https://er-master:8339/v1/groups/all

Authorization

Basic Authentication

Query Parameters

Parameter	Data Type	Description
group_name	string	Filter results with matching Group name. Partial matching allowed for this filter. For example, if group_name=default, response will only include results for the following Groups: Default Group and My Default.
offset	integer default: 0	The first Group to return data for. For offset=N, data will be fetched starting from Group N. If no value is specified or offset=0, the query retrieves match data starting from Group 1. Results are sorted by Group ID.
limit	integer default: 1000	Maximum number of Groups to return data for, starting from the first Group determined by the offset value.
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.
location_name	string	Filter results for matching Target location path. Partial matching allowed. If no matching paths are found, response will return Groups and Targets information without location information. 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 Enterprise Recon supported protocols, refer to Protocols.

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

Filter Groups, Targets and Locations by group_name=DEFAULT+GROUP.

HTTP

GET /v1/groups/all?group_name=DEFAULT+GROUP
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/groups/all?group_name=DEFAULT+GROUP' \
--user apiuser:password123 \
--header "Accept: application/json"

Filter Groups, Targets and Locations by target_name=MY.

HTTP

GET /v1/groups/all?target_name=MY
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/groups/all?target_name=MY' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique Group ID. This ID is unique 20 digit number.
name	string	Group name.
comments	string	Comments inserted by user about the Group.
search_time	number	Time stamp of the most recent search for the Group in Unix time format.
search_status	string enum: none searched indexing results preparing to scan processing blocked	Most recent search status for the Group. See Search Status for the full list of possible values.
pause_from	integer	Scans for a Group can be paused during scheduled periods. This value shows the number of seconds from midnight to start pausing a scan. Not returned if this parameter was not set during the Scan.
pause_to	integer	Scans for a Group can be paused during scheduled periods. This value shows the number of seconds from midnight to unpause the scan. Not returned if this parameter was not set during the Scan.
errors	object	Breakdown of errors across the Group.
errors/notice	integer	Total number of Notice warnings for the Group across all Targets and Target Locations.
errors/error	integer	Total number of Errors for the Group across all Targets and Target Locations.
errors/critical	integer	Total number of Prohibited errors for the Group across all Targets and Target Locations.
matches	object	Breakdown of matches for the Group 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.
targets	object
targets/id	string	Unique Target ID. This ID is unique 20 digit number.
targets/name	string	Target name.
targets/comments	string	Comments inserted by user about the Target.
targets/search_time	number	Time stamp of the most recent search for the Target in Unix time format.
targets/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.
targets/errors	object	Breakdown of errors across the Target.
targets/errors/notice	integer	Total number of Notice warnings for the Target across all Target Locations.
targets/errors/error	integer	Total number of Errors for the Target across all Target Locations.
targets/errors/critical	integer	Total number of Prohibited errors for the Target across all Target Locations.
targets/matches	object	Breakdown of matches for the Target by match type.
targets/matches/test	string	Total number of matches containing test data patterns.
targets/matches/match	string	Total number of matches with data privacy breach patterns.
targets/matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
targets/platform	string example: Windows 10 64bit	Platform name. Will not be returned if platform is unknown.
targets/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.
targets/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.
targets/locations	object
targets/locations/id	string	Unique Target location ID. This ID is unique 20 digit number.
targets/locations/protocol	string	Protocol type for the Target or Target Location (e.g. Server, Dropbox, Azure Table, File). For the list of Enterprise Recon supported protocols, refer to Protocols.
targets/locations/path	string	Search path defined for Target. Value will be blank if no search path was specified during the Scan setup.
targets/locations/description	string	Details about the Target type.
targets/locations/search_time	number	Time stamp of the most recent search for the Target Location in Unix time format.
targets/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.
targets/locations/errors	object	Breakdown of errors across the Target Location.
targets/locations/errors/notice	integer	Total number of Notice warnings for the Target Location.
targets/locations/errors/error	integer	Total number of Errors for the Target Location.
targets/locations/errors/critical	integer	Total number of Prohibited errors for the Target Location.
targets/locations/matches	object	Breakdown of matches for the Target Location by match type.
targets/locations/matches/test	string	Total number of matches containing test data patterns.
targets/locations/matches/match	string	Total number of matches with data privacy breach patterns.
targets/locations/matches/prohibited	string	Total number of matches containing prohibited PCI data patterns.
targets/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.
targets/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

Filter: group_name=DEFAULT+GROUP

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  "id": "4838093354730319999",
  "name": "DEFAULT GROUP",
  "comments": "comments",
  "search_time": 1523600152,
  "search_status": "none",
  "errors": {
    "notice": 1,
    "error": 0,
    "critical": 0
  },
  "matches": {
    "test": "3",
    "match": "120130",
    "prohibited": "0"
  },
  "targets": {
    "id": "4759598330602895744",
    "name": "FREEBSD-ER2",
    "comments": "comments",
    "search_time": 1523600152,
    "search_status": "none",
    "errors": {
      "notice": 1,
      "error": 0,
      "critical": 0
    },
    "matches": {
      "test": "3",
      "match": "120130",
      "prohibited": "0"
    },
    "platform": "FreeBSD 9 Intel 64bit",
    "locations": {
      "id": "8987302884414283716",
      "search_time": 1523600152,
      "search_status": "none",
      "errors": {
        "notice": 1,
        "error": 0,
        "critical": 0
      },
      "matches": {
        "test": "3",
        "match": "120130",
        "prohibited": "0"
      },
      "protocol": "file",
      "path": "",
      "description": "All local files"
    }
  }
]

200 OK

Filter: target_name=MY

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  "id": "16145931871908943813",
  "name": "WINDOWS_SERVER",
  "comments": "",
  "search_time": 1523839857,
  "search_status": "none",
  "errors": {
    "notice": 10,
    "error": 242,
    "critical": 1
  },
  "matches": {
    "test": "0",
    "match": "60398",
    "prohibited": "0"
  },
  "targets": [
    {
      "id": "5776191921548943090",
      "name": "MY-CPU-10",
      "comments": "",
      "search_time": 1523839857,
      "search_status": "searched",
      "errors": {
        "notice": 0,
        "error": 242,
        "critical": 0
      },
      "matches": {
        "test": "0",
        "match": "429",
        "prohibited": "0"
      },
      "platform": "Windows 10 64bit",
      "locations": [
        {
          "id": "8987302884414283716",
          "search_time": 0,
          "search_status": "none",
          "errors": {
            "notice": 0,
            "error": 0,
            "critical": 0
          },
          "matches": {
            "test": "0",
            "match": "0",
            "prohibited": "0"
          },
          "protocol": "file",
          "path": "",
          "description": "All local files"
        },
        {
          "id": "13533612821043917001",
          "search_time": 0,
          "search_status": "none",
          "errors": {
            "notice": "0,",
            "error": "0,",
            "critical": 0
          },
          "matches": {
            "test": "0",
            "match": "0",
            "prohibited": "0"
          },
          "protocol": "memory",
          "path": "",
          "description": "All local process memory"
        },
        {
          "id": "4955830182215299965",
          "search_time": 1523839857,
          "search_status": "searched",
          "errors": {
            "notice": 0,
            "error": 0,
            "critical": 0
          },
          "matches": {
            "test": "0",
            "match": "429",
            "prohibited": "0"
          },
          "protocol": "http",
          "path": "(port=8080)(depth=3)",
          "description": "Web page (port=8080)(depth=3)",
          "proxy_id": "15792178316638465022",
          "credential_id": "4956506920609057476"
        }
      ]
    },
    {
      "id": "11831561494313687476",
      "name": "MYWEBSITE.ORG",
      "comments": "",
      "search_time": 1523839312,
      "search_status": "none",
      "errors": {
        "notice": 1,
        "error": 0,
        "critical": 0
      },
      "matches": {
        "test": "0",
        "match": "0",
        "prohibited": "0"
      },
      "platform": "Remote Access Only,",
      "locations": {
        "id": "9626694988399146231",
        "search_time": 1523839312,
        "search_status": "none",
        "errors": {
          "notice": 0,
          "error": 0,
          "critical": 0
        },
        "matches": {
          "test": "0",
          "match": "0",
          "prohibited": "0"
        },
        "protocol": "http",
        "path": "(depth=2)",
        "description": "Web page (depth=2)",
        "proxy_id": "15792178316638465022",
        "credential_id": "4956506920609057476"
      }
    }
  ]
]

List Groups

Get details about all or a specific Target Group. Returned values are organized by Group ID 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}

Authorization

Basic Authentication

Path Parameters

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

Query Parameters

Parameter

Data Type

Description

group_name

string

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

offset

integer

default: 0

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

limit

integer

default: 1000

max: 100000

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

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Unique Group ID. This ID is unique 20 digit number.
name	string	Group name.
comments	string	Comments inserted by user about the Group.
search_time	number	Time stamp of the most recent search for the Group in Unix time format.
search_status	string enum: none searched indexing results preparing to scan processing blocked	Most recent search status for the Group. See Search Status for the full list of possible values.
pause_from	integer	Scans for a Group can be paused during scheduled periods. This value shows the number of seconds from midnight to start pausing a scan. Not returned if this parameter was not set during the Scan.
pause_to	integer	Scans for a Group can be paused during scheduled periods. This value shows the number of seconds from midnight to unpause the scan. Not returned if this parameter was not set during the Scan.
errors	object	Breakdown of errors across the Group.
errors/notice	integer	Total number of Notice warnings for the Group across all Targets and Target Locations.
errors/error	integer	Total number of Errors for the Group across all Targets and Target Locations.
errors/critical	integer	Total number of Prohibited errors for the Group across all Targets and Target Locations.
matches	object	Breakdown of matches for the Group 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.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": 16145931871908944000,
    "name": "WINDOWS_SERVER",
    "comments": "Targets can be added to this Group during initial setup.",
    "search_time": 1523839857,
    "search_status": "searched",
    "errors": {
      "notice": 10,
      "error": 242,
      "critical": 1
    },
    "matches": {
      "test": 10,
      "match": 12345,
      "prohibited": 1
    }
  }
]  

Update a Group

Update the name, comments, or scan pause period for a specific Group.

Request

PUT

https://er-master:8339/v1/groups/<group_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
group_id	string	Specify the Group ID of the Group you want to update. group_id is the 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
name	string	Group name.
comments	string	Comments inserted by user about the Group.
pause_from	integer	Scans for a Group can be paused during scheduled periods. This value is the number of seconds from midnight to start pausing a scan. Use this with the pause_to parameter.
pause_to	integer	Scans for a Group can be paused during scheduled periods. This value is the number of seconds from midnight to unpause the scan. Use this with the pause_from parameter.

Request Samples

HTTP

PUT /v1/groups/16145931871908944000
Content-Type: application/json
{
  "name": "My Updated Group Name",
  "comments": "Comments about My Updated Group",
  "pause_from": 0,
  "pause_to": 0
}

cURL

curl --request PUT 'https://er-master:8339/v1/groups/16145931871908944000' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "My Updated Group Name",
  "comments": "Comments about My Updated Group",
  "pause_from": 0,
  "pause_to": 0
}'

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 Group

Delete a Group from the Master Server. Cannot be deleted if there are still Targets under the Group.

Request

DELETE

https://er-master:8339/v1/groups/<group_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
group_id	string	Specify the Group ID of the Group you want to delete. group_id is the id response item from the /v1/groups/all endpoint.

Request Samples

HTTP

DELETE /v1/groups/16145931871908944000
Content-Type: application/json

cURL

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

Response Samples

204 No Content

Add a New Group

Create or add a new Group.

Request

POST

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

Authorization

Basic Authentication

Request Schema

Response Item	Data Type	Description
name	string	Group name.
comments	string	Comments inserted by user about the Group.
pause_from	integer	Scans for a Group can be paused during scheduled periods. This value is the number of seconds from midnight to start pausing a scan. Use this with the pause_to parameter.
pause_to	integer	Scans for a Group can be paused during scheduled periods. This value is the number of seconds from midnight to unpause the scan. Use this with the pause_from parameter.

Request Samples

HTTP

POST /v1/groups
Content-Type: application/json
{
  "name": "My New Group Name",
  "comments": "Comments about My New Group",
  "pause_from": 0,
  "pause_to": 0
}

cURL

curl --request POST 'https://er-master:8339/v1/groups' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "My New Group Name",
  "comments": "Comments about My New Group",
  "pause_from": 0,
  "pause_to": 0
}'

Response Schema

201 Created

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

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