---
title: "Agentic StackHawk Setup Guide"
description: "Go from zero to secure — install agent skills, configure HawkScan, scan your app, fix vulnerabilities, and verify fixes in one session."
url: https://docs.stackhawk.com/ai-security/agentic-stackhawk-guide/
---

# Agentic StackHawk Setup Guide

This guide walks you through the complete agentic security testing workflow: install a StackHawk agent skill, run a security scan, fix every finding, and verify with a clean rescan — all within your AI coding agent.

## Prerequisites

Before you start, you need:

- A StackHawk account ([sign up](https://auth.stackhawk.com/wingman) or [log in](https://app.stackhawk.com))
- The `hawk` CLI installed and authenticated (`hawk init --browser` provisions your API key automatically — no separate `hawkop`, no Java)
- An application running locally that the scanner can reach, with its associated source code.

### Install the hawk CLI

The `hawk` CLI is a single self-contained binary — `hawkop` is now bundled in as `hawk op`, and no separate Java install is required.

**Tab: macOS**

```bash
brew tap stackhawk/cli && brew trust stackhawk/cli && brew install hawk
hawk init --browser
```

**Tab: Linux**

Install `hawk` with the hawk CLI [install script](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script), add it to your PATH, then authenticate:

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

**Tab: Windows**

Download and run the `hawk.exe` MSI installer from the [downloads page](https://docs.stackhawk.com/downloads/hawkscan/) — self-contained, no Java required. Or install `hawk` for your user only, with no administrator access, using the hawk CLI [install script](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script), then authenticate:

```powershell
irm https://download.stackhawk.com/hawk/install.ps1 | iex
$env:Path = "$env:USERPROFILE\.hawk\bin;$env:Path"
hawk init --browser
```

CMD users: run the cmd.exe version of the install script instead:

```bat
curl -fsSL -o "%TEMP%\hawk-install.bat" https://download.stackhawk.com/hawk/install.bat && call "%TEMP%\hawk-install.bat"
set "PATH=%USERPROFILE%\.hawk\bin;%PATH%"
hawk init --browser
```

`hawk init --browser` opens your browser to approve access, then provisions and saves your API key automatically — no copy/paste. Prefer to manage keys yourself? Create one at [app.stackhawk.com](https://app.stackhawk.com) → **Settings → API Keys**.

## Step 1: Install the Agent Skill

Choose your AI coding platform:

| Platform | Install Command |
| - | - |
| **Claude Code** | `/plugin marketplace add stackhawk/agent-skills-marketplace` then `/plugin install wingman@stackhawk` |
| **Codex** | `codex plugin marketplace add stackhawk/agent-skills-marketplace` then `codex plugin add wingman@stackhawk` |
| **Antigravity (agy)** | `agy plugin install https://github.com/stackhawk/agent-skills` |
| **GitHub Copilot** | `copilot plugin marketplace add stackhawk/agent-skills-marketplace` then `copilot plugin install wingman@stackhawk` |
| **Cursor** | Copy rules from [agent-skills](https://github.com/stackhawk/agent-skills) `cursor/` dir to `~/.cursor/rules/` — see [Cursor setup](https://docs.stackhawk.com/ai-security/agent-skills/cursor/) |

On Claude Code, Codex, and GitHub Copilot, `wingman` is the umbrella plugin — one install pulls the full skill set (hawkscan, stackhawk-api, data-seed, optimize). Cursor and Antigravity install directly from the [agent-skills](https://github.com/stackhawk/agent-skills) repo. For detailed setup instructions, see the [platform-specific guides](https://docs.stackhawk.com/ai-security/agent-skills/).

> **Note:** Model recommendation: Claude Sonnet 4.5+ and Opus perform well with multi-step security scanning workflows — app creation, auth configuration, and fix loops. GPT-4o and GPT-4.1 have shown less reliable results in our testing. If you're using GitHub Copilot or another multi-model platform, select Claude when running security scanning tasks.

## Step 2: Ask Your Agent to Scan

Tell your AI agent to set up and run a security scan:

```
Use StackHawk to set up security scanning for my app and scan it for vulnerabilities. Explain each step you take and each decision you make along the way.
```

The agent handles the rest — it will check if your app is running (and start it if needed), generate a `stackhawk.yml` configuration, validate it, and kick off the scan. Asking it to explain each step and decision shows you what it is doing and why it made each choice, which is especially useful the first time you run it. If the app isn’t reachable, the agent will tell you what to do.

## Step 3: Fix and Verify

If the scan finds vulnerabilities, tell the agent:

```
Fix all of these security findings
```

The agent reads your code, understands the vulnerability context, and makes idiomatic fixes — parameterized queries for SQL injection, output encoding for XSS, security headers for missing protections, and more.

After fixing, the agent rescans to verify all issues are resolved.

## The Autonomous Loop

With the latest agent skills, your AI agent runs this entire workflow automatically. When you finish building a feature:

1. The agent announces it’s running a security scan
2. It configures HawkScan if needed
3. It scans your application
4. If it finds vulnerabilities, it fixes all of them
5. It rescans to verify the fixes
6. It reports the results

You don’t need to ask — “done” means “done and secure.”

## Troubleshooting

The agent handles most issues automatically — config errors, unreachable apps, auth failures, low path counts. If something goes wrong during a scan, the agent will diagnose the problem and either fix it or tell you what it needs.

**If the agent skill isn’t activating:**

- Confirm it’s installed — ask your agent “What StackHawk skills do you have?”
- Check that `hawk init --browser` was run and `~/.hawk/hawk.properties` exists

**For deeper HawkScan issues**, see the [HawkScan Troubleshooting](https://docs.stackhawk.com/hawkscan/troubleshooting/) guide.