Getting Started with
the New StackHawk CLI

rebecca-warren-hex-bw

Rebecca Warren|January 13, 2022

Giving developers a more familiar way to install and interact with the StackHawk scanner.

Today we are thrilled to announce the StackHawk CLI.

Until now, running StackHawk has required a Docker container. By introducing the CLI, we remove the Docker dependency and more importantly, developers get a security tool that feels more familiar and better fits their workflow. 

The CLI has been months in the making and we can’t wait to help users get going with the tool. We have put together this getting started guide to help you get scanning and better protect your apps.

Wait…But I ❤️ The Docker Version

If you are currently using the Docker version of the StackHawk scanner, don’t worry. That version is still fully supported and has some of the great configuration validation capabilities mentioned later in this post. While the Docker version is well-suited for running in your CI/CD pipeline, the CLI is great for running on your local computer.

If you want more details on the Docker vs CLI check out the docs that explain all the differences.

A Few Resources Before We Get Going 

We will break down the CLI highlights in this blog, but there are other resources that will help guide you through this process as well. 

📺 A Video Demo

Join StackHawk engineer Omar Alkhalili as he guides you through using the CLI step-by-step. This is a great resource to watch, pause, and replay as you get going.

📝 The Docs

Wouldn’t be a release without the docs, now would it? If you are looking for all the technical details, dive into the CLI documentation.

CLI Pre-Reqs

In order to get going with the StackHawk CLI, you will need to:

  1. Have a StackHawk account. Sign-up here.

  2. Create an app in the StackHawk platform. This requires configuring an app which will provide you with an API key and a YAML config file. 

    1. Make sure you save your API key and YAML config file. 

  3. Have Java version 11 or higher.

  4. Have a way to install the CLI. This can be done with homebrew or by downloading the self-contained zip file

Once you have completed those steps, open a terminal window and get ready to hawk 🦅.

Installation

Depending on your OS and personal preference you can either install via homebrew or you can install the zip. 

We will walk through homebrew here, but if you are interested in the zip, you can find those docs here.

To install, using homebrew run the command brew install stackhawk/cli/hawk, at which point your terminal should output something like this:

StackHawk CLI Install - Pic 1 image

You are now ready to start using the CLI 🎉

CLI Commands

Getting Your Bearings: hawk --help

If you are unsure where to get started with the CLI, use the command hawk --help or hawk -h. This will provide you with a list of available commands:

Getting Started with the New StackHawk CLI - Picture 2 image

Initializing the Scanner: hawk init

To connect to the StackHawk platform use the hawk init command. Upon entering this command you will be prompted for your API key to authenticate your session. 

Once you enter your API key you should get a message that you are now authenticated!

Getting Started with the New StackHawk CLI - API Key Picture image

Note: You should have saved your API key upon creating your app in the StackHawk platform, but if you did not or your dog ate your homework, head over to the settings menu in the bottom left of the platform and you can create a new one.

Validating Your Config: hawk validate

The next step in getting scanning with the CLI is validating your config file, which by default will be named stackhawk.yml. Store this file at the base of your project’s directory. 

Once you have updated your YAML with any specific configurations not included by default (like authentication, or API configuration details), you will be ready to run the ‘hawk validate’ command. 

If your configuration file is error free, the CLI will return back a success message. 

Getting Started with the New StackHawk CLI - Picture 3 image

If your configuration file has errors, the specific lines causing the issue will be called out with error messages and suggestions for how to fix.

Getting Started with the New StackHawk CLI - Picture 4 image

Getting Scanning: hawk scan

Once you have initialized and validated your config, you are ready to complete your first scan. 

Enter the command hawk scan in your terminal and you will see your scan kick off.

Getting Started with the New StackHawk CLI - Hawk Scan Pic image

By default, the scanner will expect your config file to be named stackhawk.yml. If your config file is named something else, just append your file name to the hawk scan command. So, the command would look something like hawk scan file-name.yml

There are many other configuration modifications you can make to the hawk scan command to better fit your specific scanning scenario. 

You can learn more about these by adding the subcommand --help or -h to hawk scan, at which point your terminal should output all of the configuration options. 

Getting Started with the New StackHawk CLI - Picture 7 image

Note: The -help and -h subcommand also work with the other commands in this blog.

So Get CLI-ing

There you have the quick overview of the new StackHawk CLI. We hope you find it makes it easier to get going with your first scan, and every scan after that.

If you get going with it and have run into any issues, drop us a line at support@stackhawk.com. We would love to help you! 


Rebecca Warren  |  January 13, 2022