stackhawk-hawkscan-install git:20260519.2e7eb0bA

Immutable. This exact content is served forever at /api/v1/blob/4298d3e99f9fc3e3.

---
description: >
  HawkScan installation: Homebrew (macOS), package installers (all platforms), prerequisites (Java 17+), verification (hawk version).
globs:
alwaysApply: false
---
# HawkScan Installation Reference

**Minimum hawk version:** This skill calls `hawk config show <section>` for live config documentation. You need hawk **v5.5.11** or later. Verify with:

```bash
hawk version
hawk config --help
```

If `hawk config` is unrecognized, upgrade hawk before running this skill.

## CLI Installation

### Homebrew (macOS — Recommended)

```bash
brew tap stackhawk/cli
brew install hawk
```

### Package Installers (All Platforms)

Downloads page: https://docs.stackhawk.com/downloads/

Check the current version:
```bash
curl -s https://api.stackhawk.com/hawkscan/version
# → 5.5.0
```

**macOS — PKG installer (includes bundled Java, recommended):**
```bash
HAWK_VERSION=$(curl -s https://api.stackhawk.com/hawkscan/version)
curl -Lo hawk.pkg "https://download.stackhawk.com/hawk/pkg/hawk-${HAWK_VERSION}.pkg"
sudo installer -pkg hawk.pkg -target /Applications
```

**Windows — MSI installer (includes bundled Java):**
```powershell
$version = Invoke-RestMethod https://api.stackhawk.com/hawkscan/version
msiexec.exe /i "https://download.stackhawk.com/hawk/msi/hawk-${version}.msi" /passive
```

**Linux / All Platforms — ZIP (requires Java 17+ installed separately):**
```bash
HAWK_VERSION=$(curl -s https://api.stackhawk.com/hawkscan/version)
curl -Lo hawk.zip "https://download.stackhawk.com/hawk/cli/hawk-${HAWK_VERSION}.zip"
unzip hawk.zip
echo "export PATH=\$HOME/hawk-${HAWK_VERSION}:\$PATH" >> ~/.zshrc && source ~/.zshrc
```

Direct download URL patterns (substitute version):
- macOS PKG: `https://download.stackhawk.com/hawk/pkg/hawk-{VERSION}.pkg`
- Windows MSI: `https://download.stackhawk.com/hawk/msi/hawk-{VERSION}.msi`
- ZIP (all): `https://download.stackhawk.com/hawk/cli/hawk-{VERSION}.zip`

### Prerequisites

- **Java 17 or higher** is required
- macOS and Windows installers bundle Java automatically
- Linux users may need to install Java separately

### Verify Installation

```bash
hawk version
```

---

## Post-Install Setup

### Authenticate with `hawk init`

```bash
hawk init
```

When prompted, enter your StackHawk API key (format: `hawk.xxxxxxxxxx.xxxxxxxxxx`).
This saves the key to `~/.hawk/hawk.properties`.

**To get an API key:**
1. Log into https://app.stackhawk.com
2. Go to Settings → API Keys
3. Create or copy an existing key (keys only display once on creation)

### Set `HAWK_API_KEY` Environment Variable (Alternative)

Instead of `hawk init`, you can set the key as an env var:

**Bash/Zsh:**
```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
```

Either method works — `hawk init` writes to `~/.hawk/hawk.properties`, while the env
var approach uses shell config. The CLI itself reads the `API_KEY` env var (not
`HAWK_API_KEY`); these skills standardize on `HAWK_API_KEY` as the user-facing
name and bridge it inline at every CLI invocation (e.g.
`API_KEY=$HAWK_API_KEY hawk scan`). The CLI resolves keys in this order:
`--api-key` flag → `API_KEY` env var → `~/.hawk/hawk.properties`.

---

## Docker (Alternative to CLI)

If you prefer Docker over the CLI:

```bash
docker pull stackhawk/hawkscan:latest
```

No Java or CLI installation needed. See `references/docker-usage.md` for run commands.

**Trade-offs:**
- Docker requires `--network host` (Linux) or `host.docker.internal` (Mac/Windows) to
  reach apps on localhost
- CLI is faster for local iteration and has simpler localhost networking
- Docker is better for CI environments that already have Docker available