How it works

Core Philosophy

Axilock aims to take a prevention first approach, without compromising on coverage or development workflow.

Installation

Axi binary ships with an embedded installer accessible through axi install command.
Two installation processes are possible:

1. axi install - open a one time github/gitlab/bitbucket/SSO login window in browser. Recommended for individual installs.
2. axi install --api-key=KEY - uses the provided api key for installation. Recommended for MDM based installs with pre-generated api keys for all devices under an organization.

Both installation methods ensure a backend authentication has been completed in order to populate coverage information.

The installer primarily:

1. Install axi in the $AXI_HOME directory (typically ~/.axi)
2. Set global core.hooksPath to an axi controlled location (typically $AXI_HOME/hooks)
3. Create symlinks for all possible git hooks in $AXI_HOME/hooks pointing to axi binary.

This ensures axi captures all git hooks, but the story doesn't end here. If it were, user controlled hooks (local to repository directory) would never run.

Info

git considers core.hooksPath for all hooks, ie you cannot selectively have only pre-push hook at /path/to/xyz vs pre-commit hook at /another/path/to/abc, all hooks must be in a single directory.
Further, if a global core.hooksPath is set, then local hooks at .git/hooks are ignored.
If local core.hooksPath is set then global core.hooksPath is ignored.

Following flow chart covers the installation process:

Catchall hooks

The above installation ensures all git hooks are captured by axi inside the $AXI_HOME/hooks directory. In order for existing repository level hooks to run, the hooksPath must be set back to local repo directory. This can be done in local .git/config.

Catchall hooks catch any and all hooks and then installs axi pre-push hook locally into the repository. The intended behavior is similar to git's template directory with the added benefit of working in existing repositories as well.

Pre Push Hook

The locally installed pre-push hook created by catchall hooks calls axi binary thus delegating the pre push task to it.

The pre push routine inside axi runs trufflehog to identify secrets in the codebase and blocks the push if any secrets are present in any of the commits being pushed. It does not scan already pushed commits since they were not introduced by this user and thus not her responsibility.

It is also the responsibility of this routine to manage custom secret regexes for the organization.

Uninstallation

The axi uninstall command removes the $AXI_HOME directory effectively uninstalling axi from the system. It also unsets the core.hooksPath in the global git config. Whenever a pre-push is triggered after uninstallation, it will either replace itself with user defined hook (from pre-push.user) or remove itself altogether.