NXLog Agent Minder Public APIs
Counting agents
| method + URI | description |
|---|---|
|
return number of agents matching the specified |
request response |
|
Listing agents
| method + URI | description |
|---|---|
|
return IDs of agents matching the specified |
request response |
|
Agent information
| method + URI | description |
|---|---|
|
return information about agents matching the specified |
request response |
|
|
return information about agent with id |
request response |
|
Agent commands
| method + URI | description |
|---|---|
|
execute an operation ( |
request response |
|
|
execute an operation ( |
request response
|
|
Module information
| method + URI | description |
|---|---|
|
return info about module |
request response |
|
|
return info about module |
request response |
|
Module commands
| method + URI | description |
|---|---|
|
execute an operation ( |
request response |
|
Reading files
| method + URI | description |
|---|---|
|
retrieve the content of the file |
request response |
|
|
retrieve the content of the file |
request response |
|
Writing files
| method + URI | description |
|---|---|
|
put the content of the request body into the file |
request response |
|
|
put the content of the request body into the file |
request response
|
|
Reading the internal log
| method + URI | description |
|---|---|
|
retrieve the content of the log file of the agents matching the specified |
request response |
|
admin] getLog called\n2020-12-09 13:05:03 INFO [xm_admin |
admin] getLog called\n"
}
}
]
----
|
|
retrieve the content of the log file of |
Reading the configuration
| method + URI | description |
|---|---|
|
retrieve the content of the config file of agents matching the specified |
request response |
|
|
retrieve the content of the config file of |
request response |
|
Writing the configuration
| method + URI | description | ||
|---|---|---|---|
|
put the content of the config file of agents matching the specified |
||
request response
|
|||
|
put the content of the config file of |
||
request response
|
|||
Reading agent state
| method + URI | description |
|---|---|
|
get the state ( |
request response |
|
|
get the state ( |
request response |
|
Enrolling agents
Enrolling agents is a complex procedure. It consists of the following steps:
-
generating connection configuration
-
generating client key
-
generating client certificate
-
pushing the connection configuration to the targeted agents set
-
pushing the client key to the targeted agent set
-
pushing the client certificate to the targeted agent set
-
pushing the CA certificate to the targeted agent set
-
restarting the targeted agent set
All of these steps are handled in the background by NXLog Agent Minder.
To enroll your agents you will need to provide the apparent IP address or host name and port of NXLog Agent Minder, shown as 192.168.1.1:4041 in our examples.
| If your agents already have a valid configuration this will overwrite that, effectively resetting the agent to a blank state. |
method + URI |
description |
|
enroll agents matching the specified |
request response |
|
|
enroll |
request response
|
|
NXLog Agent Minder MQL Filter Syntax
Agents can be targeted individually or in sets using Minder Query Language (MQL).
MQL expressions search the connected agents using the attributes provided in their serverinfo response data.
To apply a query to any HTTP endpoint described above, simply include it in the URI query filter attribute.
The general format of a filter expression is as follows:
attribute operation literalExpressions may be combined using the and, or, and not operators and can be grouped with
parentheses. For example: name = agentname and not (os = Linux or digest like abcd%).
Literals may be grouped in lists with elements separated by commas and optionally delimited by
parentheses. For example: name = (agent-1, agent-2, agent-3) returns the same agents as
name = agent-1 or name = agent-2 or name = agent-3. Including the parentheses surrounding the list
items is a stylistic choice.
String literals may be delimited by double quotes or single quotes, however this is optional. Should a string literal not be delimited, whitespace, commas, and closing parentheses will terminate the string left unescaped with the backslash character. Should it be delimited, only a matching double quote or single quote left unescaped will terminate the string.
Should a literal be interpretable as an IP address, socket address, or IP network, it will
not work with string operations such as like or regex without being placed inside double or
single quotes.
|
| String literals in a query are case-sensitive. |
All operations may be negated directly. For example: name not = agentname works in place of
not name = agentname. Furthermore, the not keyword left in place of an operation expands to
not =.
Supported Attributes
Attributes of most types may be coerced to strings such that you can use like and regex with them.
|
| attribute | description | valid operations | example |
|---|---|---|---|
uid |
The uid of the agent |
|
|
name |
The name of the agent |
|
|
ip |
The apparent IP address of the agent |
|
|
socket |
The agent’s remote socket address |
|
|
local_ip |
The IP address of the agent’s local socket |
|
|
local_socket |
The agent’s local socket address |
|
|
os |
The reported operating system of the agent |
|
|
version |
The NXLog Enterprise Edition agent’s version number |
|
|
net |
The apparent network the agent is part of (exact match only) |
|
|
module |
The canonical name of the module |
|
|
label |
The name and value of the label provided by the agent. See the examples for details |
|
|
state |
The state of the agent ( |
|
|
digest |
The agent’s certificate sha256 digest formatted as lowercase hex |
|
|
Supported Operations
=-
Checks for an exact equality
like-
Checks for a match with a string pattern similar to that of SQL. An unescaped
_will act as a wildcard and allow any character. An unescaped%will allow any number of any character. This may be used to check whether an attribute starts with, ends with, or contains a pattern. regex-
Checks for a regex match
in-
Checks whether the attribute is in a given container. This allows you to check whether an attribute is found in a list of literals eg.
name in (agent-1, agent-2), but it also allows searching within networks eg.ip in 192.168.1.0/24.
NXLog Agent Minder Enrollment Request Format
| field | description | format |
|---|---|---|
certificate |
optional parameters for agent’s certificate generation |
see description of the |
connection |
mandatory connection options of the agent |
see description of the |
confdir-path |
optional path to the |
string containing path to the |
certdir-path |
optional path to the |
string containing path to the |
extra-params |
optional collection of additional |
object with keys representing additional parameter names and values representing parameter values; note that the values are saved as is and no quotation is added |
extra-ro-acls |
optional collection of additional read-only ACLs. |
object with keys representing ACL names and values representing ACL |
extra-wo-acls |
optional collection of additional write-only ACLs. |
object with keys representing ACL names and values representing ACL |
extra-rw-acls |
optional collection of additional ACLs with both read and write access. |
object with keys representing ACL names and values representing ACL |
extra-labels |
optional collection of additional labels. |
object with keys representing label names and values representing label values; note that the values are saved as is and no quotation is added |
| field | description | format |
|---|---|---|
common-name |
optional common name ( |
string; agent’s hostname is used if this field is unspecified or |
country |
optional country ( |
string containing two-letter country code; country ( |
state |
optional state ( |
string; state ( |
locality |
optional locality ( |
string; locality ( |
organization |
optional organization ( |
string; organization ( |
organization-unit |
optional organization unit ( |
string; organization unit ( |
not-before |
optional |
string containing time in ASN.1, RFC3339 or RFC2822 format; |
not-after |
optional |
string containing time in ASN.1, RFC3339 or RFC2822 format; |
serial |
optional |
non-negative integer; randomly generated value is used if this field is unspecified or |
encrypt_key |
optional controls whether to encrypt agent’s private key (with a randomly generated password) |
boolean; agent’s private key is unencrypted if this field is unspecified |
| field | description | format |
|---|---|---|
mode |
mandatory connection mode of the agent |
either "connect" or "listen" string |
address |
mandatory address to establish outgoing connection to or listen for incoming connections on |
string containing NXLog Agent Minder’s IP address or hostname and agent management port in "ADDRESS:PORT" format |
Minimal Enrollment Request Example
{
"connection": {
"mode": "connect",
"address": "192.168.1.1:4041"
}
}Full Enrollment Request Example
{
"certificate": {
"common-name": "agent",
"country": "US",
"state": "CA",
"locality": "San-Francisco",
"organization": "NXLog",
"organization-unit": "Dev",
"not-before": "20200101000000Z",
"not-after": "20201231235959Z",
"serial": 128
},
"connection": {
"mode": "connect",
"address": "192.168.1.1:4041"
},
"extra-params": {
"ReversionTimeout": "10"
},
"extra-ro-acls": {
"ro-acl": "\"/var/ro\""
},
"extra-wo-acls": {
"wo-acl": "\"/var/wo\""
},
"extra-rw-acls": {
"rw-acl1": "\"/var/rw1\"",
"rw-acl2": "\"/var/rw2\""
},
"extra-labels": {
"first": "\"foo\"",
"second": "\"bar\""
}
}Prometheus Metrics
Minder exposes Prometheus metrics on BASE_URI/metrics endpoint.
Minder provides 11 metrics for itself, 2 global metrics about agents, 13 metrics per agent and 4 metrics per module.
To get the number of data series (\(C_t\)) in the metrics store one would multiply the number of minder instances (\(C_m\)) by \(11+2\), then add the number of agents (\(C_a\)) multiplied by 13 and the number of modules (\(C_m'\)) multiplied by 4.
In a concrete example, where a single minder instance serves 100 agents what have 2 modules each:
This comes to 2213 time series.
Metrics endpoint uses the same credentials as all other API endpoints!
| metric | labels | description |
|---|---|---|
minder_cpu_load |
- |
CPU load of the minder |
minder_memory_usage |
- |
Memory usage of the minder |
minder_requests |
- |
Total amount of requests to the minder’s API |
minder_response_time |
- |
Histogram of response times of the minder’s API |
minder_errors |
- |
Total amount of errors returned by the minder’s API |
agents |
- |
Total amount of agents connected |
agents_connect |
- |
Amount of agents connected in 'connect' mode |
agents_listen |
- |
Amount of agents connected in 'listen' mode |
agent_state |
|
Agent’s state: |
agent_requests |
|
Total amount of requests to the agent |
agent_response_time |
|
Histogram of response times of the agent |
agent_transport_errors |
|
Total amount of transport errors while communicating with the agent |
agent_cpu_load |
|
load of the agent as in RFC546 |
agent_memory_usage |
|
Memory usage of the agent |
module_events_received |
|
Total amounts of the events received by the module of the agent |
module_events_dropped |
|
Total amount of the events dropped by the module of the agent |
module_events_forwarded |
|
Total amount of the events forwarded by the module of the agent |
module_queue_size |
|
Queue size of the module of the agent |
