Enterprise Recon v1 API

All Documentation > ER2 v1 API > Agents and Agent Groups

Agents and Agent Groups

Use this set of APIs to manage Node Agents, Agent Groups and download Agent installation packages.

List Agents

Retrieve information about the agent host name, version, connection status, and proxy status for all agents or agent groups, or retrieve details for a specific Agent or Agent Group.

Request

GET

https://er-master:8339/v1/agents/{agent_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_id	string	Define the hash ID of the Agent or Agent Group to retrieve data for. If no value is specified, response returns data for all Agents or Agent Groups. agent_id is the id response item from the /v1/agents endpoint.

Query Parameters

Parameter	Data Type	Description
agent_name	string	Filter results with matching Agent name. Simple, case insensitive search.
verification	string enum: verified unverified	Filter results by Agent verification status.
connectivity	string enum: connected disconnected	Filter results by Agent connectivity status.
offset	integer default: 0	The first Agent to return data for. For offset=N, data will be fetched starting from the Nth Agent. If no value is specified or offset=0, query will return data from the very first Agent.
limit	integer default: 1000 max: 100000	Maximum number of Agents 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

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

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Agent or Agent Group Hash ID. This ID is a unique 20-digit number.
name	string	Host name of Agent or label for Agent Group.
type	string enum: node group	Indicates if the returned data is for an Agent or an Agent Group.
members	array <string>	List of Agent Hash IDs for members in the Agent Group. Only applicable when type=group.
version	string	Version of the installed Agent. Only applicable when type=node.
platform	string	Self-reported Agent platform name. Only applicable when type=node.
platform_compatibility	string	Platform classification. Only applicable when type=node.
verified	boolean enum: true false	Indicates if Agent has been verified and can be used to scan Targets. Only applicable when type=node.
connected	boolean enum: true false	Indicates if Agent is currently connected. Only applicable when type=node.
connected_ip	string	IP address of the Agent host machine. Only applicable when type=node.
time_difference	number	Time difference between the Master Server and Node Agent system clocks in seconds (Unix time format). Only applicable when type=node.
target_group	string	Only returned if Agent is assigned to a specific Target Group upon verifying / adding the Agent. Only applicable when type=node.
proxy	boolean enum: true false	Indicates if Agent is allowed to act as a Proxy Agent in scans where a Target has no locally installed Node Agent. Only applicable when type=node.
user	string	User account that the Agent service is running on. Only applicable when type=node.
cpu	string	CPU on the Agent host system. Only applicable when type=node.
cores	integer	Number of CPU cores present on the Agent host system. Only applicable when type=node.
boot	number	Agent host system boot time in Unix time format. Only applicable when type=node.
ram	integer <bytes>	Amount of RAM available on the Agent host system in bytes. Only applicable when type=node.
started	number	Agent service start up time in Unix time format. Only applicable when type=node.
networks	object	List of network devices present on Agent system. Only applicable when type=node.
networks/ip	string	IP address of the connected network device.
networks/mac	string	MAC address of the connected network device.
networks/device	string	Description of connected network device.
mountpoints	object	List of mounted shares or devices on Agent host system. Only available for Agents version 2.1 onwards.
mountpoints/path	string	Path for the mount point / mount directory.
mountpoints/source	string	Path for the source device.
mountpoints/network	boolean enum: true false	Returns true for network shares or network devices, returns false for local devices.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "15930516385165798963",
    "name": "<Agent System Hostname>",
    "type": "node",
    "version": "2.0.31",
    "platform": "Microsoft Windows Server 2012 R2 64-bit",
    "platform_compatibility": "Windows Server 2012 R2",
    "verified": true,
    "connected": false,
    "proxy": true,
    "user": "SYSTEM",
    "cpu": "Intel(R) Xeon(R) CPU E5-2640 v4 @ 2.40GHz",
    "cores": 4,
    "boot": 1577341543,
    "ram": "13018513408",
    "started": 1577341566,
    "networks": [
      {
          "ip": "<ip address>",
          "mac": "<mac address>",
          "device": "<description>"
      }
    ],
    "mountpoints": [
      {
          "path": "<mount point path>",
          "source": "<source device path>",
          "network": "false"
      },
      {
          "path": "<mount point path>",
          "source": "<source device path>",
          "network": "false"
      }
    ]
  },
  {
      "id": "2047671365782960485",
      "name": "<Agent Group Name>",
      "type": "group",
      "members": [
          "3630276204982621206",
          "728092471340873028"
      ]
  }
]

