StackHawk MCP Server

Current Version: 1.2.5

Requires Python 3.10 or higher

Сервер Model Context Protocol (MCP) для интеграции с платформой сканирования безопасности StackHawk. Помогает разработчикам настраивать StackHawk, запускать сканирования безопасности и проводить разбор находок для устранения уязвимостей — все это из IDE или чата, управляемых LLM.

Features
Installation
Usage
Configuration
Available Tools
Testing & Development
Example Configurations
Integrating with LLMs and IDEs
Contributing
License

Features

Setup: Определение вашего проекта, создание приложения StackHawk и генерация готового к сканированию stackhawk.yml
Scan: Запуск сканирований StackHawk напрямую из IDE или чата (помощь по установке, если CLI отсутствует)
Triage: Получайте конкретные находки на или выше вашего порога отказа для устранения проблем
Validate: Проверяйте YAML-конфиги в соответствии с официальной схемой и валидируйте пути к полям, чтобы предотвратить галлюцинации
Custom User-Agent: Все вызовы API включают версионированный заголовок User-Agent

Installation

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

pip install stackhawk-mcp

Requires Python 3.10 or higher">```

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">```
> 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">```

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">```
> pip install --user .
# Run this command from the root of the cloned repository

Set your StackHawk API key:

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

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

pytest


### Integrating with LLMs and IDEs

StackHawk MCP можно использовать в качестве поставщика инструментов для AI-редакторов кода и сред разработчиков, управляемых LLM, что позволяет настраивать сканирование безопасности, валидировать YAML и проводить разбор уязвимостей непосредственно в вашем рабочем процессе.

#### Cursor (AI Coding Editor)

- **Setup:**

Следуйте инструкциям установки выше, чтобы установить `stackhawk-mcp` в вашу Python-среду.

- В Cursor перейдите в Cursor Settings->Tools & Integrations->MCP Tools

- Добавьте "New MCP Server" со следующим json, в зависимости от вашей конфигурации:

Использование виртуального окружения по пути `~/.virtualenvs/mcp`:

{ "mcpServers": { "stackhawk": { "command": "/home/bobby/.virtualenvs/mcp/bin/python", "args": ["-m", "stackhawk_mcp.server"], "env": { "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}" }, "disabled": false } } }


- Использование pyenv:

