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 most green & blue output.

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)

-cfu, --cf-url <cf_url>¶: CLOUDFLARE ACCESS TOKEN: URL to use in cloudflared commands, will fallback to url if not supplied

-cft, --cf-token <cf_token>¶: CLOUDFLARE ACCESS TOKEN: token supplied by user, will be checked for validity if not empty

-cfr, --cf-run, -ncfr, --no-cf-run¶

CLOUDFLARE ACCESS TOKEN: If no token supplied or in OS env vars, try to get token from cloudflared commands

Default:: False

-cfrac, --cf-run-access, -ncfrac, --no-cf-run-access¶

CLOUDFLARE ACCESS TOKEN: If run is True, try to get token from access token command

Default:: True

-cfrlc, --cf-run-login, -ncfrlc, --no-cf-run-login¶

CLOUDFLARE ACCESS TOKEN: If run is True and no token returned from access token command, try to get token from access login command

Default:: True

-cfp, --cf-path <cf_path>¶

CLOUDFLARE ACCESS TOKEN: Path to cloudflared binary to run, can be full path or path in OS env var $PATH

Default:: cloudflared

-cfta, --cf-timeout-access <cf_timeout_access>¶

CLOUDFLARE ACCESS TOKEN: Timeout for access token command in seconds

Default:: 60

-cftl, --cf-timeout-login <cf_timeout_login>¶

CLOUDFLARE ACCESS TOKEN: Timeout for access login command in seconds

Default:: 180

-cfe, --cf-error, -ncfe, --no-cf-error¶

CLOUDFLARE ACCESS TOKEN: Raise error if an invalid token is found or no token can be found

Default:: False

-cfeac, --cf-error-access, -ncfeac, --no-cf-error-access¶

CLOUDFLARE ACCESS TOKEN: Raise exc if access token command fails and login is False

Default:: True

-cfel, --cf-error-login, -ncfel, --no-cf-error-login¶

CLOUDFLARE ACCESS TOKEN: Raise exc if access login command fails

Default:: True

-cfec, --cf-echo, -ncfec, --no-cf-echo¶

CLOUDFLARE ACCESS TOKEN: Echo commands and results to STDERR

Default:: True

-cfev, --cf-echo-verbose, -ncfev, --no-cf-echo-verbose¶

CLOUDFLARE ACCESS TOKEN: Echo more stuff to STDERR

Default:: False

-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.

-lbl, --log-body-lines <log_body_lines>¶

Number of lines to log from request/response body.

Default:: 100

-lhs, --log-hide-secrets, -nlhs, --no-log-hide-secrets¶

Enable hiding of secrets in log output

Default:: True

-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-token <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

-lhs, --log-hide-secrets, -nlhs, --no-log-hide-secrets¶

Enable hiding of secrets in log output

Default:: True

-lmax, --log-http-max, -nlmax, --no-log-http-max¶

Shortcut to include_output http logging - overrides: log_request_body = True, log_response_body = True, log_level_http = “debug”, log_level_package = “debug”, log_level_console = “debug”, log_level_file = “debug”, log_request_attrs = “all”, log_response_attrs = “all”, log_body_lines = 10000

Default:: False

-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

-rc, --max-retries <max_retries>¶

Number of times to retry failed connections.

Default:: 3

-rb, --retry-backoff <retry_backoff>¶

Seconds to wait between retry attempts. This value is multiplied by the retry attempt.

Default:: 5

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

Treat key as Username and secret as password

Default:: False

--version¶: Show the version and exit.

Environment variables

['CF_URL', 'AX_URL']: Provide a default for --cf-url

CF_TOKEN: Provide a default for --cf-token

CF_RUN: Provide a default for --cf-run

CF_RUN_ACCESS: Provide a default for --cf-run-access

CF_RUN_LOGIN: Provide a default for --cf-run-login

CF_PATH: Provide a default for --cf-path

CF_TIMEOUT_ACCESS: Provide a default for --cf-timeout-access

CF_TIMEOUT_LOGIN: Provide a default for --cf-timeout-login

CF_ERROR: Provide a default for --cf-error

CF_ERROR_ACCESS: Provide a default for --cf-error-access

CF_ERROR_LOGIN: Provide a default for --cf-error-login

CF_ECHO: Provide a default for --cf-echo

CF_ECHO_VERBOSE: Provide a default for --cf-echo-verbose

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, AX_CREDENTIALS 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…