Command Line Interface (CLI)
Table of Contents
Options
N|Solid comes with a set of predefined endpoints for interaction and introspection that can be accessed at the command-line using the N|Solid Command Line Interface, nsolid-cli
.
The N|Solid CLI tool mirrors the Console's API schema. Many options are documented below. For commands not documented here, consult your Console's API Docs at http://localhost:6753/api/v3/api-docs (replace localhost:6753 with your Console server's address.)
To see a list of help information for nsolid-cli
, use the -h
option:
$ nsolid-cli -h
The output of the nsolid-cli
commands, unless otherwise noted, is line-delimited JSON (each line is separated by a newline delimiter \n
). The output shown in the examples below is expanded for readability.
--start
and --end
options
For commands that take --start
and --end
options, you can pass the following
formats for the date/time value:
Format |
Description |
milliseconds since epoch |
Value returned from Date.now() |
yyyy-mm-ddThh:mm:ss |
ISO date |
-Ns |
N seconds since now |
-Nm |
N minutes since now |
-Nh |
N hours since now |
-Nd |
N days since now |
0 |
Now, when used with the --end option |
--q
option
Some commands take a --q
parameter followed by a query filter expression. Only results matching all query filter terms will be returned.
A filter term is a string with no spaces separating the values.
"field+operator+value"
The field
may be any field from info or metrics, or vulns
, vuln
, or package
. See the output of those commands to see what options exist for the field
portion of the query.
The operators
for each field type are described below.
The value
can be a single value or a list of values separated by ,
. The term will evaluate to true if the field and operator match any of the specified values. Values may escape any character by preceding it with the %
character. In practice, the only characters that need to be escaped are %
, (space), and ,
.
A query filter expression is a list of filter terms, separated by space characters.
Here is an example showing the list
command being passed the --q
flag with a query filter expression that has two filter terms:
$ nsolid-cli list --q "vulns>=2 package=express"
String Operators
Operator |
Description |
"=" |
Evaluates to true if the field value is equal to any value in the expression |
"!=" |
Evaluates to true if the field value is not equal to any value in the expression |
"~" |
Evaluates to true if the field value wild-card matches any value in the expression |
"!~" |
Evaluates to true if the field value does not wild-card match any value in the expression |
Note that multiple string values may be specified in the expression, separated by commas.
Number Operators
Operator |
Description |
"<" |
Evaluates to true if the field value is less than the value in the expression |
"<=" |
Evaluates to true if the field value is less than or equal to the value in the expression |
">" |
Evaluates to true if the field value is greater than the value in the expression |
">=" |
Evaluates to true if the field value is greater than or equal to the value in the expression |
Package Operators
Operator |
Description |
"=" |
Evaluates to true if the field value equals the value in the expression |
"!=" |
Evaluates to true if the field value does not equal the value in the expression |
"<" |
Evaluates to true if the field value is less than the value in the expression |
"<="" |
Evaluates to true if the field value is less than or equal to the value in the expression |
">" |
Evaluates to true if the field value is greater than the value in the expression |
">=" |
Evaluates to true if the field value is greater than or equal to the value in the expression |
A value for packages fields is either package name or {package name}@{simple-semver-range}, where a simple semver range is one of:
Semver Ranges
Type |
Examples |
X-ranges |
1.2.3, 1.2, 1.2.x, 1.x, 1.2.*, etc. |
Tilde ranges |
~1.2.3, ~1.2, etc. |
Caret ranges |
^1.2.3, ^1.2, etc. |
Using the <
and >
operators will do a semver range check comparing the versions.
asset
Download an asset.
Option |
Description |
--id |
The asset id (required) |
Usage
$ nsolid-cli asset --id 217040c0-02d1-4956-8648-7fb84b78c65e > my.heapsnapshot
Asset IDs are available via the assets
command described below. The asset file itself
will be written to stdout. The N|Solid CLI tool will automatically manage decompression if the asset is compressed.
assets
Lists the assets (CPU profiles and heap snapshots) that are currently available for download.
Option |
Description |
--id |
The agent id or agent id prefix |
--app |
The NSOLID_APP value |
--hostname |
The host the process is running on |
--tag |
An NSOLID_TAGS value (may be specified multiple times) |
--type |
One of snapshot , snapshot-summary , or profile to limit the type of asset returned |
--start |
Return assets that were created after the specified time |
--end |
Return assets that were created before the specified time |
--starred |
Return only assets that have been starred |
Usage
$ nsolid-cli assets --app my-app-name --type snapshot
Returns a JSON stream including the following properties:
Property |
Description |
time |
The timestamp of the asset completion |
asset |
An asset id to use with the asset command |
type |
profile , snapshot , or snapshot-summary |
id |
The agent id |
app |
The NSOLID_APP value |
hostname |
The host the process is running on |
tags |
The NSOLID_TAGS values |
size |
The size of the asset in bytes |
compressed |
Boolean value representing whether the asset will be served as a gzip |
pid |
The operating system process id |
title |
The process title |
info |
The process info |
metrics |
The process metrics nearest the time of collection |
starred |
Boolean value representing whether the asset is starred or not |
Example JSON Result
{
"time": "2017-11-29T17:08:17.364Z",
"asset": "3011f777-b8e0-4696-ae6c-50358bce298a",
"type": "snapshot",
"id": "272470293ef95e530b1d9d072e6ed87e0c980173",
"app": "my-app-name",
"hostname": "my-computer.local",
"tags": [
"region:north",
"zone:A"
],
"size": 4288158,
"compressed": true,
"pid": 5940,
"title": "my-app-name",
"info": { ... },
"metrics": { ... },
"starred": false
}
async-activity
N|Solid can list any pending asynchronous operations and where the JavaScript callbacks will resume. This can be extremely helpful for determining how many concurrent operations a given N|Solid process is handling and what they are. It can also be useful in determining where an application is hanging, if there are any left-behind callbacks, or where there is a misuse of resources (e.g. reading the same file repetitively).
The output will list the in-flight asynchronous activity, including the function location and line of source code to reference where the callback will resume.
Option |
Description |
--id |
The agent id or agent id prefix |
Usage
$ nsolid-cli async-activity --id 5dd6f7a
Returns a JSON stream including the following properties:
Property |
Description |
handles |
An array of async operations. Usually longer-lived, larger-scale asynchronous operations, such as open sockets or timers |
requests |
An array of async operations. Usually shorter-lived, smaller-scale operations such as writing to file handles and other file-related operations |
pending |
An array of async operations. Represents async activity that is lower level. Often activity created by code inside Node.js core, like DNS lookups, signal handlers and TCP connections |
Example JSON Result
{
"handles": [
{
"name": "onrequest",
"location": {
"file": "nsolid-user/server-http.js",
"line": 3,
"column": 19,
"inferredName": ""
},
"anonymous": false,
"code": "function onrequest(req, res) { res.end('ok\n') }",
"type": {
"group": "handle",
"flag": 4,
"name": "TCP server connection"
},
"details": {
"fd": 10,
"transport": "TCP",
"connectionKey": "6::::0",
"connections": 0,
"unrefd": false
},
"metadata": {
"async_wrap_provider": "TCPWRAP",
"async_wrap_providerKey": "15"
}
},
{
"type": {
"group": "handle",
"flag": 64,
"name": "pipe socket"
},
"details": {
"fd": 1,
"transport": "Pipe",
"bytesDispatched": 0,
"hadError": false,
"host": null,
"pendingData": "<Buffer>"
},
"metadata": {
"async_wrap_provider": "PIPEWRAP",
"async_wrap_providerKey": "8"
}
},
{
"type": {
"group": "handle",
"flag": 64,
"name": "pipe socket"
},
"details": {
"fd": 2,
"transport": "Pipe",
"bytesDispatched": 57985,
"hadError": false,
"host": null,
"pendingData": "<Buffer>"
},
"metadata": {
"async_wrap_provider": "PIPEWRAP",
"async_wrap_providerKey": "8"
}
}
],
"requests": [
{
"name": "onreadFile",
"location": {
"file": "nsolid-user/server-http.js",
"line": 14,
"column": 20,
"inferredName": ""
},
"anonymous": false,
"code": "function onreadFile(err, src) {\n if (err) return console.error(err)\n readAgain()\n}",
"type": {
"group": "request",
"flag": 4,
"name": "readFile",
"api": "fs.readFile(filename[, options], callback)"
},
"details": {
"path": "nsolid-user/server-http.js",
"flag": "r",
"isUserFd": false,
"buffers": [
"<Buffer>"
],
"buffer": "<Buffer>",
"pos": 0,
"encoding": null,
"err": null
},
"metadata": {
"async_wrap_provider": "FSREQWRAP",
"async_wrap_providerKey": "3"
}
}
],
"pending": [],
"time": "2017-12-04T00:56:28.566Z",
"id": "8ed04c57f248624c6068945b68a5f023497498cd",
"app": "runtime/async-activity/03-server-http_app",
"hostname": "ebc192f5fae2"
}
custom
Invoke a custom command. For more information on custom commands, see
Custom Commands.
Option |
Description |
--id |
The agent id or id prefix (required) |
--name |
The name of the custom command (required) |
--data |
Data to be sent with the command |
Usage
$ nsolid-cli custom --id=[agent id] --name=verbose --data=off
Returns a JSON object with the following properties:
Property |
Description |
time |
The timestamp recorded for the event |
id |
The agent id |
app |
The NSOLID_APP value |
hostname |
The host the process is running on |
tags |
The NSOLID_TAGS values |
result |
The result of the custom command |
Example JSON Result
{
"time": "2017-12-04T00:56:28.566Z",
"id": "81535293aea1fe8c1e2f3f7518d8db3f96cf7b39",
"app": "nsolid2",
"hostname": "computer.local",
"tags": [
"localdev"
],
"result": {
"verbose": false
}
}
events
Subscribe to the event stream, which emits a wide array of event types and metadata.
Usage
$ nsolid-cli events
There are many types of events, and more are added all the time. Some of the primary types are described below.
Event Type |
Description |
license-updated |
The license data has been changed or verified with the license server |
field-range-changed |
The range or option set for a field has expanded or contracted |
agent-packages-added |
An agent's package list has been added or updated |
agent-found |
A new agent has connected to the console |
agent-exit |
An agent has terminated |
Example JSON Result
{"time":"2017-12-04T01:47:16.386Z","event":"license-updated","args":{"licensed":true}}
{"time":"2017-12-04T01:47:17.905Z","event":"field-range-changed","args":{"domain":"metrics","name":"loopsPerSecond","range":[0,22]}}
{"time":"2017-12-04T01:47:48.613Z","event":"agent-packages-added","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646}}
{"time":"2017-12-04T01:47:48.613Z","event":"agent-found","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646}}
{"time":"2017-12-04T01:47:53.087Z","event":"agent-exit","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646,"exitCode":0}}
events-historic
Extract the events from a range of time in the past.
Option |
Description |
--id |
An agent id |
--type |
An optional event type to only include |
--start |
Return events that occurred after the specified time |
--end |
Return events that occurred before the specified time |
Usage
$ nsolid-cli events-historic --start "-2h" --end "-1h"
generate-keypair
Returns a randomly generated keypair suitable for use in the N|Solid Console
socket configuration. If your N|Solid Console instance is running on an
untrusted network, it is recommended that you generate and use new keys.
Usage
$ nsolid-cli generate-keypair
Returns a JSON object with the following properties:
Property |
Description |
public |
Public key value. publicKey in N|Solid Console configuration, and env variable NSOLID_PUBKEY for N|Solid Runtime |
private |
Private key value. privateKey in N|Solid Console configuration |
Example JSON Result
{
"public": "[t&m}{EZH7=HR(IW:+Ttk:=r.Y$:CP+-Q&5L?2N!",
"private": "4QZof={^Pman?I?mB0o!]%z/{Jlu6:mJfl[Ms@[^"
}
info
Returns objects which contain static information about processes and the hosts
they are running on.
Option |
Description |
--id |
The full or partial agent id |
--q |
The query options (see above) |
Usage
$ nsolid-cli info
Returns a JSON stream including the following properties:
Property |
Description |
time |
Milliseconds since epoch time message was sent |
id |
The agent id |
app |
The NSOLID_APP value or name property from package.json |
appVersion |
The version property from package.json |
hostname |
The host the process is running on |
tags |
The NSOLID_TAGS values |
pid |
Operating system process id |
processStart |
The time the process started |
execPath |
Path of the executable running the application |
main |
The main module used when the application started up |
arch |
The CPU architecture |
platform |
Name of the N|Solid platform |
totalMem |
Total available memory in the system |
cpuCores |
The number of CPU cores |
cpuModel |
The CPU model |
versions |
Object describing the versions of components used in the runtime |
Example JSON Result
{
"id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
"app": "my-app-name",
"appVersion": "1.0.0",
"tags": [
"region:north",
"zone:A"
],
"pid": 14880,
"processStart": 1512335595061,
"nodeEnv": "dev",
"execPath": "/usr/bin/nsolid",
"main": "/var/my-app/app.js",
"arch": "x64",
"platform": "linux",
"hostname": "my-computer.local",
"totalMem": 8244523008,
"versions": {
"http_parser": "2.7.0",
"node": "8.10.0",
"nsolid": "3.1.0",
"v8": "6.2.414.50",
"uv": "1.19.1",
"zlib": "1.2.11",
"ares": "1.10.1-DEV",
"modules": "57",
"nghttp2": "1.25.0",
"openssl": "1.0.2n",
"icu": "60.1",
"unicode": "10.0",
"cldr": "32.0",
"tz": "2017c",
"nsolid_lib": {
"v8_profiler": "nsolid-v5.7.0-fix1",
"sodium": "nsolid-2.1.0",
"cjson": "nsolid-3.0.0",
"function_origin": "nsolid-v1.2.1",
"nan": "v2.5.1",
"cli": "v3.0.0",
"agent": "v8.0.3",
"zmq-bindings": "nsolid-2.15.4-fix1",
"zmq": "nsolid-v4.2.0-fix4",
"persistents_with_classid": "v1.1.1"
}
},
"cpuCores": 4,
"cpuModel": "Intel(R) Core(TM) i7-5600U CPU @ 2.60GHz",
"time": "2017-12-03T21:13:15.061Z"
}
list
Returns an array of all available matching N|Solid processes, along with their
most recent info
and metrics
data. The command ls
is an alias for this command.
Option |
Description |
--q |
The query object (see above) |
Usage
$ nsolid-cli list --q id=5dd6
Returns newline delimited JSON objects where each row includes the following properties:
Property |
Description |
time |
The timestamp of the last metrics payload |
info |
The object returned from the info command |
metrics |
The object returned from the metrics command |
Example JSON Result
{
"time": "2017-12-04T01:17:31.299Z",
"info": { ... },
"metrics": { ... }
}
metrics
Subscribes to the metrics for a set of agents.
Option |
Description |
--field |
A list of fields to include in the output. If unspecified, all fields will return |
--interval |
How frequently to poll for metrics data |
--q |
The query set (see above) |
Usage
$ nsolid-cli metrics
Consult the Metrics in Detail section for complete details on the metrics available.
Example JSON Result
{
"time": "2017-12-04T01:23:16.163Z",
"id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
"app": "my-app-name",
"hostname": "my-computer.local",
"tags": [
"region:north",
"zone:A"
],
"activeHandles": 750,
"activeRequests": 0,
"blockInputOpCount": 0,
"blockOutputOpCount": 19424,
"cpuPercent": 0.2666424917029181,
"cpuSpeed": 2640,
"cpuSystemPercent": 0.13332124585145905,
"cpuUserPercent": 0.13332124585145905,
"ctxSwitchInvoluntaryCount": 9988,
"ctxSwitchVoluntaryCount": 1795924,
"dns99Ptile": 0,
"dnsCount": 0,
"dnsMedian": 0,
"freeMem": 251301888,
"gcCount": 446,
"gcCpuPercent": 0,
"gcDurUs99Ptile": 409,
"gcDurUsMedian": 527,
"gcForcedCount": 0,
"gcFullCount": 0,
"gcMajorCount": 54,
"heapSizeLimit": 1501560832,
"heapTotal": 73269248,
"heapUsed": 60332056,
"httpClient99Ptile": 0,
"httpClientAbortCount": 0,
"httpClientCount": 0,
"httpClientMedian": 0,
"httpServer99Ptile": 0,
"httpServerAbortCount": 0,
"httpServerCount": 0,
"httpServerMedian": 0,
"ipcReceivedCount": 0,
"ipcSentCount": 0,
"load15m": 0.2333984375,
"load1m": 0.2265625,
"load5m": 0.28564453125,
"loopAvgTasks": 0,
"loopEstimatedLag": 0,
"loopIdlePercent": 100,
"loopTotalCount": 713,
"loopsPerSecond": 0,
"pageFaultHardCount": 0,
"pageFaultSoftCount": 132206,
"rss": 138301440,
"signalCount": 0,
"swapCount": 0,
"systemUptime": 23006,
"title": "node",
"totalAvailableSize": 1437491784,
"totalHeapSizeExecutable": 5242880,
"totalPhysicalSize": 72644376,
"uptime": 15000.85,
"user": "appuser",
"vulns": 1
}
metrics-historic
Retrieve metrics records over a historical time range. Records match the metrics
command output.
Option |
Description |
--field |
A list of fields to include in the output. If unspecified, all fields will return |
--q |
The query set (see above) |
--start |
The start of the time range |
--end |
The end of the time range |
--series |
The aggregation level of the data. Can be raw , 1m , or 1h . Defaults to raw |
Usage
$ nsolid-cli metrics-historic --start=-5m --end=-1m
packages
Returns a list of packages and modules available in the specified process.
Option |
Description |
--id |
The full agent id or prefix |
Usage
$ nsolid-cli packages --id=[agent id]
Returns a JSON object with the following properties:
Property |
Description |
id |
The agent id |
time |
The timestamp of the message |
app |
The NSOLID_APP value |
packages |
An array of package objects with details about the package and its dependencies |
vulnerabilities |
An object with vulnerability details |
Example JSON Result
{
"id": "a40827afbc3620e40887d6774249c321848d54f6",
"time": "2017-12-04T01:26:12.514Z",
"packages": [
{
"name": "my-app-name",
"version": "1.0.0",
"path": "/var/my-app",
"main": "app.js",
"dependencies": [
"node_modules/debug",
"node_modules/minimist",
"node_modules/split"
],
"dependents": [],
"vulns": []
},
{
"name": "debug",
"version": "2.2.0",
"path": "/var/my-app/node_modules/debug",
"main": "./node.js",
"dependencies": [
"../ms"
],
"dependents": [
"../.."
],
"vulns": [
"npm:debug:20170905"
]
},
{
"name": "minimist",
"version": "1.2.0",
"path": "/var/my-app/node_modules/minimist",
"main": "index.js",
"dependencies": [],
"dependents": [
"../.."
],
"vulns": []
},
{
"name": "ms",
"version": "0.7.1",
"path": "/var/my-app/node_modules/ms",
"main": "./index",
"dependencies": [],
"dependents": [
"../debug"
],
"vulns": [
"npm:ms:20170412"
]
},
{
"name": "split",
"version": "1.0.0",
"path": "/var/my-app/node_modules/split",
"dependencies": [
"../through"
],
"dependents": [
"../.."
],
"vulns": []
},
{
"name": "through",
"version": "2.3.8",
"path": "/var/my-app/node_modules/through",
"main": "index.js",
"dependencies": [],
"dependents": [
"../split"
],
"vulns": []
}
],
"vulnerabilities": [
{
"package": "debug",
"title": "Regular Expression Denial of Service (ReDoS)",
"published": "2017-09-26T03:55:05.106Z",
"credit": [
"Cristian-Alexandru Staicu"
],
"id": "npm:debug:20170905",
"ids": {
"NSP": 534,
"CWE": [
"CWE-400"
],
"CVE": [],
"ALTERNATIVE": [
"SNYK-JS-DEBUG-10762"
]
},
"vulnerable": "<2.6.9 || >=3.0.0 <3.1.0",
"severity": "low",
"description": " ... ",
"nsolidMetaData": {
"hidden": false
},
"packages": [
"/var/my-app/node_modules/debug"
],
"depsChains": [
[
"nsolid-dev-demo@1.0.0",
"debug@2.2.0"
]
],
"topLevel": 1
},
{
"package": "ms",
"title": "Regular Expression Denial of Service (ReDoS)",
"published": "2017-05-15T06:02:45.497Z",
"credit": [
"Snyk Security Research Team"
],
"id": "npm:ms:20170412",
"ids": {
"CWE": [
"CWE-400"
],
"CVE": [],
"ALTERNATIVE": [
"SNYK-JS-MS-10509"
]
},
"vulnerable": "<2.0.0",
"severity": "low",
"description": " ... ",
"nsolidMetaData": {
"hidden": false
},
"packages": [
"/var/my-app/node_modules/ms"
],
"depsChains": [
[
"nsolid-dev-demo@1.0.0",
"debug@2.2.0",
"ms@0.7.1"
]
],
"topLevel": 1
}
]
}
profile
Generates a V8 CPU profile of the specified process.
Option |
Description |
--id |
The agent id (required) |
--duration |
Duration of profile in seconds. Default is 10 minutes |
Usage
$ nsolid-cli profile --id=[agent id] > my.cpuprofile
Once the profile file has been created, it can be opened using Chrome’s
Development Tool’s CPU Profile Debugging
Tool.
Note: To load the file, Chrome requires that the generated file have the
extension .cpuprofile
.
snapshot
Generates a V8 heap snapshot of the specified process.
Option |
Description |
--id |
The agent id (required) |
Usage
$ nsolid-cli snapshot --id=[agent id] > my.heapsnapshot
Once the snapshot file has been created, it can be opened using Chrome’s Development Tool’s heap snapshot browser
Note: To load the file, Chrome requires that the generated file have the
extension .heapsnapshot
.
startup-times
Lists the time to reach certain process lifecycle startup phases from initial process execution.
Option |
Description |
--id |
The full agent id or prefix |
Usage
$ nsolid-cli startup-times
Returns a JSON stream including the following properties:
Property |
Description |
time |
Milliseconds since epoch time message was sent |
id |
The agent id |
app |
The NSOLID_APP value |
hostname |
The host the process is running on |
initialized_node |
An array of two integers. The time it took to initialize the Node internals, reported as [seconds, nanoseconds] |
initialized_v8 |
An array of two integers. The time it took to initialize the V8 engine, reported as [seconds, nanoseconds] |
loaded_environment |
An array of two integers. The time it took to complete all initialization, which includes running some of Node's internal JavaScript code, and your main module's top-level code, reported as [seconds, nanoseconds] |
Example JSON Result
{
"loaded_environment": [
0,
322526338
],
"initialized_node": [
0,
120919
],
"initialized_v8": [
0,
240910
],
"id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
"time": "2017-12-04T01:32:30.042Z",
"tags": [
"region:north",
"zone:A"
],
"app": "my-app-name",
"hostname": "my-computer.local"
}
Additional timers can be added to your application with custom lifecycle events.
vulnerabilities
Returns known security vulnerabilities for all processes.
Usage
$ nsolid-cli vulnerabilities
Returns a JSON object representing all current known vulnerabilities.
Property |
Description |
time |
Message timestamp |
vulnerabilities |
An array of vulnerability objects |
Example JSON Result
{
"time": "2017-12-04T01:34:54.805Z",
"vulnerabilities": [
{
"report": {
"package": "ms",
"title": "Regular Expression Denial of Service (DoS)",
"published": "2015-11-06T02:09:36.187Z",
"credit": [
"Adam Baldwin"
],
"id": "npm:ms:20151024",
"ids": {
"CWE": [
"CWE-400"
],
"CVE": [
"CVE-2015-8315"
],
"NSP": 46,
"ALTERNATIVE": [
"SNYK-JS-MS-10064"
]
},
"vulnerable": "<=0.7.0",
"severity": "medium",
"description": " ... ",
"nsolidMetaData": {
"hidden": false
}
},
"processes": [
{
"id": "e1c17bc36d7a9cc76ead259ace0307d4b9705646",
"app": "my-app-name",
"tags": [
"region:north",
"zone:A"
],
"hostname": "my-computer.local",
"topLevel": 1,
"depChains": [
[
"ms@0.7.0"
]
]
}
...
]
},
...
]
}
query
Subscribe to matching agent data on an interval.
Option |
Description |
--field |
List of fields to request. All fields returned if not specified |
--interval |
Number of seconds before returning next current object (default: 1) |
--q |
The query filter options (see above) |
Usage
$ nsolid-cli query --q id=5
Returns newline delimited JSON objects with framing objects.
Framing Type |
Description |
start |
The query stream start frame |
interval-start |
The start of the records for this interval |
agent-enter |
An agent entry |
summary |
Summary data about the entire (unfiltered) data set |
interval-end |
The last record for this interval frame |
Example JSON Result
{"time":"2017-12-04T01:42:29.502Z","type":"start"}
{"time":"2017-12-04T01:42:29.502Z","type":"interval-start"}
{"time":"2017-12-04T01:42:29.502Z","type":"agent-enter","id":"5dd6f7a940bfc3633cc3ffc82332640d51ce5112","info":{ ... },"metrics":{ ... }
{"time":"2017-12-04T01:42:29.502Z","type":"summary","totalAgents":9}
{"time":"2017-12-04T01:42:29.502Z","type":"interval-end"}
summary
Pull a summary of all connected N|Solid processes. Reports counts of matched properties or resources.
Option |
Description |
--q |
The query options (see above) |
Usage
$ nsolid-cli summary
Example JSON Result
{
"time": "2017-12-04T02:12:02.506Z",
"processes": 9,
"apps": {
"my-app-name": 5,
"api-server": 1,
"web": 1,
"batch-service": 2
},
"tags": {
"region:north": 4,
"zone:A": 5,
"region:south": 5,
"zone:B": 2,
"zone:C": 2
},
"rss": 693153792,
"cpu": 3.4667812728278924,
"node": {
"8.9.1": 9
},
"nsolid": {
"3.0.0": 9
},
"packages": 552,
"vulnerabilities": {
"npm:ms:20170412": 4,
"npm:qs:20140806": 2,
},
"hiddenVulnerabilities": {}
}
Policies
N|Solid ships with the ability to enable some security-related policies to help harden your application. Currently these include the ability to disable core modules and bindings.
To enable policy configuration with N|Solid, you must create a policies file in JSON format, and specify that file via the policies flag when starting N|Solid.
$ nsolid --policies my-policies.json app.js
Disabling Core Resources
N|Solid includes the ability to disable core modules with a policy file. This can be used to restrict application access to system resources or features that should not be used by your application.
Modules and bindings are the two types of core resources that can be disabled:
- modules are the JavaScript APIs of Node, e.g.
fs
or http
;
- bindings are the wrappers for native code, e.g.
stream_wrap
or tcp_wrap
.
There are four different severity levels you can configure:
Parameter |
Level |
Description |
0 |
ignore |
No notice will be provided during the loading of the module or binding. This is the default behavior |
1 |
warning |
A warning is written to stderr during the loading of the module or binding. The application otherwise runs normally |
2 |
throw error |
A error is thrown only when the policy is _violated_ which doesn't occur during the _loading_ of the module, but when a function on it is called. You can catch this by writing a try/catch in your code around your require() calls |
3 |
exit |
The application exits during the loading of the module or binding |
Disabling a module in the policy file prevents all non-core modules from using it. A warning is printed when loaded, but only when it is used does the violation handler kick in). Core modules are still able to load it (e.g. the core module library can still use fs
to read new files via require()
).
Example Policy File
# disable-dns-all.policy.json
{
"// severity levels": "0 - ignore; 1 - warning; 2 - throw error; 3 - exit",
"blacklist": {
"modules": {
"dns": 2
},
"bindings": {
"cares_wrap": 2
}
}
}
The policy file can also be used to restrict access to bindings. The example policy file above disables both the dns
module and the cares_wrap
binding, both of which can be used to access DNS.
When a non-core module attempts to access a disabled core module, messages will be logged to stdout
, and an exception thrown.
Using A Policy File
In this example, a DNS connection is made in a separate file, faux-dns.js. To implement the above policy file, disable-dns-all.policy.json, enter the following command. Note the printed result:
$ nsolid --policies disable-dns-all.policy.json faux-dns.js
nsolid error Binding "cares_wrap" is requested via a process.binding call
nsolid error at Object.<anonymous> (/Users/user/nsolid-demos/demos/faux-dns.js:3:23)
nsolid error But it was disabled in the policies.
_module_wrap.js:423
throw new Error('Binding "' + id +
^
Error: Binding "cares_wrap" has been disabled by the policies flag, using "GetAddrInfoReqWrap" on it is not allowed, terminating execution.
at new throwError (_module_wrap.js:423:11)
at Module._compile (module.js:430:26)
... more stack trace lines here
Example: Restricting Access to Modules and Bindings
The cares_wrap
binding can be used directly for DNS access. We will invoke it and restrict access with a policy file.
# fauxdns.js
module.exports = lookup;
var cares = process.binding('cares_wrap');
function lookup(hostname, callback) {
var req = new cares.GetAddrInfoReqWrap();
req.callback = callback;
req.family = 4;
req.hostname = hostname;
req.oncomplete = callback;
var err = cares.getaddrinfo(req, hostname, 4, 0);
if (err) {
callback(new Error("OOPS"));
return {};
}
return req;
}
Call the function:
# lookup.js
var look = require("./fauxdns.js");
look("nodesource.com", function (err, data) {
console.log(data);
});
Without a policy file in place, you still have access to the network via the dns
module:
$ nsolid lookup.js
[ '162.243.142.64' ]
Create a policy file that prevents just the dns
module:
# disable_dns.js
{
"blacklist": {
"modules": {
"dns": 2
}
}
But, we still have DNS access:
$ nsolid --policies disable_dns.js lookup.js
[ '162.243.142.64' ]
To prevent the circumvention of the modulesBlacklist
, we need to blacklist the cares_wrap
binding directly:
# disable_cares.json
{
"blacklist": {
"bindings": {
"cares_wrap": 2
}
}
}
The behavior is now blocked:
$ nsolid --policies disable_cares.json lookup.js
nsolid error Binding "cares_wrap" is requested via a process.binding call
nsolid error at Object.<anonymous> (/Users/user/develop/nodesource/policies/fauxdns.js:3:21)
nsolid error But it was disabled in the policies.
_module_wrap.js:423
throw new Error('Binding "' + id +
^
Error: Binding "cares_wrap" has been disabled by the policies flag, using "GetAddrInfoReqWrap" on it is not allowed, terminating execution.
at new throwError (_module_wrap.js:423:11)
at lookup (/Users/user/develop/nodesource/policies/fauxdns.js:7:13)
at Object.<anonymous> (/Users/user/develop/nodesource/policies/lookup.js:3:1)
at Module._compile (module.js:434:26)
at Object.Module._extensions..js (module.js:452:10)
at Module.load (module.js:355:32)
at Function.Module._load (module.js:310:12)
at Function.Module.runMain (module.js:475:10)
at startup (node.js:150:18)
at node.js:986:3
More Policy Usage
Example: Disabling the child_process
Module
In this example, the child_process
module is blacklisted with severity level 2
.
# disable_childprocess.json
{
"blacklist": {
"modules": {
"child_process": 2
}
}
}
Code Usage
var ls = require("child_process").execSync("ls -l")
console.log(ls.toString())
Running with Policy
$ nsolid --policies disable_childprocess.json child_process_example.js
nsolid error Module "child_process" is required
nsolid error at Object.<anonymous> (/home/bryce/ns/nsolid-node/foo.js:1:72)
nsolid error But it was disabled in the policies.
child_process.js:75
throw new Error('"' + module.id + '" has been disabled ' +
^
Error: "child_process" has been disabled by the policies flag, terminating execution.
at handleDisabledMethodCall (child_process.js:75:9)
at Object.execSync (child_process.js:89:22)
at Object.<anonymous> (/home/bryce/ns/nsolid-node/foo.js:1:96)
at Module._compile (module.js:434:26)
at Object.Module._extensions..js (module.js:452:10)
at Module.load (module.js:355:32)
at Function.Module._load (module.js:310:12)
at Function.Module.runMain (module.js:475:10)
at startup (node.js:149:18)
at node.js:985:3
JSON Comments
To be able to include comments in your JSON files, N|Solid ignores properties whose keys start with "//".
{
"//this": "is an N|Solid JSON comment"
}
N|Solid Policies and Security
N|Solid's Policies feature should not be used as a blind replacement for good security practices with regard to your code and the code of your application's dependencies. Disabling core modules and bindings does not provide a complete guarantee that your application is unable to use the features provided by those parts of Node.js.
For example, child processes interacting with Unix utilities, if not disabled, can be used to replace the functionality of many of the core modules. Some core modules may be completely re-implemented in user-land modules, such as in the dns
and cares_wrap
example. Compiled add-ons have complete freedom to insert new functionality that can replace anything that has been disabled.
N|Solid's policy features augment and support existing enterprise-wide application security hardening programs. Please contact NodeSource if you wish to discuss your Node.js application security needs and prepare a customized security hardening program that involves the use of internal and third-party code review, application monitoring, and the use of operating system security tools.
Invalid Policies
Anytime an unexpected property or a property with an invalid value is encountered, the policies are considered invalid and the process is halted.
Modules That Can Be Blacklisted
The following is a list of modules that can be blacklisted. It should be noted that for most of these modules it is rare to have a business need where blacklisting makes sense.
Module |
Description |
assert |
Used for writing unit tests for your applications, you can access it with require('assert') |
async_hooks |
Provides an API to register callbacks tracking the lifetime of asynchronous resources |
buffer |
Raw data is stored in instances of the Buffer class |
bootstrap_node |
Bootstraps the Node.js core, with a special eye on performance |
child_process |
Provides a tri-directional popen(3) facility in order to create a child process |
cluster |
Allows you to easily create child processes that all share server ports |
console |
Console object is a special instance of Console whose output is sent to stdout or stderr |
constants |
Deprecated way of accessing constant values. Updated: require('someModule').constants |
crypto |
Crypto module offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or HTTP connection |
dgram |
Provides Datagram sockets |
dns |
Provides name resolution |
domain |
Pending deprecation - provide a way to handle multiple different I/O operations as a single group |
encoding |
Converts strings from one encoding to another |
errors |
Provides an API for handling errors |
events |
Provides event emitters |
freelist |
Data structure used internally by Node.js |
fs |
Provides file I/O via simple wrappers around standard POSIX functions |
http |
Provides ability to create HTTP servers and clients |
http2 |
Provides ability to create HTTP2 servers and clients |
https |
Provides ability to create HTTPS servers and clients |
_http_agent |
Provides support for HTTP and HTTPS modules, mostly used internally |
_http_client |
Provides support for HTTP and HTTPS modules, mostly used internally |
_http_common |
Provides support for HTTP and HTTPS modules, mostly used internally |
_http_incoming |
Provides support for HTTP and HTTPS modules, mostly used internally |
_http_outgoing |
Provides support for HTTP and HTTPS modules, mostly used internally |
_http_server |
Provides support for HTTP and HTTPS modules, mostly used internally |
inspector |
Provides an API for interacting with the V8 inspector |
inspector_async_hook |
Registers async hooks with the V8 inspector |
module |
Provides the Node.js module system, mostly used internally |
net |
Net module provides asynchronous network wrapper for server and clients |
os |
Provides basic operating-system related utility functions |
path |
Provides utilities for handling and transforming file paths |
perf_hooks |
Supports collection of high resolution performance metrics |
process |
Same as the global process object |
punycode |
Provides Unicode utilities |
querystring |
Provides utilities for dealing with query strings |
readline |
Allows reading of a stream (such as process.stdin) on a line-by-line basis |
repl |
Provides a way to interactively run JavaScript and see the results |
socket_list |
Provides a way to monitor socket connections |
stream |
Provides streaming functionality |
_stream_duplex |
Provides the DuplexStream exposed via the stream module |
_stream_passthrough |
Provides the PassThroughStream exposed via the stream module |
_stream_readable |
Provides the ReadableStream exposed via the stream module |
_stream_transform |
Provides the TransformStream exposed via the stream module |
_stream_wrap |
Provides the wrapper to the libuv stream implementation, mostly used internally |
_stream_writable |
Provides the WritableStream exposed via the stream module |
string_decoder |
Decodes a buffer to a string with utf8 support |
sys |
Deprecated alias for util |
timers |
Provides internal support for global Timers |
tls |
Uses OpenSSL to provide Transport Layer Security and/or Secure Socket Layer: encrypted stream communication |
_tls_common |
Provides support for tls module, mostly used internally |
_tls_legacy |
Provides support for tls module, mostly used internally |
_tls_wrap |
Provides support for tls module, mostly used internally |
tty |
Provides the tty.ReadStream and tty.WriteStream classes |
url |
Provides utilities for URL resolution and parsing |
util |
Primarily designed to support the needs of Node.js's internal APIs, but many of these utilities are useful for user programs |
v8 |
Events and interfaces specific to the version of V8 |
vm |
Provides support to compile and run code immediately, or compile, save, and run code later |
wrap_js_stream |
Provides an interface for the C++ side of Node and a standard JS stream |
zlib |
Provides bindings to Gzip/Gunzip |
Bindings That Can Be Blacklisted
The following is a list of bindings that can be blacklisted. It should be noted that for most of these bindings it is rare to have a business need where blacklisting makes sense.
Binding |
Description |
async_wrap |
Base class for all async request modules which supports hooks into async events |
buffer |
Interface to libuv methods to operate on buffers |
cares_wrap |
Wraps the cares library for asynchronous name resolves |
config |
Build configuration |
constants |
Provides access to C++ constants |
contextify |
Interface to V8 in order to create execution contexts |
crypto |
Provides crypto functionality such as SSL and ciphers |
fs |
Interface to file system methods provided by libuv |
fs_event_wrap |
Binding to listen to file-related events in order to support watching files and directories for changes |
http_parser |
Binding to http_parser |
icu |
Internationalization API and database |
inspector |
Provides the source code for the --inspect debug tooling |
js_stream |
Binding that provides support for Node.js streams |
os |
Interface to libuv in order to obtain process state information |
performance |
Provides the code for the perf_hooks module |
pipe_wrap |
Wraps libuv's socket implementation |
process_wrap |
Provides process functionality such as spawning child processes |
serdes |
Polyfill for the Node.js 8.x serializer API |
signal_wrap |
Supports sending and handling signals to processes |
spawn_sync |
Supports child_process.execSync functionality via libuv |
stream_wrap |
Wraps stream implementations exposed by libuv to communicate via file descriptors or network connections |
tcp_wrap |
Integrates TCP functionality exposed by libuv in order to create TCP connections |
timer_wrap |
Integrates with timer functionality provided by libuv so support things like setTimeout and setInterval |
tls_wrap |
Provides TLS termination functionality via crypto |
tty_wrap |
Integrates with TTY terminal functionality provided by libuv |
udp_wrap |
Provides UDP protocol functionality such as binding and broadcasting |
url |
WhatWG URL parser |
util |
Backing code for Node's util module |
uv |
Provides libuv integration such as error name resolution |
v8 |
Limited interface to the V8 API, i.e. to set flags and get process information |
zlib |
Wraps the zlib library |