stackhawk

StackHawk MCP 服务

当前版本：1.2.5 需要 Python 3.10 或更高版本

用于与 StackHawk 安全扫描平台集成的模型上下文协议（MCP）服务。帮助开发者设置 StackHawk、运行安全扫描并分类处理发现的问题以修复漏洞——所有操作均可在由大模型驱动的 IDE 或聊天环境中完成。

---

目录

• 功能
• 安装
• 使用方法
• 配置
• 可用工具
• 测试与开发
• 配置示例
• 与大模型和 IDE 集成
• 贡献
• 许可证

---

功能

• **设置：**检测你的项目，创建 StackHawk 应用，并生成可直接用于扫描的 stackhawk.yml
• **扫描：**直接从 IDE 或聊天环境运行 StackHawk 扫描（如果缺少 CLI，还会提供安装帮助）
• **分类处理：**获取达到或超过失败阈值、可采取措施进行修复的问题
• **验证：**根据官方架构检查 YAML 配置，并验证字段路径以防止产生幻觉
• **自定义 User-Agent：**所有 API 调用均包含带版本号的 User-Agent 标头

---

安装

1. 通过 pip 安装（请确保你对当前 Python 环境有写入权限）：

   > pip install stackhawk-mcp
   # Requires Python 3.10 or higher
   

或在虚拟环境中通过 pip 安装：

> python3 -m venv ~/.virtualenvs/mcp
> source ~/.virtualenvs/mcp/bin/activate
> (mcp) pip install stackhawk-mcp
# Requires Python 3.10 or higher

或使用 pyenv 通过 pip 安装：

> pyenv shell 3.10.11
> pip install stackhawk-mcp
# Requires Python 3.10 or higher

或从此仓库本地安装：

> pip install --user .
# Run this command from the root of the cloned repository

2. 设置 StackHawk API 密钥：

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

---

使用方法

运行 MCP 服务

python -m stackhawk_mcp.server

运行 HTTP 服务（FastAPI）

python -m stackhawk_mcp.http_server

运行测试

pytest

与大模型和 IDE 集成

StackHawk MCP 可作为 AI 编码助手和大模型驱动的开发环境的工具提供方，让你能在工作流中直接设置安全扫描、验证 YAML 并分类处理漏洞。

Cursor（AI 编码编辑器）

• 设置：
  • 按照上方的安装说明，在你的 Python 环境中安装 stackhawk-mcp。
  • 在 Cursor 中，转到 Cursor Settings->Tools & Integrations->MCP Tools
  • 根据你的设置，使用以下 json 添加一个 "New MCP Server"：
    • 在 ~/.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}"
            }
          }
        }
      }
      

    • 然后确保已启用 "stackhawk" MCP 工具
• 使用方法：
  • 使用 Cursor 的工具调用功能调用 StackHawk MCP 工具（例如，搜索漏洞、验证 YAML）。
  • 提示词示例：Validate this StackHawk YAML config for errors.

OpenAI、Anthropic 和其他大模型

• 设置：
  • 部署 MCP HTTP 服务，并将其开放给你的大模型系统（本地或云端）。
  • 使用大模型的工具调用或函数调用 API 连接到 MCP 端点。
  • 按照工具架构中指定的内容传递所需参数（例如，org_id、yaml_content）。
• API 调用示例：

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

• 最佳实践：
  • 使用反幻觉工具验证字段名称和架构合规性。
  • 始终检查工具输出中是否包含警告或建议。

Windsurf 等 IDE

• 设置：
  • 在 IDE 中将 StackHawk MCP 添加为工具提供程序或扩展，并指向本地或远程 MCP 服务端点。
  • 根据需要配置环境变量。
• 用法：
  • 直接从 IDE 的命令面板或工具集成面板调用设置、扫描、验证和分诊工具。

通用提示

• 确保 MCP 服务正在运行，并且可从你的大模型或 IDE 环境访问。
• 查看可用工具和 API部分，了解支持的操作。
• 如需高级集成，请参阅本 README 中的工具用法示例，或探索代码库以了解自定义工作流。

