api · diff
v2.6.1 to v2.6.2
1 added, 1 removed. Audit A to A.
---
name: api
- version: 2.6.1
+ version: 2.6.2
description: >
Use this skill when a user or agent needs to query the StackHawk platform for
security reporting, findings analysis, or app management. Triggers include:
"stackhawk api", "security posture", "findings report", "show me findings",
"untriaged findings", "which apps", "scan history", "security dashboard",
"triage", "what needs attention". Uses the hawk CLI (`hawk op` subcommand) for
all platform queries. Do NOT use for running scans (use the hawkscan skill for
"scan my app", "hawkscan", "stackhawk.yml", "DAST") or for fixing/remediating
code or vulnerabilities — this skill only reads and reports platform data.
---
# StackHawk API Skill
This skill enables Claude to act as a security reporting agent against the StackHawk
platform. The core workflow is:
**Question → Authenticate → Query API via `hawk op` → Present Results → Suggest Next Actions**
All platform queries run through the `hawk` binary's `op` subtree
(`hawk op …`). It authenticates, refreshes tokens, follows pagination, and
emits stable JSON. There is no raw-REST fallback — if `hawk` is unavailable,
install it and run `hawk init --browser` rather than hand-rolling curl.
See [`references/hawk-op-shortcuts.md`](references/hawk-op-shortcuts.md).
---
## Step 1: Assess Context
Before making any calls, check what's available:
1. **Is `hawk` installed and configured?** (`hawk version` reports v6.0.0 or greater)
```bash
# Identify the driving skill for CLI usage telemetry (read by hawk/hawkop).
export _STACKHAWK_SKILL=api
command -v hawk >/dev/null && hawk op status
```
- valid org + JWT → proceed.
- installed but unconfigured → `hawk init --browser` (interactive; the combined binary
has no `hawk op init` — `hawk init` writes `~/.hawk/hawk.properties`, which
`hawk op` reads along with the `HAWK_API_KEY` env var).
- not installed → instruct the user to install the `hawk` CLI (docs:
[docs.stackhawk.com](https://docs.stackhawk.com)) and stop; do **not** fall back to curl.
2. **Is `hawk op` authenticated?** For interactive local use, `hawk init --browser` stores
credentials in `~/.hawk/hawk.properties` — no env var needed for interactive
sessions. Verify:
```bash
hawk op status
```
> **Any non-interactive session** (CI, containers, headless agents): set `HAWK_API_KEY`.
> `hawk op` reads it directly — no config file, no browser.
3. **Is `orgId` known?** Required for most endpoints.
- `hawk op org get` returns the active org UUID.
- `hawk op org set <ID>` switches the default org.
4. **Route based on user intent:**
| User says... | Go to... |
|---|---|
| "What's my security posture?" or "dashboard" | Step 3 (org summary) |
| "Tell me about [app]'s findings" or "what needs attention" | Step 4 (app deep dive) |
| "What apps haven't been scanned recently?" | Step 3 with stale-app focus |
| "What changed since last week?" or "what's new" | Step 4 with diff recipe |
| "Show me untriaged findings" | Step 3, then drill into Step 4 for flagged apps |
---
## Step 2: Authenticate
`hawk init --browser` once for interactive setup — the CLI stores credentials in
`~/.hawk/hawk.properties` and `hawk op` handles token refresh and `401` retry on
every call. No further auth work for this skill.
→ Full setup commands (install, CI env var, profiles for org switching):
[`references/hawk-op-shortcuts.md`](references/hawk-op-shortcuts.md#setup-once).
---
## Step 3: Org Posture Summary
**Goal:** Give the user a bird's-eye view of security health across all apps and environments.
### Approach
Use `hawk op app list` and `hawk op scan list` to assemble an org-level view.
`hawk op app list --format json` returns app metadata; `hawk op scan list --format json`
returns per-scan severity counts. Join on `applicationId` to build a posture table.
```bash
# All apps with metadata (team, type, env count)
hawk op app list --format json
# Recent scans across the org — has per-scan severity counts
hawk op scan list --limit 500 --format json
```
Fields available per scan: `highAlertCount`, `mediumAlertCount`, `lowAlertCount`,
`applicationId`, `environmentName`, `startedTimestamp`, `status`.
### Present as a table
Format the response as:
| App | Environment | High | Medium | Low | Last Scan |
|-----|-------------|------|--------|-----|-----------|
| My API | Production | 3 | 7 | 12 | 2024-01-15 |
| Auth Service | Staging | 0 | 2 | 4 | 2024-01-10 |
Resolve `applicationId` → app name via `hawk op app list --format json`.
### Flag priority items
- **Stale apps**: `startedTimestamp` older than 30 days — flag as "No recent scan"
- **High severity hotspots**: environments with `highAlertCount > 0`, sorted descending
- **Incomplete scans**: `status` not `COMPLETED` — may indicate config issues
### After presenting the table
Offer to drill down on any flagged app:
- "App X has 3 unaddressed High findings — shall I pull the full finding details?"
- → Step 4 for any app the user selects
Full recipe with jq transforms:
→ [`references/reporting-recipes.md`](references/reporting-recipes.md)
---
## Step 4: App Deep Dive
**Goal:** Get specific finding details for a single app — what was found, where, and what it means.
### `hawk op scan get` (one command covers ~90% of cases)
`hawk op scan get` walks the scan → alerts → findings chain internally. No manual drill-down, no ID extraction, no token handling.
```bash
# Latest scan for an app — overview + alerts table
hawk op scan get --app "<APP_NAME>"
# Full findings with HTTP evidence + remediation (best for AI agent reasoning)
hawk op scan get --app "<APP_NAME>" --detail full --format json
```
`--detail full` returns every alert, every affected URI, HTTP messages (subject to
`--max-body-size`), and remediation guidance in one JSON blob. It fetches per-plugin detail for
at most **10 plugins per call** (the CLI prints "Fetching 10 plugin details"); for a
scan with more alert types, drill the rest with `--plugin-id`, or read the scanner's own
`hawk scan --json-output` file, which is the complete list.
→ Specific scan IDs, single-alert / single-URI drill-down, `--max-findings` tuning:
[`references/hawk-op-shortcuts.md`](references/hawk-op-shortcuts.md#2--app-deep-dive-scan--alerts--findings) §2.
### Present findings
Show a structured summary:
- **Scan summary**: date, duration, total alerts by severity
- **Alert breakdown**: alert name, severity, CWE, number of affected paths
- **Finding details**: for High severity — affected URI, HTTP method, parameter, triage status
Link to the scan on the platform:
```
https://app.stackhawk.com/scans/{scanId}
```
### "What changed?" — diff recipe
Compare two scans: use `hawk op scan list` to get the two most recent scan IDs for
the app, pull alerts for each via `hawk op scan get`, diff the `pluginId` sets.
→ Executable recipe (`hawk op` pipeline with `comm` diff):
[`references/hawk-op-shortcuts.md`](references/hawk-op-shortcuts.md#2--app-deep-dive-scan--alerts--findings) §2.
→ Full jq recipes: [`references/reporting-recipes.md`](references/reporting-recipes.md).
---
## Step 5: Present Results and Suggest Next Actions
### Formatting
- Use **tables** for multi-app/multi-finding summaries
- Use **structured lists** for single-app deep dives
- Include the platform link (`app.stackhawk.com/scans/{scanId}`) whenever referencing a specific scan
- Show triage status (`NEW`, `FALSE_POSITIVE`, `RISK_ACCEPTED`, `ASSIGNED`) alongside each finding
### Next action suggestions
Base suggestions on what the data shows:
| Finding | Suggested action |
|---|---|
| High severity findings present | Recommend immediate remediation; offer to hand finding details to → hawkscan skill for a re-scan to verify fixes |
| Stale apps (no scan > 30 days) | Recommend running a fresh scan → hawkscan skill |
| Clean results across all envs | Note that low path count may mean the spider needs tuning → hawkscan skill, config-patterns reference |
| Untriaged findings (`status: NEW`) | Direct to platform for triage: **app.stackhawk.com** — triage write operations are out of scope for this skill |
| `ENV_INCOMPLETE` app status | Direct to platform to complete environment configuration |
### Platform UI vs API data
**Use API data (this skill) when:**
- Generating a bulk posture report across many apps
- Comparing findings across scans programmatically
- Building a CI/CD gate decision from scan output
**Direct to platform UI when:**
- Triaging individual findings (accept, mark false positive)
- Managing API keys, team membership, or app configuration
- Viewing request/response evidence for a specific finding (or use `hawk op scan get <SCAN_ID> --uri-id <ID> --message`)
---
## Common Mistakes to Avoid
- **Don't hardcode API keys in scripts** — always reference `${HAWK_API_KEY}` in any non-interactive session (CI, containers, headless agents); store credentials via `hawk init --browser` for interactive local use; never inline the key value itself.
- **Don't confuse `orgId` with `appId`** — `hawk op scan list --app <APP_ID>` takes the app UUID. The org is implicit from config; override with `--org <ID>` if needed. Mixing them returns empty results, not an error.
- **Don't attempt triage via API** — triage write operations (accept, false positive) are not in scope for this skill. Direct users to the platform UI at app.stackhawk.com.
- **Don't report "no findings" without checking path count** — an empty findings list may mean the spider didn't crawl enough routes. Low path count on a scan is a coverage gap, not a clean bill of health. Recommend spider tuning via → hawkscan skill.
- **Don't forget `--detail full` when you need the remediation/HTTP message payload.** The default `hawk op scan get` output is the overview — it won't include per-URI evidence.