GitHub - stackhawk/stackhawk-mcp (original) (raw)

StackHawk MCP Server

Current Version: 1.2.1 Requires Python 3.10 or higher

A Model Context Protocol (MCP) server for integrating with StackHawk's security scanning platform. Provides security analytics, YAML configuration management, sensitive data/threat surface analysis, and anti-hallucination tools for LLMs.

Table of Contents

Features

Installation

  1. Install via pip (make sure you have write permission to your current python environment):

    pip install stackhawk-mcp

Requires Python 3.10 or higher

Or Install via pip in a virtual env:

python3 -m venv ~/.virtualenvs/mcp source ~/.virtualenvs/mcp/bin/activate (mcp) pip install stackhawk-mcp

Requires Python 3.10 or higher

Or Install via pip using pyenv:

pyenv shell 3.10.11 pip install stackhawk-mcp

Requires Python 3.10 or higher

Or Install locally from this repo:

pip install --user .

Run this command from the root of the cloned repository

  1. Set your StackHawk API key:

    export STACKHAWK_API_KEY="your-api-key-here"

Usage

Running the MCP Server

python -m stackhawk_mcp.server

Running the HTTP Server (FastAPI)

python -m stackhawk_mcp.http_server

Running Tests

Integrating with LLMs and IDEs

StackHawk MCP can be used as a tool provider for AI coding assistants and LLM-powered developer environments, enabling security analytics, YAML validation, and anti-hallucination features directly in your workflow.

Cursor (AI Coding Editor)

OpenAI, Anthropic, and Other LLMs

IDEs like Windsurf

General Tips

GitHub Copilot Agents

StackHawk can be added to the GitHub Coding Agent as an MCP server or as its own GitHub Custom Agent.

Add to GitHub Coding Agent

You can add StackHawk MCP to the GitHub Copilot Coding Agent. This gives the agent all the stackhawk/ tools.

StackHawk MCP installation into the Coding Agent

General instructions on GitHub

For StackHawk MCP, the MCP Configuration JSON should look something like this:

{ "mcpServers": { "stackhawk": { "type": "local", "tools": [ "*" ], "command": "uvx", "args": [ "stackhawk-mcp" ], "env": { "STACKHAWK_API_KEY": "COPILOT_MCP_STACKHAWK_API_KEY" } } } }

Then in the Repository's Settings->Environments->copilot->Environment Secrets, add COPILOT_MCP_STACKHAWK_API_KEY with your StackHawk API Key.

Installation verification instructions

StackHawk Onboarding Agent as a GitHub Copilot Custom Agent

You can the StackHawk Onboarding Agent as a custom agent at the enterprise, organization, or repository level in GitHub. When added, the StackHawk Onboarding Agent becomes a selectable option in the Copilot Agent Chat with context to help with onboarding, plus it installs stackhawk-mcp so the agent has access to all of those tools.

StackHawk Onboarding Agent installation

The general approach is to take the StackHawk Onboarding Agent defintion and apply it to either the desired repository, enterprise, or organization in GitHub.

Note that the mcp-servers block in the StackHawk Onboarding Agent definition references an environment variable called COPILOT_MCP_STACKHAWK_API_KEY. Go to the Repository's Settings->Environments->copilot->Environment Secrets, add COPILOT_MCP_STACKHAWK_API_KEY with your StackHawk API Key.

Configuration

User-Agent: StackHawk-MCP/{version}

Available Tools & API

Security Analytics

YAML Configuration Management

Sensitive Data & Threat Surface

Example Tool Usage

Get organization info

org_info = await server._get_organization_info(org_id="your-org-id")

Validate a YAML config

result = await server._validate_stackhawk_config(yaml_content="...")

Get application vulnerabilities

vulns = await server._get_application_vulnerabilities(app_id="your-app-id")

YAML & Anti-Hallucination

Official Schema URL: https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json

Sensitive Data & Threat Surface

Testing & Development

Running All Tests

Running Individual Tests

pytest tests/test_sensitive_data.py pytest tests/test_repository_analysis.py

Code Formatting

Type Checking

Example Configurations

Basic Configuration

app: applicationId: "12345678-1234-1234-1234-123456789012" env: "dev" host: "http://localhost:3000" name: "Development App" description: "Local development environment"

Production Configuration with Authentication

app: applicationId: "87654321-4321-4321-4321-210987654321" env: "prod" host: "https://myapp.com" name: "Production App" description: "Production environment" authentication: type: "form" username: "your-username" password: "your-password" loginUrl: "https://myapp.com/login" usernameField: "username" passwordField: "password"

hawk: spider: base: true ajax: false maxDurationMinutes: 30 scan: maxDurationMinutes: 60 threads: 10 startupTimeoutMinutes: 5 failureThreshold: "high"

tags:

Contributing

Contributions are welcome! Please open issues or pull requests for bug fixes, new features, or documentation improvements.

License

Apache License 2.0. See LICENSE for details.

Release and Version Bumping

Version bumps are managed via the "Prepare Release" GitHub Actions workflow. When triggering this workflow, you can select whether to bump the minor or major version. The workflow will automatically update version files, commit, and push the changes to main.

Note: The workflow is protected against infinite loops caused by automated version bump commits.

GitHub Actions Authentication

All CI/CD git operations use a GitHub App token for authentication. The git user and email are set from the repository secrets HAWKY_APP_USER and HAWKY_APP_USER_EMAIL.

Workflow Protections

Workflows are designed to skip jobs if the latest commit is an automated version bump, preventing workflow loops.

How to Trigger a Release

  1. Go to the "Actions" tab on GitHub.
  2. Select the "Prepare Release" workflow.
  3. Click "Run workflow" and choose the desired bump type (minor or major).
  4. The workflow will handle the rest!