💡How it Works

Ax doesn't have any APIs; it's purely a command-line tool. Moreover, Ax doesn't even interact with any cloud provider's APIs directly. Instead, Ax wraps the cloud provider's CLI to perform cloud operations, simplifying the process. By wrapping the cloud provider's CLI, we eliminate the need to write API calls for each operation, abstracting some complexity.

The cloud provider CLI functions are stored in ~/.axiom/providers.

Installation Flow

When you setup the Ax Controller on a supported OS, the required dependencies are first installed.

Then you pick what shell you'd like to use, either bash, zsh or oh my zsh

You'll have an option to install Golang (not required).

Then ax configure kicks off ax account-setup, where you decide what cloud provider to use.

When you select a cloud provider, ax account-setup calls the associated cloud provider's account-helpers script. This script installs and setups the CLI and Ax account profile.

After providing a valid authentication token, you select the region where you want to deploy, along with the desired instance size (CPU, RAM). Finally, you choose a name for the Ax account profile, which stores your cloud account credentials and other user profile information in ~/.axiom/accounts/$profile-name.json.

ax account-setup then calls ax build. ax build creates the Packer image based on the Provisioner file chosen.

After choosing your Provisioner, Packer creates a temporary cloud instance, installs all the tools found in the Provisioner file, takes a snapshot of the image and saves it. Then Packer deletes the temporary instance.

When the build completes you should see a success message like the one below. You might need to restart your shell.

Ax SSH Config

Ax creates its own sshconfig located in ~/.axiom/.sshconfig

The sshconfig is how the Ax Controller communicates to the Ax instances (fleets).

The sshconfig is generated based on your cloud inventory and allows you to connect to your Ax instances over their public or private network interface. Most Ax scripts generate a fresh SSH config before executing. You can always regenerate the sshconfig manually with ax ssh --just-generate or lock the sshconfig to prevent Ax from ever regenerating ax ssh --just-generate lock. To unlock the sshconfig run ax ssh --just-generate

ax scan

After you spin up some instances, you can run ax scan to perform a distributed scan using those instances (fleet).

The first argument passed to ax scan must always be an input file (bunch of IPs or URLs etc). ax scan takes a user provided input file and divides the input file by how many instances currently selected (ax select).

In this case, we have a target list of five lines and five instances selected. So each instance will scan one target. You can also pass additional arguments to the underlying module by simply appending them to the command line.

ax scan begins by using SSH to create a scan working directory on the remote instances at /home/op/scan/$module-$timestamp/. You can see what ax scan uploads by using ax ssh to connect to any instance and navigating to the scan working directory on the remote instance.

When an instance completes its operation, Ax creates a file named after the instance's hostname in the scan working directory on the remote instance. Ax continuously checks for these hostname files to determine the completion status of all instances. Once all instances have created their hostname files, or if Ax can no longer reach any of the instances, the scan is considered complete. Scan results are periodically downloaded throughout the process and once again when the scan finishes.

During the scan, you can view the results periodically downloaded to ~/axiom/tmp/$module+$timestamp/. Once the scan is complete, the results from all scanners are merged and moved to ~/axiom/logs/$module+$timestamp/.

You can check which instances have completed their scans by navigating to the local temporary scan directory and displaying the contents of status/completed/hosts.

You can also monitor any instance in real-time by using ax ssh to connect and attach to the tmux session. A unique tmux session, named $module+$timestamp, is created on each remote instance to manage the scan.

More Info

In summary, Ax simplifies the distribution of arbitrary binaries and scripts by configuring your cloud account CLI, building Packer images, and deploying fleets of new instances. It dynamically splits and uploads an input file to all selected instances, executing the same command across each one. Upon completing the scan, Ax downloads and merges the scan output.

For more information, continue to Ax Utility Scripts or Scans!