💡How it Works
Last updated
Last updated
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.
Quick Breakdown: During the first time install, ax configure calls ax account-setup, then ax accountand finally ax build. This installs all required dependencies, installs and authenticates the cloud providers CLI, and kicks off the Packer builder to create an image with your desired tools installed.
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.
Symbolic Links: Ax supports multiple account user profiles. To list your current account user profiles, use ax account. To switch between different profiles, use ax account $profile.
For example, running ax account do switches to my Digital Ocean user profile.
cloud credentials and user profile data are stored in ~/.axiom/accounts/$profile-name.json. A symbolic link to this file is created in ~/.axiom/axiom.json.
Another important aspect of ax account is that it calls ax provider.
ax provider creates another symbolic link from the cloud providers functions in ~/.axiom/providers/$cloud-provider.sh to ~/.axiom/interact/includes/functions.sh
This dynamic linking is how Ax remains flexible. When you switch accounts, the appropriate cloud provider functions and user profile are essentially sourced.
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.
SSH Keys: By default, ax creates a SSH key named axiom_rsa in ~/.ssh/axiom_rsa. The reference to the SSH key is stored in ~/.axiom/axiom.json. You can change thesshkey value to another SSH key as long as its stored in ~/.ssh/.
You might need to rebuild (ax build) with your new SSH key to use it.
When the build completes you should see a success message like the one below. You might need to restart your shell.
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
Private Network Connectivity: When creating the sshconfig from instances private IPs (ax ssh --just-generate private) you must be on the same private network as your cloud instances.
After you spin up some instances, you can run ax scan to perform a distributed scan using those instances (fleet).
ax scan: for a detailed overview on ax scan, please visit https://ax-framework.gitbook.io/wiki/fundamentals/scan
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.
Modules: For a detailed overview on ax scan modules, please visit https://ax-framework.gitbook.io/wiki/fundamentals/scan/modules
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.
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!