Delete an Agent

Delete an installed Node Agent.

Request

DELETE

https://er-master:8339/v1/agents/<agent_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_id	string	Define the hash ID of the Agent or Agent Group to delete. Agent can only be deleted when it is not connected. agent_id is the id response item from the /v1/agents endpoint.

Request Samples

HTTP

DELETE /v1/agents/3519591954114186070
Content-Type: application/json

cURL

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

Response Samples

204 No Content

Manage an Agent

Verify, block, enable or disable Agent as Proxy Agent.

Request

POST

https://er-master:8339/v1/agents/<agent_id>/<action>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_id	string	Define the hash ID of the Agent to perform an action on. agent_id is the id response item from the /v1/agents endpoint.
action	string enum: verify block enable_proxy disable_proxy	Specify action to perform on Node Agent.

Parameter

Data Type

Description

agent_id

string

Define the hash ID of the Agent to perform an action on. agent_id is the id response item from the /v1/agents endpoint.

action

string

enum: verify block enable_proxy disable_proxy

Specify action to perform on Node Agent.

Request Samples

HTTP

POST /v1/agents/3519591954114186070/verify
Accept: application/json

cURL

curl --request POST 'https://er-master:8339/v1/agents/3519591954114186070/verify' \
--user apiuser:password123 \
--header "Content-Type: application/json"

Response Samples

201 Created

List Blocked Agents

Get a list of blocked Agents.

Request

GET

https://er-master:8339/v1/agents/blocked/{blocked_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
blocked_id	string	Retrieve information for a specific Agent by Blocked ID.

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

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Blocked ID for the blocked Agent.
hostname	string	Host name of the blocked Agent host system.
ip	string	IP v4 address of the blocked Agent.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
{
  "id": "6108591700849724588",
  "hostname": "My-Windows-Machine",
  "ip": "192.168.1.150"
}

Unblock an Agent

Unblock a blocked Agent.

Request

POST

https://er-master:8339/v1/agents/blocked/<agent_id>/unblock

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
blocked_id	string	Specify Blocked ID of Agent to unblock.

Request Samples

HTTP

POST /v1/agents/blocked/3519591954114186070/unblock
Accept: application/json

cURL

curl --request POST 'https://er-master:8339/v1/agents/blocked/3519591954114186070/unblock' \
--user apiuser:password123 \
--header "Content-Type: application/json"

Response Samples

201 Created

List Available Agent Packages

Get list of available Node Agent packages.

Request

GET

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

Authorization

Basic Authentication

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

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
platform	string	Node Agent platform name.
version	string	Node Agent version.
filename	string	File name for Node Agent package file.
download_url	string	URL to download the Node Agent package file from.
md5_hash	string	128-bit MD5 hash value for the Agent package file.
sha1_hash	string	160-bit SHA1 hash value for the Agent package file.
sha256_hash	string	256-bit SHA1 hash value for the Agent package file.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "platform": "FreeBSD 9 Intel 64bit",
    "version": "2.0.31",
    "filename": "er2-2.0.31-freebsd9-x64.tbz",
    "download_url": "<ip address>:8339/v1/nodeagents/er2-2.0.31-freebsd9-x64.tbz",
    "md5_hash": "<md5 hash value>",
    "sha1_hash": "<sha1 hash value>",
    "sha256_hash": "<sha256 hash value>"
  },
  {
    "platform": "Linux 2.6 Red Hat 64 bit",
    "version": "2.0.31",
    "filename": "er2-2.0.31-linux26-rh-x64.rpm",
    "download_url": "<ip address>:8339/v1/nodeagents/er2-2.0.31-linux26-rh-x64.rpm",
    "md5_hash": "<md5 hash value>",
    "sha1_hash": "<sha1 hash value>",
    "sha256_hash": "<sha256 hash value>"
  },
  {
    "platform": "Windows XP Professional 64",
    "version": "2.0.31",
    "filename": "er2_2.0.31-windows-x64.msi",
    "download_url": "<ip address>:8339/v1/nodeagents/er2_2.0.31-windows-x64.msi",
    "md5_hash": "<md5 hash value>",
    "sha1_hash": "<sha1 hash value>",
    "sha256_hash": "<sha256 hash value>"
  },
  {
    "platform": "Apple macOS 10.11 El Capitan",
    "version": "2.0.31",
    "filename": "er2-2.0.31-osx-x64.pkg",
    "download_url": "<ip address>:8339/v1/nodeagents/er2-2.0.31-osx-x64.pkg",
    "md5_hash": "<md5 hash value>",
    "sha1_hash": "<sha1 hash value>",
    "sha256_hash": "<sha256 hash value>"
  }
]