{ "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 } } }


- Или использование Python напрямую:

{ "mcpServers": { "stackhawk": { "command": "python3", "args": ["-m", "stackhawk_mcp.server"], "env": { "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}" } } } }


- Затем убедитесь, что инструмент MCP "stackhawk" включен

- **Usage:**

Используйте вызов инструментов Cursor для вызова инструментов StackHawk MCP (например, поиск уязвимостей, валидация YAML).

- Пример запроса: `Validate this StackHawk YAML config for errors.`

#### OpenAI, Anthropic, and Other LLMs

- **Setup:**

Разверните MCP HTTP server и откройте доступ к вашей LLM-системе (локально или в облаке).

- Используйте API вызова инструментов или функцию-вызова вашей LLM для подключения к MCP-endpoint.

- Передавайте необходимые аргументы (например, org_id, yaml_content) в соответствии со схемами инструментов.

- **Example API Call:**

{ "method": "tools/call", "params": { "name": "validate_stackhawk_config", "arguments": {"yaml_content": "..."} } }


- **Best Practices:**

Используйте anti-hallucination инструменты для проверки соответствия имен полей и схемам.

- Всегда проверяйте вывод инструмента на наличие предупреждений или предложений.

#### IDEs like Windsurf

- **Setup:**

Добавьте StackHawk MCP в качестве поставщика инструментов или расширения в вашей IDE, указывая на локальный или удалённый MCP-сервер.

- Настройте переменные окружения по мере необходимости.

- **Usage:**

Вызывайте настройку, сканирование, валидацию и разбор инструментов напрямую из палитры команд IDE или панели интеграций инструментов.

#### General Tips

- Убедитесь, что MCP-сервер запущен и доступен из вашего LLM или IDE-среды.

- Ознакомьтесь с разделом [Available Tools & API](#available-tools--api) для поддерживаемых операций.

- Для продвинутой интеграции смотрите пример использования инструментов в этом README или изучайте кодовую базу для собственных рабочих процессов.

### GitHub Copilot Agents

StackHawk можно добавить в GitHub Coding Agent как MCP-сервер или как собственный GitHub Custom Agent.

#### Add to GitHub Coding Agent

Вы можете добавить StackHawk MCP в GitHub Copilot Coding Agent. Это даст агенту доступ ко всем инструментам `stackhawk/`.

**Установка StackHawk MCP в Coding Agent**

[Общие инструкции по GitHub](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#adding-an-mcp-configuration-to-your-repository)

Для StackHawk MCP конфигурационный JSON MCP должен выглядеть примерно так:

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


После этого в Settings->Environments->copilot->Environment Secrets репозитория добавьте COPILOT_MCP_STACKHAWK_API_KEY со своим StackHawk API Key.

[Installation verification instructions](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#validating-your-mcp-configuration)

#### StackHawk Onboarding Agent as a GitHub Copilot Custom Agent

Можно использовать StackHawk Onboarding Agent в качестве пользовательского агента на уровне enterprise, organization или репозитория в GitHub. При добавлении агент становится доступной опцией в Copilot Agent Chat с контекстом для упрощения onboarding, кроме того он устанавливает `stackhawk-mcp`, чтобы агент имел доступ ко всем этим инструментам.

**Установка StackHawk Onboarding Agent**

Общий подход — взять определение StackHawk Onboarding Agent и применить его к нужному репозиторию, enterprise или организации в GitHub.

- [Инструкция по установке в репозитории на GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents#creating-a-custom-agent-profile-for-a-repository)

- [Инструкция по установке в enterprise на GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents)

- [Инструкция по установке в организации GitHub](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents)

Обратите внимание, что блок `mcp-servers` в определении StackHawk Onboarding Agent ссылается на переменную окружения `COPILOT_MCP_STACKHAWK_API_KEY`. Перейдите в Repository's Settings->Environments->copilot->Environment Secrets и добавьте `COPILOT_MCP_STACKHAWK_API_KEY` со своим StackHawk API Key.

---

## Configuration

- All HTTP requests include a custom `User-Agent` header:

User-Agent: StackHawk-MCP/{version}


- The version is set in `stackhawk_mcp/server.py` as `STACKHAWK_MCP_VERSION`.

- Set your API key via the `STACKHAWK_API_KEY` environment variable.

---

## Available Tools

The MCP server exposes 7 tools organized around the developer workflow:

| Phase | Tool | Description |
| --- | --- | --- |
| Discover | get_organization_info | Получить детали организации, команды и приложения |
| Discover | list_applications | Перечислить приложения в организации |
| Setup | setup_stackhawk_for_project | Обнаружить язык, найти/создать приложение, сгенерировать stackhawk.yml |
| Validate | validate_stackhawk_config | Валидировать YAML в соответствии с официальной схемой |
| Validate | validate_field_exists | Проверять существование пути к полю в схеме (anti-hallucination) |
| Scan | run_stackhawk_scan | Запуск сканирования StackHawk через CLI (возвращает помощь по установке, если CLI отсутствует) |
| Triage | get_app_findings_for_triage | Получить находки для триажа на пороге ошибки |

### Example Tool Usage

Set up StackHawk for a project

result = await server.call_tool("setup_stackhawk_for_project", {"host": "http://localhost:3000"})

Validate a YAML config

result = await server.call_tool("validate_stackhawk_config", {"yaml_content": "..."})

Run a scan

result = await server.call_tool("run_stackhawk_scan", {})

Get findings to triage

result = await server.call_tool("get_app_findings_for_triage", {})


**Official Schema URL:** [https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json](https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json)

---

## Testing & Development

### Running All Tests

pytest


### Running Individual Tests

pytest tests/test_ux_improvements.py pytest tests/test_user_scenarios.py


### Code Formatting

black stackhawk_mcp/


### Type Checking

mypy stackhawk_mcp/


---

## 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:

name: "environment" value: "production"
name: "application" value: "myapp"


---

## 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](https://github.com/stackhawk/stackhawk-mcp/blob/main/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

- Go to the "Actions" tab on GitHub.

- Select the "Prepare Release" workflow.

- Click "Run workflow" and choose the desired bump type (minor or major).

- The workflow will handle the rest!

StackHawk MCP Server

Table of Contents

Features

Installation

Requires Python 3.10 or higher">```

Requires Python 3.10 or higher

Requires Python 3.10 or higher">```

Requires Python 3.10 or higher

Set up StackHawk for a project

Validate a YAML config

Run a scan

Get findings to triage