---
title: "Install & Run HawkScan"
description: "Install HawkScan on macOS, Windows, or Linux, authenticate with your StackHawk account, create a configuration file, and run your first local security scan."
url: https://docs.stackhawk.com/getting-started/install-and-run/
---

# Install & Run HawkScan

Install the HawkScan CLI and run your first security scan locally or in CI/CD

> **Note:** Using an AI coding agent? Install a [StackHawk agent skill](https://docs.stackhawk.com/ai-security/agent-skills/) — your agent handles config, scanning, and fixes automatically.

Get started with StackHawk by [creating an account](https://auth.stackhawk.com/signup), installing the scanner, and running your first application security scan in minutes. StackHawk empowers developers to identify and fix vulnerabilities early in the development cycle—before they hit production.

> **Tip:** Need an App to Scan?\
> Follow the [Automate Tests with GitHub Actions](https://docs.stackhawk.com/getting-started/javaspringvulny-gh-actions/) tutorial to see StackHawk in action with a sample app.

## Step 1: Set Up Your StackHawk Account

1. Sign up for a [StackHawk Account](https://auth.stackhawk.com/signup)
2. During setup, you’ll receive an API Key used to authenticate scans.
3. Optionally create your first Application Record in the platform—this will generate your applicationId.

## Step 2: Install HawkScan

HawkScan is StackHawk’s security testing engine that runs on your local machine or in CI/CD.

### Install with Homebrew (macOS)

The quickest way to install HawkScan on macOS is with [Homebrew](https://brew.sh/). Tap the [StackHawk formulae](https://github.com/stackhawk/homebrew-cli), trust the tap, then install the `hawk` CLI:

```shell
brew tap stackhawk/cli
brew trust stackhawk/cli
brew install hawk
```

`brew trust` tells Homebrew it may load formulae from this third-party tap. It is required when `HOMEBREW_REQUIRE_TAP_TRUST` is set, and becomes mandatory for all non-official taps in Homebrew 6.0.0 (or 5.2.0).

### Install with a Script (Linux)

On Linux, install HawkScan with the hawk CLI install script, then add it to your PATH:

```bash
curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
export PATH="$HOME/.hawk/bin:$PATH"
```

The script downloads the latest release for your architecture, checks its checksum, and installs `hawk` to `~/.hawk/bin` with no `sudo`. It works on macOS too, and there are PowerShell and cmd.exe versions for Windows. See [Install with a Script](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script) for every platform and for the options the scripts accept.

### Other Platforms

- **macOS**: Download the macOS pkg installer (Apple Silicon or Intel). [Download](https://docs.stackhawk.com/downloads/)
- **Windows**: Download the Windows MSI installer, or install per user with the PowerShell install script. [Download](https://docs.stackhawk.com/downloads/)
- **Linux**: Install with the install script, or download the Linux binary for your architecture (x64 or arm64). [Install](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script)

Looking for more downloads? Check out our [downloads page](https://docs.stackhawk.com/downloads/).

> **Note:** Note: HawkScan 6.0.0 and later bundles its own Java runtime — no JDK installation or management required on any platform.

## Step 3: Verify Installation and Authenticate

**1. Verify that HawkScan is installed** by checking your terminal for the hawk command version:

```bash
$ hawk version
```

The current version of HawkScan is 6.6.0.

**2. Authenticate to the StackHawk Platform** using your API Key:

When you first created your StackHawk account, an API key was automatically generated for you. You’ll need this key to authenticate HawkScan with your StackHawk account.

```bash
$ hawk init
```

When prompted, enter your API key. This one-time setup links HawkScan to your account so scan results can be securely stored and analyzed in the StackHawk Platform.

1. Log into the [StackHawk Platform](https://app.stackhawk.com/)
2. Go to **Settings > API Keys**
3. Use an existing key (*if you saved it previously*) or create a new one

> **Note:** An API key was automatically generated when you created your account. For security reasons, API keys are only displayed once when created. If you don’t have access to your original key, simply create a new one from the Settings page.

### Generate an API Key

StackHawk requires an API key to run scans and push results to the platform. You can manage your API keys at [Settings > API Keys](https://app.stackhawk.com/settings/apikeys).

To store your API key as an environment variable for use with HawkScan:

**Bash:**

```bash
mkdir -p ~/.hawk
echo 'export HAWK_API_KEY=hawk.xxxxxxxxxx.xxxxxxxxxx' > ~/.hawk/hawk.rc
source ~/.hawk/hawk.rc
```

**PowerShell:**

```powershell
mkdir "$HOME\.hawk"
echo '$env:HAWK_API_KEY="hawk.xxxxxxxxxx.xxxxxxxxxx"' > $HOME\.hawk\hawk.ps1
. $HOME\.hawk\hawk.ps1
```

Replace `hawk.xxxxxxxxxx.xxxxxxxxxx` with your actual API key.

> **Tip:** If you lose your API key or need a new one, generate a replacement at [Settings > API Keys](https://app.stackhawk.com/settings/apikeys) in the StackHawk platform.

## Step 4: Create Your Application and Configuration File

First, you’ll need to provide a valid **StackHawk Application ID**. You can do this in one of two ways:

### Option 1: Use an Existing App

If you already created an app during onboarding, you can grab the applicationId from the App Settings page in the StackHawk platform.

### Option 2: Create a New App via the CLI

If you don’t have an existing app, you can create one using the HawkScan CLI.

**Interactive (recommended for humans):**

```bash
$ hawk create app
```

You’ll be prompted for an application name:

```
Application Name: [your app name]

KaaKaww! Here is your new application ID:
XXxxXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
```

**Non-interactive (for scripts and AI agents):**

```bash
$ hawk create app --name "My App" --env Development
```

Use the `--env` flag to set the environment name — common values are `Development`, `Staging`, `Production`, and `CI`.

### Define Your Configuration

Next, you’ll create a stackhawk.yml configuration file in the root of your app. This file tells HawkScan how to run against your application, including where it’s hosted and how to behave during the scan.

Here’s a basic example:

```yaml
app:
  applicationId: [your-application-id]
  env: Development
  host: http://localhost:3000
```

- **applicationId:** The ID from the CLI or platform
- **env:** The current environment label (Development, Staging, Production, etc.)
- **host:** The base URL where your app is running

## Step 5: Run a Scan

With your stackhawk.yml file in place, run this command from your project’s root directory:

```bash
$ hawk scan
```

That’s it! HawkScan will start analyzing your application for security vulnerabilities.

## Step 6: Review the Results

After the scan completes, you’ll see the results in the StackHawk Platform.

```bash
StackHawk HAWKSCAN - v5.1.0
* app id:              xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
* env:                 Development
* scan id:             xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
* scan configs:        ['stackhawk.yml']
* app host:            https://localhost:3000
* graphql:             False

Passive scanning complete
Active scan of https://localhost:3000 complete
Scan results for https://localhost:3000
------------------------------------------------------------
Criticality: New/Triaged
   High: 0/1    Medium: 32/0    Low: 22/0
------------------------------------------------------------

View on StackHawk platform: https://app.stackhawk.com/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
```

## That’s It!

You’ve just run your first security scan with StackHawk. From here, you can:

- [Scan from your agent](https://docs.stackhawk.com/ai-security/) — let your AI coding agent run security scans autonomously
- [Optimize your scans](https://docs.stackhawk.com/getting-started/scan-optimization/) with API specs and seed paths
- [Set up authenticated scanning](https://docs.stackhawk.com/getting-started/authenticated-scan/) to test protected routes
- [Automate scans in CI/CD](https://docs.stackhawk.com/integrations/ci-cd/) with every pull request