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

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

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

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

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.

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.

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

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…