Download Agent Package File

Download specific Node Agent package file.

Request

GET

https://er-master:8339/v1/nodeagents/<filename>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
filename	string	Specify file name of the Agent package file to download. filename is the filename response item from the /v1/nodeagents endpoint.

Request Samples

HTTP

GET /v1/nodeagents/er2-2.0.31-freebsd9-x64.tbz
Accept: application/json

cURL

curl --request GET 'https://er-master:8339/v1/nodeagents/er2-2.0.31-freebsd9-x64.tbz' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Samples

200 OK

List Agent Groups

Retrieve information about the agent members (e.g. host name, version, connection status, and proxy status) for all or for a specific Agent Group.

Use Agent Groups to run Distributed Scans for supported Targets.

Request

GET

https://er-master:8339/v1/agentgroups/{agent_group_id}

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_group_id	string	Hash ID of the Agent Group to retrieve data for. If no value is specified, response returns data for all Agent Groups.

Query Parameters

Parameter	Data Type	Description
details	boolean default: false enum: true false	Show (true) or hide (false) Agent Group member details (e.g. Node Agent ID, platform, version etc.)

Parameter

Data Type

Description

details

boolean

default: false

enum: true false

Show (true) or hide (false) Agent Group member details (e.g. Node Agent ID, platform, version etc.)

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

cURL

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

Response Schema

200 OK

Response Item	Data Type	Description
id	string	Agent Group hash ID. This ID is unique 20 digit number.
name	string	Agent Group name or label.
type	string enum: group	Indicates if the returned data is for an Agent or an Agent Group. Always returns group for this endpoint.
members	array <string>	List of Agent hash IDs for Agent members in the Agent Group.
details	array <object>	Detailed information about each Agent member in the Agent Group. Only returned if details=true.
details/id	string	Agent hash ID. This ID is unique 20 digit number.
details/name	string	Host name of Agent.
details/type	string enum: node	Indicates if the returned data is for a Agent or an Agent Group. Always returns node for for the details object.
details/version	string	Version of the installed Agent.
details/platform	string	Self-reported Agent platform name.
details/platform_compatibility	string	Platform classification.
details/verified	boolean enum: true false	Indicates if Agent has been verified and can be used to scan Targets.
details/connected	boolean enum: true false	Indicates if Agent is currently connected.
details/connected_ip	string	IP address of the Agent host machine.
details/proxy	boolean enum: true false	Indicates if Agent is allowed to act as a Proxy Agent in scans where a Target has no locally installed Agent.
details/user	string	User account that the Agent service is running on.
details/time_difference	number	Time difference between the Master Server and Agent system clocks in seconds.
details/target_group	string	Only returned if Agent is assigned to a specific Target Group upon verifying / adding the Agent.
details/cpu	string	CPU on the Agent host system.
details/cores	integer	Number of CPU cores present on the Agent host system.
details/boot	number	Agent host system boot time in Unix time format.
details/ram	integer <bytes>	Amount of RAM available on the Agent host system in bytes.
details/started	number	Agent service start up time in Unix time format.
details/networks	object	List of network devices present on Agent system.
details/networks/ip	string	IP address of the connected network device.
details/networks/mac	string	MAC address of the connected network device.
details/networks/device	string	Description of connected network device.
details/mountpoints	object	List of mounted shares or devices on Agent host system. Only available for Agents version 2.1 onwards.
details/mountpoints/path	string	Path for the mount point / mount directory.
details/mountpoints/source	string	Path for the source device.
details/mountpoints/network	boolean enum: true false	Returns true for network shares or network devices, returns false for local devices.

Response Samples

