3.3.1. root¶

This is the root group of axonshell (aka running the script with no arguments).

Note

All prompts and info/warning/error messages will go to STDERR.

All –help outpout goes to STDOUT.

All exported data goes to STDOUT by default, unless -xf / –export-file in Export Options is supplied.

3.3.1.1. Command Groups¶

The entry point for axonshell has the following command groups:

adapters Commands to work with adapters and connections.
devices: Commands to work with device assets.
tools: Commands that provide extra functionality for the CLI.
users: Commands to work with user assets.

3.3.1.2. Options¶

The entry point for the command line interface provides a number of options, all of which must be supplied before any other arguments.

Example of proper ordering:

$ axonshell --proxy "https://proxy:443" devices get

Example of improper ordering:

$ axonshell devices get --proxy "https://proxy:443"

3.3.1.2.1. SSL Certificate Validation Options¶

Define a certificate file or CA bundle to use to verify the SSL certicate offered by the Axonius instance: axonshell -cp / --certpath PATH
Enable validation of the SSL certificate offered by the Axonius instance: axonshell -cv / --certverify PATH
Disable certificate validation warnings: axonshell -ncw / --no-certwarn PATH

Note

If –certpath is supplied, –certverify is automatically set to True.

If –certverify is supplied and –certpath is not and the certificate of the Axonius instance is self-signed, axonshell will exit with an error when attempting to connect.

If you want to turn off the warnings that are shown for self-signed certificates, use –no-certwarn.

3.3.1.2.2. Proxy Options¶

Define a proxy to use when connecting to the Axonius instance: axonshell -p / --proxy PROXY

Note

A proxy can be supplied numerous ways as per the requests documentation

Examples:

$ # proxy that does not require authentication
$ axonshell --proxy https://host:port

$ # proxy that requires authentication
$ axonshell --proxy https://username:password@host:port

$ # socks proxy
$ axonshell --proxy socks5://username:password@host:port

3.3.1.2.3. Logging Options¶

3.3.1.2.3.1. Logging to the Console¶

Enable logging to the console using STDERR: axonshell -c / --log-console
Console logging level: axonshell -lvlcon / --log-level-console LEVEL

Note

–log-level-console controls the overall level of logs displayed on the console.

For instance:

$ # This will only display INFO log entries and above
$ # DEBUG log entries will not show up in the console log
$ axonshell --log-console --log-level-console info --log-level-package debug

3.3.1.2.3.2. Logging to a File¶

Enable logging to a file: axonshell -f / --log-file
Control the file logging is sent to: axonshell -fn / --log-file-name
Control the directory file logging is sent to: axonshell -fp / --log-file-path
Control the size in MB that will cause a log to roll over: axonshell -fmb / --log-file-max-mb
Control how many rolled over logs are saved: axonshell -fmf / --log-file-max-files
File logging level: axonshell -lvlfile / --log-level-file LEVEL

Note

–log-level-file controls the overall level of logs sent to –log-file-name.

For instance:

$ # This will only display INFO log entries and above
$ # DEBUG log entries will not show up in the log file
$ axonshell --log-file \
            --log-level-file info \
            --log-level-package debug

$ # only send WARNING and above to console and DEBUG and above to file
$ axonshell --log-console \
            --log-console-level warning \
            --log-file \
            --log-level-file debug

3.3.1.2.4. Logging Levels¶

Control the logging levels for each component of the API client.

Package logging level: axonshell -lvlpkg / --log-level-package LEVEL
API logging level: axonshell -lvlapi / --log-level-api LEVEL
Authentication logging level: axonshell -lvlauth / --log-level-auth LEVEL
HTTP client logging level: axonshell -lvlhttp / --log-level-http LEVEL

Note

–log-level-package will override the levels for all other settings. It’s best to leave this at the lowest level (DEBUG) and set other logging levels higher.

–log-level-api controls the level of logs displayed from Users, Devices, Adapters, and Enforcement API objects.

3.3.1.2.5. Controlling HTTP Client Debug Messages¶

Enable more verbose logging of the HTTP client requests and responses. These options are useful for debugging purposes.

Log request bodies at DEBUG level: axonshell -reqbody / --log-request-body
Log response bodies at DEBUG level: axonshell -respbody / --log-response-body
Control with request attributes get logged: axonshell -reqattr / --log-request-attrs
Control with response attributes get logged: axonshell -respattr --log-response-attrs

Note

None of these will show if the overall logging level of –log-level-console, –log-level-file, –log-level-http, or –log-level-package is set to higher than DEBUG.

By default, attributes or bodies for requests or responses are logged.

3.3.1.2.6. Controlling Error Wrapping¶

Disable the error wrapping performed by the CLI by default: axonshell -nw / --no-wraperror

Note

This is useful for debugging as it allows you to see the full traceback of the exception, instead of just the string representation of the exception.

3.3.1.3. Help Page¶

3.3.1.3.1. axonshell¶

Command line interface for the Axonius API Client.

axonshell [OPTIONS] COMMAND [ARGS]...

Options

-q, --quiet, -nq, --no-quiet¶

Silence green text.

Default: False

-cook, --cookie <cookies>¶: Additional cookies to supply with every request (Example: ‘key1=value1’) (env var parsed as CSV unless starts with ‘json:’) (env var CSV delimiter uses ; instead of , if starts with ‘semi:’) (multiples)

