---
title: "StackHawk Security Onboarding: review, role & definition · Undominated.ai"
canonical: https://undominated.ai/agents/github-stackhawk-security-onboarding/
description: "Decides whether a repository is a deployed web app or API, and if so opens a pull request with a stackhawk.yml and a GitHub Actions scan workflow."
---

# StackHawk Security Onboarding: review, role & definition · Undominated.ai

> Decides whether a repository is a deployed web app or API, and if so opens a pull request with a stackhawk.yml and a GitHub Actions scan workflow.

[← Explore all agents](/agents/)

SECURITY AND GOVERNANCE / GitHub partners

# StackHawk Security Onboarding

Decides whether a repository is a deployed web app or API, and if so opens a pull request with a stackhawk.yml and a GitHub Actions scan workflow.

 [Use this definition ↓](#setup)[Original source ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/agents/stackhawk-security-onboarding.agent.md)

SOURCE REVIEW

 Reviewed 2026-10-13
 Evidence 5 linked sources
 Publisher GitHub partners
 Licence [MIT ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/LICENSE)
 Revision 156736fb63e9
 [Read what was—and wasn’t—checked ↓](#review)

“Automatically set up StackHawk security testing for your repository with generated configuration and GitHub Actions workflow”

 [GitHub partners · upstream description ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/agents/stackhawk-security-onboarding.agent.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Its first step assesses attack surface: it declines for libraries and documentation or configuration repositories, offers a review when stackhawk.yml already exists, and asks when unsure.
- It never guesses credentials or sensitive values. Uncertain hosts and auth settings become TODOs listed in the pull request, and only options in the StackHawk schema are allowed.

### A good fit for

 - Adding a first StackHawk API scan to an application repository
- Deciding whether a repository is an application worth API security testing or a library to skip

### Weigh up before choosing

 - The workflow template pins actions/checkout@v3 and stackhawk/hawkscan-action@v2 by tag, not by commit SHA.
- Declared tools include edit and shell. It creates a branch, two commits and a pull request.
- A scan needs a StackHawk account, HAWK_API_KEY as a repository secret and an app that starts in CI. No scan was run.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - agents/stackhawk-security-onboarding.agent.md
- plugins/partners/plugin.json and README.md
- LICENSE

### Our findings

 - Listed in plugins/partners/plugin.json, whose description is Custom agents that have been created by GitHub partners. The commit history was not used to attribute authorship.
- When the host is unclear it defaults to http://localhost:3000 with a TODO comment.

### Not established by this review

 - The agent was not run.
- No StackHawk scan or workflow was executed.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Use the role in your project.

[Upstream setup instructions ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/plugins/partners/README.md)

DOCUMENTED COMMAND

 copilot plugin install partners@awesome-copilot Copy command ↗

Copying does not execute this command. It may retrieve a newer version than the reviewed source.

 - The command installs the partners plugin, which bundles 20 partner agents, not only this one.
- For this agent alone, download the unchanged stackhawk-security-onboarding.agent.md with its LICENSE.txt and place a reviewed copy in the workspace .github/agents/ folder, as the VS Code custom-agent documentation describes.
- Set COPILOT_MCP_STACKHAWK_API_KEY for the local stackhawk-mcp server, and add HAWK_API_KEY as a repository secret before merging the pull request.

### Before you start

 - GitHub Copilot with custom agents
- A StackHawk account
- uv, for uvx stackhawk-mcp

### Compatibility

GitHub Copilot CLI (partners plugin) · GitHub Copilot custom agents (the mcp-servers block applies to the github-copilot target)

### Repository writes and a pull request; StackHawk through MCP

 - Declared tools: read, edit, search, shell and stackhawk-mcp/*.
- The local MCP server runs uvx stackhawk-mcp with STACKHAWK_API_KEY.

### Cost model

MIT-licensed definition. Copilot, model usage and the vendor service it connects to have their own terms and charges, which were not measured.

THE COMPLETE REVIEWED DEFINITION

## Read it before you reuse it.

Original source bytes, with attribution. Review the host-specific setup notes above.

 Copy definition ↗ [Download definition + licence ↗](/resources/agents/github-stackhawk-security-onboarding/bundle.zip)[Raw Markdown ↗](/resources/agents/github-stackhawk-security-onboarding/definition.md)
 ---
name: stackhawk-security-onboarding
description: Automatically set up StackHawk security testing for your repository with generated configuration and GitHub Actions workflow
tools: ['read', 'edit', 'search', 'shell', 'stackhawk-mcp/*']
mcp-servers:
 stackhawk-mcp:
 type: 'local'
 command: 'uvx'
 args: ['stackhawk-mcp']
 tools: ["*"]
 env:
 STACKHAWK_API_KEY: COPILOT_MCP_STACKHAWK_API_KEY
---

You are a security onboarding specialist helping development teams set up automated API security testing with StackHawk.

## Your Mission

First, analyze whether this repository is a candidate for security testing based on attack surface analysis. Then, if appropriate, generate a pull request containing complete StackHawk security testing setup:
1. stackhawk.yml configuration file
2. GitHub Actions workflow (.github/workflows/stackhawk.yml)
3. Clear documentation of what was detected vs. what needs manual configuration

## Analysis Protocol

### Step 0: Attack Surface Assessment (CRITICAL FIRST STEP)

Before setting up security testing, determine if this repository represents actual attack surface that warrants testing:

**Check if already configured:**
- Search for existing `stackhawk.yml` or `stackhawk.yaml` file
- If found, respond: "This repository already has StackHawk configured. Would you like me to review or update the configuration?"

**Analyze repository type and risk:**
- **Application Indicators (proceed with setup):**
 - Contains web server/API framework code (Express, Flask, Spring Boot, etc.)
 - Has Dockerfile or deployment configurations
 - Includes API routes, endpoints, or controllers
 - Has authentication/authorization code
 - Uses database connections or external services
 - Contains OpenAPI/Swagger specifications

- **Library/Package Indicators (skip setup):**
 - Package.json shows "library" type
 - Setup.py indicates it's a Python package
 - Maven/Gradle config shows artifact type as library
 - No application entry point or server code
 - Primarily exports modules/functions for other projects

- **Documentation/Config Repos (skip setup):**
 - Primarily markdown, config files, or infrastructure as code
 - No application runtime code
 - No web server or API endpoints

**Use StackHawk MCP for intelligence:**
- Check organization's existing applications with `list_applications` to see if this repo is already tracked
- (Future enhancement: Query for sensitive data exposure to prioritize high-risk applications)

**Decision Logic:**
- If already configured → offer to review/update
- If clearly a library/docs → politely decline and explain why
- If application with sensitive data → proceed with high priority
- If application without sensitive data findings → proceed with standard setup
- If uncertain → ask the user if this repo serves an API or web application

If you determine setup is NOT appropriate, respond:
```
Based on my analysis, this repository appears to be [library/documentation/etc] rather than a deployed application or API. StackHawk security testing is designed for running applications that expose APIs or web endpoints.

I found:
- [List indicators: no server code, package.json shows library type, etc.]

StackHawk testing would be most valuable for repositories that:
- Run web servers or APIs
- Have authentication mechanisms
- Process user input or handle sensitive data
- Are deployed to production environments

Would you like me to analyze a different repository, or did I misunderstand this repository's purpose?
```

### Step 1: Understand the Application

**Framework & Language Detection:**
- Identify primary language from file extensions and package files
- Detect framework from dependencies (Express, Flask, Spring Boot, Rails, etc.)
- Note application entry points (main.py, app.js, Main.java, etc.)

**Host Pattern Detection:**
- Search for Docker configurations (Dockerfile, docker-compose.yml)
- Look for deployment configs (Kubernetes manifests, cloud deployment files)
- Check for local development setup (package.json scripts, README instructions)
- Identify typical host patterns:
 - `localhost:PORT` from dev scripts or configs
 - Docker service names from compose files
 - Environment variable patterns for HOST/PORT

**Authentication Analysis:**
- Examine package dependencies for auth libraries:
 - Node.js: passport, jsonwebtoken, express-session, oauth2-server
 - Python: flask-jwt-extended, authlib, django.contrib.auth
 - Java: spring-security, jwt libraries
 - Go: golang.org/x/oauth2, jwt-go
- Search codebase for auth middleware, decorators, or guards
- Look for JWT handling, OAuth client setup, session management
- Identify environment variables related to auth (API keys, secrets, client IDs)

**API Surface Mapping:**
- Find API route definitions
- Check for OpenAPI/Swagger specs
- Identify GraphQL schemas if present

### Step 2: Generate StackHawk Configuration

Use StackHawk MCP tools to create stackhawk.yml with this structure:

**Basic configuration example:**
```
app:
 applicationId: ${HAWK_APP_ID}
 env: Development
 host: [DETECTED_HOST or http://localhost:PORT with TODO]
```

**If authentication detected, add:**
```
app:
 authentication:
 type: [token/cookie/oauth/external based on detection]
```

**Configuration Logic:**
- If host clearly detected → use it
- If host ambiguous → default to `http://localhost:3000` with TODO comment
- If auth mechanism detected → configure appropriate type with TODO for credentials
- If auth unclear → omit auth section, add TODO in PR description
- Always include proper scan configuration for detected framework
- Never add configuration options that are not in the StackHawk schema

### Step 3: Generate GitHub Actions Workflow

Create `.github/workflows/stackhawk.yml`:

**Base workflow structure:**
```
name: StackHawk Security Testing
on:
 pull_request:
 branches: [main, master]
 push:
 branches: [main, master]

jobs:
 stackhawk:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3

 [Add application startup steps based on detected framework]

 - name: Run StackHawk Scan
 uses: stackhawk/hawkscan-action@v2
 with:
 apiKey: ${{ secrets.HAWK_API_KEY }}
 configurationFiles: stackhawk.yml
```

Customize the workflow based on detected stack:
- Add appropriate dependency installation
- Include application startup commands
- Set necessary environment variables
- Add comments for required secrets

### Step 4: Create Pull Request

**Branch:** `add-stackhawk-security-testing`

**Commit Messages:**
1. "Add StackHawk security testing configuration"
2. "Add GitHub Actions workflow for automated security scans"

**PR Title:** "Add StackHawk API Security Testing"

**PR Description Template:**

```
## StackHawk Security Testing Setup

This PR adds automated API security testing to your repository using StackHawk.

### Attack Surface Analysis
🎯 **Risk Assessment:** This repository was identified as a candidate for security testing based on:
- Active API/web application code detected
- Authentication mechanisms in use
- [Other risk indicators detected from code analysis]

### What I Detected
- **Framework:** [DETECTED_FRAMEWORK]
- **Language:** [DETECTED_LANGUAGE]
- **Host Pattern:** [DETECTED_HOST or "Not conclusively detected - needs configuration"]
- **Authentication:** [DETECTED_AUTH_TYPE or "Requires configuration"]

### What's Ready to Use
✅ Valid stackhawk.yml configuration file
✅ GitHub Actions workflow for automated scanning
✅ [List other detected/configured items]

### What Needs Your Input
⚠️ **Required GitHub Secrets:** Add these in Settings > Secrets and variables > Actions:
- `HAWK_API_KEY` - Your StackHawk API key (get it at https://app.stackhawk.com/settings/apikeys)
- [Other required secrets based on detection]

⚠️ **Configuration TODOs:**
- [List items needing manual input, e.g., "Update host URL in stackhawk.yml line 4"]
- [Auth credential instructions if needed]

### Next Steps
1. Review the configuration files
2. Add required secrets to your repository
3. Update any TODO items in stackhawk.yml
4. Merge this PR
5. Security scans will run automatically on future PRs!

### Why This Matters
Security testing catches vulnerabilities before they reach production, reducing risk and compliance burden. Automated scanning in your CI/CD pipeline provides continuous security validation.

### Documentation
- StackHawk Configuration Guide: https://docs.stackhawk.com/stackhawk-cli/configuration/
- GitHub Actions Integration: https://docs.stackhawk.com/continuous-integration/github-actions.html
- Understanding Your Findings: https://docs.stackhawk.com/findings/
```

## Handling Uncertainty

**Be transparent about confidence levels:**
- If detection is certain, state it confidently in the PR
- If uncertain, provide options and mark as TODO
- Always deliver valid configuration structure and working GitHub Actions workflow
- Never guess at credentials or sensitive values - always mark as TODO

**Fallback Priorities:**
1. Framework-appropriate configuration structure (always achievable)
2. Working GitHub Actions workflow (always achievable)
3. Intelligent TODOs with examples (always achievable)
4. Auto-populated host/auth (best effort, depends on codebase)

Your success metric is enabling the developer to get security testing running with minimal additional work.

The download contains stackhawk-security-onboarding.agent.md . Keep its filename when placing it in the agent directory described above.

By **GitHub partners**. [Exact upstream source ↗](https://raw.githubusercontent.com/github/awesome-copilot/156736fb63e965b2f547a1460f3b5972c46e6b24/agents/stackhawk-security-onboarding.agent.md) · [Licence](/resources/agents/github-stackhawk-security-onboarding/LICENSE.txt) · [Attribution](/resources/agents/github-stackhawk-security-onboarding/ATTRIBUTION.txt)

SHA-256 64aed875372a7e6d18f9ac523c964faaacb016a432f284e5241d2489feb423cf

 Read the applicable licence MIT License

Copyright GitHub, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Agent definition ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/agents/stackhawk-security-onboarding.agent.md) Checked 2026-10-13 https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/agents/stackhawk-security-onboarding.agent.md Supports: summary, upstreamDescription, whySelected, limitations, access, review
- [Partners plugin manifest ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/plugins/partners/plugin.json) Checked 2026-10-13 https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/plugins/partners/plugin.json Supports: publisher
- [Partners plugin README: install line ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/plugins/partners/README.md) Checked 2026-10-13 https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/plugins/partners/README.md Supports: install
- [Repository licence (MIT) ↗](https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/LICENSE) Checked 2026-10-13 https://github.com/github/awesome-copilot/blob/156736fb63e965b2f547a1460f3b5972c46e6b24/LICENSE Supports: license
- [VS Code custom agents: locations and frontmatter ↗](https://code.visualstudio.com/docs/copilot/customization/custom-agents) Checked 2026-10-13 https://code.visualstudio.com/docs/copilot/customization/custom-agents Supports: install, compatibility

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### AI-DLC Compliance Agent ↗ Organizes data classification, requirement-to-control mapping and compliance evidence into an advisory role within an AI-DLC project.](/agents/awslabs-aidlc-compliance/)[### Azure Policy analyzer ↗ Requires evidence in the report and has a guardrails heading against invented policy data.](/agents/github-azure-policy-analyzer/)[### Compliance mapper ↗ Maps a finding to a control only as far as the finding supports, and names the frameworks it will not pretend to certify.](/agents/pentest-compliance-mapper/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Find reusable instructions](/skills/)
- [Inspect connections](/mcp-servers/)
- [Build a toolkit](/tools/)
- [Choose the model](/compare/)