200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "<agent_group_id>",
    "name": "<agent_group_name>",
    "type": "<group>",
    "members": [
      "15930516385165798963"
    ],
    "details": [
      {
        "id": "15930516385165798963",
        "name": "<Agent System Hostname>",
        "type": "node",
        "version": "2.0.31",
        "platform": "Microsoft Windows Server 2012 R2  64-bit",
        "platform_compatibility": "Windows Server 2012 R2",
        "verified": true,
        "connected": false,
        "proxy": true,
        "user": "SYSTEM",
        "cpu": "Intel(R) Xeon(R) CPU E5-2640 v4 @ 2.40GHz",
        "cores": 4,
        "boot": 1577341543,
        "ram": "13018513408",
        "started": 1577341566,
        "networks": [
          {
              "ip": "<ip address>",
              "mac": "<mac address>",
              "device": "<description>"
          }
        ],
        "mountpoints": [
          {
              "path": "<mount point path>",
              "source": "<source device path>",
              "network": "false"
          },
          {
              "path": "<mount point path>",
              "source": "<source device path>",
              "network": "false"
          }
        ]
      }
    ]
  }
]

Rename an Agent Group

Use this API to rename the Agent Group name or label.

See Add New Agent to Agent Group and Delete Agent from Agent Group for more information.

Request

PUT

https://er-master:8339/v1/agentgroups/<agent_group_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_group_id	string	Hash ID of the Agent Group to rename. agent_group_id is the id response item from the List All Agent Groups endpoint.

Request Schema

Parameter	Data Type	Description
name	string	Agent Group label or name.

Request Samples

HTTP

PUT /v1/agentgroups/18152352466912819838
Content-Type: application/json
{
  "name": "<new_agent_group_name>"
}

cURL

curl --request PUT 'https://er-master:8339/v1/agentgroups/18152352466912819838' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "<new_agent_group_name>"
}'

Response Samples

204 No Content

Delete an Agent Group

Use this API to delete an Agent Group. Deleting an Agent Group does not delete the Node Agent members from the Master Server.

Request

DELETE

https://er-master:8339/v1/agentgroups/<agent_group_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_group_id	string	Hash ID of the Agent Group to delete. agent_group_id is the id response item from the List All Agent Groups endpoint. Deleting an Agent Group does not delete the Node Agent members from the Master Server.

Request Samples

HTTP

DELETE /v1/agentgroups/18152352466912819838

cURL

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

Response Samples

204 No Content

Create an Agent Group

Use this API to create a new Agent Group that can be used to run Distributed Scans.

Request

POST

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

Authorization

Basic Authentication

Request Schema

Parameter	Data Type	Description
name	string	Agent Group label or name.
members	string <array>	Array of Agent hash IDs for Agents to be added as members of the new Agent Group. See Proxy Agent Requirements to understand the requirements when adding Agent members to an Agent Group.

Request Samples

HTTP

POST /v1/agentgroups
Content-Type: application/json
{
  "name": "<new_agent_group_name>",
  "members": [
    "<agent_id_1>",
    "<agent_id_2>",
    "<agent_id_N>"
  ]
}

cURL

curl --request POST 'https://er-master:8339/v1/agentgroups' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "name": "<new_agent_group_name>",
  "members": [
    "<agent_id_1>",
    "<agent_id_2>",
    "<agent_id_N>"
  ]
}'

Response Schema

201 Created

Response Item	Data Type	Description
id	string	Agent Group ID assigned to the newly created Agent Group.

Response Samples

201 Created

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

Add New Agent to Agent Group

Use this API to add a new Agent to an existing Agent Group.

Request

POST

https://er-master:8339/v1/agentgroups/<agent_group_id>/<agent_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_group_id	string	Hash ID of the Agent Group to add an Agent to. agent_group_id is the id response item from the List All Agent Groups endpoint.
agent_id	string	Hash ID of the Agent to add as a member of the specified Agent Group.

Request Samples

HTTP

POST /v1/agentgroups/18152352466912819838/3519591954114186070

cURL

curl --request POST 'https://er-master:8339/v1/agentgroups/18152352466912819838/3519591954114186070' \
--user apiuser:password123 \
--header "Content-Type: application/json"

Response Samples

201 Created

Delete Agent from Agent Group

Use this API to remove an Agent from an Agent Group. Removing an Agent from the Agent Group does not delete the Agent member from the Master Server.

Request

DELETE

https://er-master:8339/v1/agentgroups/<agent_group_id>/<agent_id>

Authorization

Basic Authentication

Path Parameters

Parameter	Data Type	Description
agent_group_id	string	Hash ID of the Agent Group to remove an Agent from. agent_group_id is the id response item from the List All Agent Groups endpoint.
agent_id	string	Hash ID of the Agent to remove as a member of the specified Agent Group.

Request Samples

HTTP

DELETE /v1/agentgroups/18152352466912819838/3519591954114186070

cURL

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

Response Samples

204 No Content