GitHub Copilot Agents

StackHawk 可以作为 MCP 服务或独立的 GitHub 自定义 Agent 添加到 GitHub 编码 Agent 中。

添加到 GitHub 编码 Agent

你可以将 StackHawk MCP 添加到 GitHub Copilot 编码 Agent。这样 Agent 就能使用所有 stackhawk/ 工具。

将 StackHawk MCP 安装到编码 Agent 中

GitHub 上的常规说明

对于 StackHawk MCP，MCP 配置 JSON 应类似如下：

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

安装验证说明

将 StackHawk 入门 Agent 用作 GitHub Copilot 自定义 Agent

你可以在 GitHub 的企业、组织或仓库级别将 StackHawk 入门 Agent 用作自定义 Agent。添加后，StackHawk 入门 Agent 将成为 Copilot Agent Chat 中的可选项，提供入门指导所需的上下文，并安装 stackhawk-mcp，使 Agent 能够访问所有这些工具。

StackHawk 入门 Agent 安装

一般做法是获取 StackHawk 入门 Agent 定义，并将其应用到 GitHub 中所需的仓库、企业或组织。

• 在 GitHub 仓库中安装的说明
• 在 GitHub 企业中安装的说明
• 在 GitHub 组织中安装的说明

请注意，StackHawk 入门 Agent 定义中的 mcp-servers 块引用了名为 COPILOT_MCP_STACKHAWK_API_KEY 的环境变量。前往仓库的 Settings->Environments->copilot->Environment Secrets，添加 COPILOT_MCP_STACKHAWK_API_KEY，并填入你的 StackHawk API Key。

---

配置

• 所有 HTTP 请求都会包含自定义的 User-Agent 标头：

  User-Agent: StackHawk-MCP/{version}
  

• 版本在 stackhawk_mcp/server.py 中通过 STACKHAWK_MCP_VERSION 设置。
• 通过 STACKHAWK_API_KEY 环境变量设置 API 密钥。

---

可用工具

MCP 服务围绕开发工作流提供 7 个工具：

阶段	工具	描述
发现	get_organization_info	获取组织详情、团队和应用程序
发现	list_applications	列出组织中的应用程序
设置	setup_stackhawk_for_project	检测语言、查找或创建应用，并生成 stackhawk.yml
验证	validate_stackhawk_config	根据官方 StackHawk 架构验证 YAML
验证	validate_field_exists	检查字段路径是否在架构中有效（防止幻觉）
扫描	run_stackhawk_scan	通过 CLI 运行 StackHawk 扫描（如果缺少 CLI，则返回安装帮助）
分类	get_app_findings_for_triage	获取达到或超过已配置失败阈值的问题

工具用法示例

# 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", {})

官方架构 URL： https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json

---

测试与开发

运行所有测试

pytest

运行单项测试

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

代码格式化

black stackhawk_mcp/

类型检查

mypy stackhawk_mcp/

---

配置示例

基本配置

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

带身份验证的生产环境配置

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"

---

贡献

欢迎贡献！请提交问题或拉取请求，以修复错误、添加新功能或改进文档。

---

许可证

Apache License 2.0。详情请参阅 LICENSE。

发布与版本升级

版本升级通过“Prepare Release”GitHub Actions 工作流管理。 触发此工作流时，可以选择升级次版本号或主版本号。 工作流会自动更新版本文件、提交更改并将更改推送到 main。

注意： 该工作流已采取防护措施，以避免自动版本升级提交导致无限循环。

GitHub Actions 身份验证

所有 CI/CD git 操作都使用 GitHub App 令牌进行身份验证。 git 用户名和邮箱取自仓库机密 HAWKY_APP_USER 和 HAWKY_APP_USER_EMAIL。

工作流防护

如果最新提交是自动版本升级，工作流会跳过作业，以防止工作流循环。

如何触发发布

1. 前往 GitHub 上的“Actions”选项卡。
2. 选择“Prepare Release”工作流。
3. 点击“Run workflow”，然后选择所需的升级类型（次版本号或主版本号）。
4. 工作流会处理其余事项！