com.stackhawk/stackhawk

Install

Config snippet generator goes here (5 client tabs)

README

# StackHawk MCP Server

**Current Version: 1.2.4**
_Requires Python 3.10 or higher_

A Model Context Protocol (MCP) server for integrating with StackHawk's security scanning platform. Helps developers set up StackHawk, run security scans, and triage findings to fix vulnerabilities — all from within an LLM-powered IDE or chat.

---

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Available Tools](#available-tools)
- [Testing & Development](#testing--development)
- [Example Configurations](#example-configurations)
- [Integrating with LLMs and IDEs](#integrating-with-llms-and-ides)
- [Contributing](#contributing)
- [License](#license)

---

## Features
- **Setup:** Detect your project, create a StackHawk application, and generate a ready-to-scan `stackhawk.yml`
- **Scan:** Run StackHawk scans directly from your IDE or chat (with install help if the CLI is missing)
- **Triage:** Get actionable findings at or above your failure threshold for remediation
- **Validate:** Check YAML configs against the official schema and validate field paths to prevent hallucination
- **Custom User-Agent:** All API calls include a versioned `User-Agent` header

---

## Installation

1. **Install via pip (make sure you have write permission to your current python environment):**
   ```bash
   > pip install stackhawk-mcp
   # Requires Python 3.10 or higher
   ```
**Or Install via pip in a virtual env:**
   ```bash
   > 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:**
   ```bash
   > pyenv shell 3.10.11
   > pip install stackhawk-mcp
   # Requires Python 3.10 or higher
   ```   
**Or Install locally from this repo:**
   ```bash
   > pip install --user .
   # Run this command from the root of the cloned repository
   ```
2. **Set your StackHawk API key:**
   ```bash
   > export STACKHAWK_API_KEY="your-api-key-here"
   ```

---

## Usage

### Running the MCP Server
```bash
python -m stackhawk_mcp.server
```

### Running the HTTP Server (FastAPI)
```bash
python -m stackhawk_mcp.http_server
```

### Running Tests
```bash
pytest
```

### 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 scanning setup, YAML validation, and vulnerability triage directly in your workflow.

#### Cursor (AI Coding Editor)
- **Setup:**
  - Follow the installation instructions above to install `stackhawk-mcp` in your python environment.
  - In Cursor, go to `Cursor Settings->Tools & Integrations->MCP Tools`
  - Add a "New MCP Server" with the following json, depending on your setup:
    - Using a virtual env at `~/.virtualenvs/mcp`:
      ```json
      {
        "mcpServers": {
          "stackhawk": {
            "command": "/home/bobby/.virtualenvs/mcp/bin/python",
            "args": ["-m", "stackhawk_mcp.server"],
            "env": {
              "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}"
            },
            "disabled": false
          }
        }
      }
      ```
    - Using pyenv:
      ```json
      {
        "mcpServers": {
          "stackhawk": {
            "command": "/home/bobby/.pyenv/versions/3.10.11/bin/python3",
            "args": ["-m", "stackhawk_mcp.server"],
            "env": {
              "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}"
            },
            "disabled": false
          }
        }
      }
      ```
    - Or use python directly:
      ```json
      {
        "mcpServers": {
          "stackhawk": {
            "command": "python3",
            "args": ["-m", "stackhawk_mcp.server"],
            "env": {
              "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}"
            }
          }
        }
      }
      ```
    - Then make sure the "stackhawk" MCP Tool is enabled
- **Usage:**
  - Use Cursor's tool invocation to call StackHawk MCP tools (e.g., vulnerability search, YAML validation).
  - Example prompt: `Validate this StackHawk YAML config for errors.`

#### OpenAI, Anthropic, and Other LLMs
- **Setup:**
  - Deploy the MCP HTTP server and expose it to your LLM system (local or cloud).
  - Use the LLM's tool-calling or function-calling API to connect to the MCP endpoint.
  - Pass the required arguments (e.g., org_id, yaml_content) as specified in the tool schemas.
- **Example API Call:**
  ```json
  {
    "method": "tools/call",
    "params": {
      "name": "validate_stackhawk_config",
      "arguments": {"yaml_content": "..."}
    }
  }
  ```
- **Best Practices:**
  - Use anti-hallucination tools to validate field names and schema compliance.
  - Always check the tool's output for warnings or suggestions.

#### IDEs like Windsurf
- **Setup:**
  - Add StackHawk MCP as a tool provider or extension in your IDE, pointing to the local or remote MCP server endpoint