-head, --header <headers>¶: Additional headers to supply with every request (Example: ‘key1=value1’) (env var parsed as CSV unless starts with ‘json:’) (env var CSV delimiter uses ; instead of , if starts with ‘semi:’) (multiples)

-lvlpkg, --log-level-package <log_level_package>¶

Logging level to use for entire package.

Default: debug
Options: debug | info | warning | error | fatal

-lvlhttp, --log-level-http <log_level_http>¶

Logging level to use for http client.

Default: debug
Options: debug | info | warning | error | fatal

-lvlauth, --log-level-auth <log_level_auth>¶

Logging level to use for auth client.

Default: debug
Options: debug | info | warning | error | fatal

-lvlapi, --log-level-api <log_level_api>¶

Logging level to use for API models.

Default: debug
Options: debug | info | warning | error | fatal

-lvlep, --log-level-endpoints <log_level_endpoints>¶

Logging level to use for API endpoints.

Default: info
Options: debug | info | warning | error | fatal

-lvlcon, --log-level-console <log_level_console>¶

Logging level to use for console output.

Default: debug
Options: debug | info | warning | error | fatal

-lvlfile, --log-level-file <log_level_file>¶

Logging level to use for file output.

Default: debug
Options: debug | info | warning | error | fatal

-reqattr, --log-request-attrs <log_request_attrs>¶

Log http client request attributes (multiples)

Options: url | size | method | headers | cookies | all

-respattr, --log-response-attrs <log_response_attrs>¶

Log http client response attributes (multiples)

Options: url | size | method | status | reason | elapsed | headers | cookies | all

-reqbody, --log-request-body¶: Log http client request body.

-respbody, --log-response-body¶: Log http client response body.

-c, --log-console, -nc, --no-log-console¶: Enable logging to STDERR.

-f, --log-file, -nf, --no-log-file¶: Enable logging to -fn/–log-file-name in -fp/–log-file-path.

-fr, --log-file-rotate, -nfr, --no-log-file-rotate¶: Force the log file to rotate.

-fn, --log-file-name <FILENAME>¶

Log file to save logs to if -f/–log-file supplied.

Default: axonius_api_client.log

-fp, --log-file-path <PATH>¶: Directory to use for -fn/–log-file-name (Defaults to current directory).

-fmb, --log-file-max-mb <log_file_max_mb>¶

Rollover -fn/–log-file-name at this many megabytes.

Default: 5

-fmf, --log-file-max-files <log_file_max_files>¶

Keep this many rollover logs.

Default: 5

-p, --proxy <PROXY>¶

Proxy to use to connect to Axonius.

Default

-ccb, --cert-client-both <PATH>¶: Path to client SSL certificate and private key in one file for mutual TLS.

-ccc, --cert-client-cert <PATH>¶: Path to client SSL certificate for mutual TLS.

-cck, --cert-client-key <PATH>¶: Path to client SSL private key for mutual TLS

-cp, --certpath <PATH>¶: Path to SSL certificate for verifying the certificate offered by Axonius.

-cv, --certverify¶: Perform SSL Certificate Verification (will fail if cert is self-signed or not signed by a system CA).

-ncw, --no-certwarn¶: Disable warnings for self-signed SSL certificates.

-nw, --no-wraperror¶: Show the full traceback of exceptions instead of a wrapped error.

-tc, --timeout-connect <timeout_connect>¶

Seconds to wait for connections to API

Default: 5

-tr, --timeout-response <timeout_response>¶

Seconds to wait for responses from API

Default: 900

-creds, --credentials, -keys, --keys¶

Treat key as Username and secret as password

Default: False

--version¶: Show the version and exit.

No .env file found, looking for ‘.env’

AX_ENV=

Tips:

- All of the options listed above must be supplied BEFORE any commands or groups.

- CORRECT: axonshell –log-console devices count

- INCORRECT: axonshell devices count –log-console

- All values stored in a .env file will be treated as OS environment variables.

- Almost all options throughout axonshell have an associated OS environment variable.

- Use AX_ENV to point to a custom .env file:

- bash: export AX_ENV=/path/to/.env  # for all commands in current shell
- bash: AX_ENV=/path/to/.env axonshell tools shell  # for single commands
- cmd.exe: SET AX_ENV=”c:pathto.env”
- powershell: $AX_ENV = “c:pathto.env”

- Multiple ways to specify AX_COOKIES and AX_HEADERS:

- As CSV with , as delimiter: AX_COOKIES=”key1=value1,key2=value2,key3=value4”
- As CSV with ; as delimiter: AX_COOKIES=”semi:key1=value1;key2=value2;key3=value4”
- As JSON str: AX_HEADERS=’json:{“key1”: “value1”, “key2”: “value2”}’

- Use AX_URL, AX_KEY, AX_SECRET to specify credentials

Commands

account: Group: Account commands.

adapters: Group: Work with adapters and adapter…

certs: Group: Work with SSL Certificates for the…

devices: Group: Work with device assets.

enforcements: Group: Work with the Enforcement Center.

folders: Group: Work with folders.

openapi: Group: Work with the OpenAPI YAML…

spaces: Group: Work with Dashboard Spaces.

system: Group: System control commands.

tools: Group: CLI tools.

users: Group: Work with user assets.

vulnerabilities: Group (BETA!): Work with vulnerability…