Stackhawk Security Consultant

Configures and optimizes StackHawk DAST scanning pipelines to automate API security testing within CI/CD workflows.

When to Use This Agent

Choose this agent when you need to:

• Set up StackHawk dynamic application security testing for a web application or API with proper attack surface analysis
• Generate stackhawk.yml configurations and GitHub Actions workflows tailored to your detected framework and auth patterns
• Triage and remediate StackHawk scan findings with prioritized fix recommendations and false positive management

Consider alternatives when:

• You need static application security testing (SAST) on source code rather than runtime DAST scanning against a live application
• Your application is a library or package without HTTP endpoints, where DAST scanning provides no meaningful attack surface coverage

Quick Start

Configuration

Copy
name: stackhawk-security-consultant
type: agent
category: security

Example Invocation

Copy
claude agent:invoke stackhawk-security-consultant "Set up StackHawk security testing for our Express.js API"

Example Output

Attack Surface Assessment: Express.js API

Repository Analysis:
  Framework: Express.js (Node.js)
  API Routes: 24 endpoints detected
  Auth: JWT via passport-jwt middleware
  Host: http://localhost:3000 (from package.json start script)

Generated Files:
  1. stackhawk.yml
     - applicationId: ${HAWK_APP_ID}
     - host: http://localhost:3000
     - authentication: token (JWT bearer)
     - openApiConf: ./openapi.yaml (detected)

  2. .github/workflows/stackhawk.yml
     - Trigger: pull_request + push to main
     - Steps: checkout, npm install, npm start, hawkscan

Required Secrets:
  - HAWK_API_KEY (Settings > Secrets > Actions)
  - HAWK_APP_ID (from app.stackhawk.com)

TODOs:
  - [ ] Add JWT test credentials to workflow env
  - [ ] Verify OpenAPI spec path is current

Core Concepts

DAST Scanning Pipeline Overview

Aspect	Details
Attack Surface Analysis	Repository classification (application vs library), endpoint enumeration, auth mechanism detection
Configuration Generation	stackhawk.yml with host, app ID, environment, authentication type, and OpenAPI spec references
CI/CD Integration	GitHub Actions workflow with dependency install, application startup, and hawkscan-action execution
Authentication Handling	Token-based (JWT/Bearer), cookie-based (session), OAuth flows, or external auth provider configuration
Finding Management	Severity classification, false positive triaging, remediation guidance, and compliance reporting

DAST Pipeline Architecture

┌─────────────┐    ┌─────────────┐    ┌──────────────┐
│  PR / Push   │───>│  CI Runner  │───>│  App Startup │
│  Trigger     │    │  (ubuntu)   │    │  (localhost)  │
└─────────────┘    └─────────────┘    └──────┬───────┘
                                              │
                   ┌─────────────┐    ┌───────┴──────┐
                   │  Results &  │<───│  HawkScan    │
                   │  Findings   │    │  Execution   │
                   │             │    │              │
                   │ StackHawk   │    │ Crawl Routes │
                   │ Dashboard   │    │ Fuzz Inputs  │
                   │ PR Comments │    │ Test Auth    │
                   └─────────────┘    └──────────────┘

Configuration

Parameter	Type	Default	Description
applicationId	string	"${HAWK_APP_ID}"	StackHawk application identifier from the platform dashboard
scanEnvironment	string	"Development"	Target environment label: Development, Staging, or Production
hostUri	string	"http://localhost:3000"	Base URL where the application is accessible during CI scan execution
authType	string	"none"	Authentication mechanism: none, token, cookie, oauth, or external
openApiSpec	string	""	Path to OpenAPI/Swagger specification file for guided route scanning

Best Practices

1. Assess Attack Surface Before Configuring Scans - Not every repository warrants DAST scanning. Libraries, documentation sites, and static assets lack HTTP endpoints to test. Analyze the repository for web server code, API route definitions, and authentication middleware before investing in scan configuration, and clearly document why a repository was included or excluded.

2. Use OpenAPI Specifications for Guided Scanning - Crawler-based discovery misses endpoints behind authentication, conditional routing, or dynamic path parameters. Providing an OpenAPI or Swagger specification to StackHawk ensures comprehensive route coverage, reduces scan time by eliminating aimless crawling, and produces more accurate findings by testing documented parameter types.

3. Configure Authentication with Dedicated Test Credentials - DAST scans that cannot authenticate only test the unauthenticated attack surface, missing vulnerabilities behind login walls. Create dedicated test accounts with known credentials stored as CI secrets, and configure the authentication section in stackhawk.yml to obtain and use valid tokens during scanning.

4. Integrate Scan Results into Pull Request Workflows - Running scans only on scheduled builds delays vulnerability discovery. Triggering StackHawk scans on pull requests surfaces security issues before code merges, provides developers with immediate feedback in the PR context, and prevents vulnerable code from reaching the main branch where remediation costs increase.

5. Triage Findings Promptly to Prevent Alert Fatigue - Unreviewed scan results accumulate quickly and developers learn to ignore them. Establish a triage cadence where findings are classified as true positives requiring fixes, false positives to be suppressed, or accepted risks with documented justification. Use StackHawk's finding management features to track disposition decisions.

Common Issues

1. Application Not Running When Scan Executes - The most frequent CI failure occurs when hawkscan starts before the application is fully initialized. Add a health check wait step between application startup and scan execution, using a curl loop against the health endpoint with a timeout. Without a responsive target, every scan request fails with connection refused errors.

2. Scan Returns Zero Findings on Authenticated Endpoints - When authentication configuration is missing or misconfigured, StackHawk receives 401/403 responses and cannot test protected routes. Verify that the auth section in stackhawk.yml matches your actual auth mechanism, test credentials are valid, and token acquisition succeeds by checking scan logs for authentication step results.

3. OpenAPI Spec Out of Sync with Actual Routes - When the specification file diverges from implemented endpoints, scans test routes that no longer exist while missing newly added endpoints. Integrate OpenAPI spec generation into your build pipeline so the specification is always current, or use StackHawk's crawler mode as a fallback for discovering undocumented routes.