Install Hipcheck

This page covers different mechanisms for installing Hipcheck. It's organized between direct installation and container-based installation.

Installing Directly

Use the following instructions if you want to install Hipcheck onto your local system outside of a container. If you want to install Hipcheck inside of a container, see the container installation instructions.

Install from Script

The easiest way to install Hipcheck is to use an install script included with each release.

macOS Linux Windows 
curl -LsSf https://mitre.github.io/hipcheck/dl/install.sh | sh
Setting up post-install

After running the install script, run hc setup to set up your local configuration and script files so Hipcheck can run.

We currently provide prebuilt binaries for the following targets:

  • x64 Linux: x86_64-unknown-linux-gnu
  • x64 Windows: x86_64-pc-windows-msvc
  • Apple Silicon macOS: aarch64-apple-darwin
  • Intel macOS: x86_64-apple-darwin

We provide installation shell scripts for:

  • POSIX-compliant shells: recommended on Linux, macOS, and in the Windows Subsystem for Linux (WSL) on Windows.
  • PowerShell: recommended on Windows.

These scripts install the Hipcheck binary and the Hipcheck self-updater.

Install Script Security

Some users may be uncertain about using an install script piped into a shell command. For those users, you can download each install script by hand before running it. The scripts are included in the set of artifacts bundled with each Hipcheck release.

The scripts themselves are only downloaded over TLS-protected connections, and the artifacts are checked against SHA-256 hashes also included with each release to ensure artifact integrity.

Install from Source

If you're on a platform for which Hipcheck does not provide pre-built binaries, or want to modify Hipcheck's default release build in some way, you will need to build Hipcheck from source.

To build Hipcheck from source, you'll need:

If you only want to build from source without configuring the build in any way, you can use cargo install to install Hipcheck into a Cargo0-specific binary directory with the source found from Crates.io.

$ cargo install hipcheck

If you do want to build from source and configure the build or modify Hipcheck itself before building, you'll also need:

You can then clone the Hipcheck repository with Git, make whatever build modifications you want to make, and then install with:

$ git clone https://github.com/mitre/hipcheck
$ cd hipcheck
$ cargo install --path hipcheck
Setting up post-install

After running the install script, run hc setup to set up your local configuration and script files so Hipcheck can run.

This will install the hc binary into your Cargo-specific binary directory.

Disadvantages of this Approach

Same as with the cargo-binstall installation, installing Hipcheck this way does work, but does not install the Hipcheck self-updater, which the recommended install scripts do install. If you want Hipcheck to be able to update itself to newer versions, you'll need to install it with an install script or install the self-updater yourself.

Using in a Container

Hipcheck can also be used inside of a container in Docker, Podman, and other container-based systems.

The Hipcheck project maintains an official Containerfile which describes the Hipcheck container, and publishes images to Docker Hub with each new release.

Using Docker Hub

Hipcheck publishes container images to Docker Hub under the mitre/hipcheck namespace. In general, we maintain a latest tag which always refers to the most-recently published version, as well as tags for each individual version.

You can use these with Docker by default, or with any other container system which you have configured to be able to pull container images from Docker Hub.

For example, to run a short-lived container with Docker using the most recent Hipcheck image, you might run:

$ docker run mitre/hipcheck:latest

Using the Containerfile

You can also run Hipcheck from the local Containerfile, first by building the image, and then by running that image. For example, with Docker:

To do this you will need Git to get a local copy of the repository, or to download the repository contents from GitHub without the Git history.

$ git clone https://github.com/mitre/hipcheck
$ cd hipcheck
$ docker build -f dist/Containerfile .

This will build the image, which you can then use normally.

Deprecated Methods

The following section lists any methods which were supported at one point for prior versions of Hipcheck. They're recorded here in case you need to use one of these older versions, but they are not recommended regardless, and can't be used at all with newer versions.

Install with cargo-binstall

Deprecated in 3.8.0

This method is deprecated as of version 3.8.0. You can use this method to install old versions of Hipcheck, but it will not work for newer versions.

Read RFD #7: Simplified Release Procedures to learn more.

Hipcheck is written in Rust, and releases of Hipcheck are published to Crates.io, the official Rust open source package host. The Rust ecosystem has a popular tool, called cargo-binstall that can search for and install prebuilt binaries for packages published to Crates.io.

To install Hipcheck with cargo-binstall, you'll need:

Then you can run:

$ cargo binstall hipcheck
Setting up post-install

After running the install script, run hc setup to set up your local configuration and script files so Hipcheck can run.

This will install the latest version of Hipcheck. To install a specific older version instead, replace hipcheck with hipcheck@<VERSION>, replacing <VERSION> with the version you need.

Disadvantages of this Approach

Installing Hipcheck with cargo-binstall does work, but does not install the Hipcheck self-updater, which the recommended install scripts do install. If you want Hipcheck to be able to update itself to newer versions, you'll need to install it with an install script or install the self-updater yourself.

Why Hipcheck?