Debian漏洞分析工具包

[！警告] 此包已重命名为 debvulns. debsecan-mcp 0.1.5 是以该名称发布的最终版本。请更新您的依赖关系：

复制

pip install debvulns

德瓦伦

Debian漏洞分析工具包——MCP服务器、独立CLI和Prometheus导出器。 与人工智能助手（如Claude）和监控堆栈（Prometheus+Grafana）集成，以 跟踪、优先处理和提醒Debian系统中的软件包漏洞。

[！注意] 该项目之前在PyPI上发布为 debsecan-mcp.最后的释放 这个名字是 0.1.5所有未来的发展都发生在这里 debvulns.

特征

• MCP服务器 (debvulns-mcp)：与Claude Desktop、VSCode和opencode集成 人工智能辅助漏洞分析
• 独立CLI (debvulns)：从中的命令行扫描并报告漏洞 JSON或CSV格式
• 普罗米修斯出口商 (debvulns-exporter)：暴露Grafana的漏洞指标 仪表板和警报
• 列出漏洞：扫描所有已安装的软件包以查找已知漏洞
• CVE研究：获取有关特定CVE的详细信息，包括EPSS分数
• 自动套房检测：自动检测您的Debian套件 （书虫、特里克斯、希德等）
• EPSS集成：通过漏洞利用预测丰富漏洞数据 评分系统（EPSS）评分

安装

pip install debvulns

或来源：

pip install -e .

用法

独立CLI工具(debvulns)

该软件包包括一个独立的CLI工具 debvulns 它允许您扫描 在不运行MCP服务器的情况下，直接从命令行访问漏洞。

在第一次运行时， debvulns 下载漏洞和EPSS数据并在本地缓存 （违约 /var/cache/debvulns 或倒退到 ~/.cache/debvulns 如果默认 路径无法写入）。如果缓存超过24小时，则会自动刷新缓存。

运行CLI工具

debvulns

命令行选项

debvulns --help

选项：

• -s, --severity {critical,high,medium,low,negligible} -按严重程度过滤漏洞。 默认情况下，按严重程度列出所有漏洞。
• -f, --format {json,csv} -输出格式（默认值： json).
• --sort-by {package,cve} -按包名或CVE ID对漏洞进行排序。
• --suite SUITE -Debian套件名称（例如。， bookworm, sid).由自动检测 违约。
• --cache-dir PATH -用于缓存提取和解析数据的目录 （默认值： /var/cache/debvulns).
• --no-cache -不要使用缓存数据，强制下载和解析。
• --vuln-url URL -Debian安全跟踪器数据的自定义URL或本地路径。
• --epss-url URL -EPSS分数数据的自定义URL或本地路径。
• -v, --verbose -启用详细调试日志记录（发送到stderr）。

例子

过滤高严重性漏洞，按CVE排序，并以CSV格式输出：

debvulns --severity high --sort-by cve --format csv

在不使用缓存数据的情况下运行特定套件：

debvulns --suite trixie --no-cache

普罗米修斯出口商(debvulns-exporter)

debvulns-exporter 是一个长时间运行的HTTP服务器，在 普罗米修斯展览格式. 它运行周期性的背景扫描，并在上提供最新结果 /metrics 没有 堵住刮痕。

运行导出程序

debvulns-exporter

这将在默认端口上启动导出器 9222 并开始一个初始漏洞 扫描。这 /metrics 端点返回 503 直到第一次扫描完成。

命令行选项

debvulns-exporter --help

选项：

• --port PORT -要暴露的TCP端口 /metrics on（默认值： 9222).
• --suite SUITE -Debian套件代号（例如。 bookworm, sid).默认情况下自动检测。
• --refresh-interval SECS -完整漏洞扫描之间的秒数 （默认值： 86400 =24小时，最小值： 3600 =1小时）。
• --cache-dir DIR -下载数据热启动磁盘缓存目录 （默认值： /var/cache/debvulns-exporter).
• --no-cache -禁用磁盘缓存；每次刷新时都要重新下载。
• --vuln-url URL -覆盖Debian安全跟踪器漏洞数据URL。
• --epss-url URL -覆盖EPSS CSV数据URL。
• -v, --verbose -启用stderr的调试级日志记录。

健康终点

暴露的指标

作为系统服务运行

现成的systemd单元文件提供在 contrib/systemd/debvulns-exporter.service.

设置步骤：

1. 创建专用系统用户：

   复制

   sudo useradd --system --no-create-home --shell /usr/sbin/nologin debvulns
   

2. 安装systemd单元：

   复制

   sudo cp contrib/systemd/debvulns-exporter.service /etc/systemd/system/
   sudo systemctl daemon-reload
   

3. 启用并启动服务：

   复制

   sudo systemctl enable --now debvulns-exporter
   

4. 检查服务状态和日志：

   复制

   sudo systemctl status debvulns-exporter
   sudo journalctl -u debvulns-exporter -f
   

该装置运行方式为 debvulns 用户，应用安全强化 (ProtectSystem=strict, ProtectHome=true, NoNewPrivileges=true)，并写入其磁盘 缓存到 /var/cache/debvulns-exporter.

[！注意] 因为 ProtectHome=true 如果已设置，Python运行时和虚拟环境必须为 安装在外面 /home （例如通过 pip install debvulns 系统范围内，或通过设置 UV_PYTHON_INSTALL_DIR=/opt/app/python 使用时 uv).

Grafana仪表板

预构建的Grafana仪表板JSON提供于 contrib/grafana/debvulns-dashboard.json.

要导入它，请执行以下操作：

1. 在Grafana，前往 仪表盘→ 导入.
2. 上传 contrib/grafana/debvulns-dashboard.json 或粘贴其内容物。
3. 选择您的Prometheus数据源并单击 导入.

仪表板包括以下面板：

• 按严重程度列出的漏洞总数
• 扫描健康状况和上次扫描时间戳
• 每包漏洞细分
• EPSS评分分布

MCP服务器(debvulns-mcp)

运行MCP服务器

debvulns-mcp

或者使用特定的Debian套件：

DEBSECAN_SUITE=bookworm debvulns-mcp

命令行选项

debvulns-mcp --help

选项：

• --transport {stdio,sse,streamable-http} -传输模式（默认：stdio）
• --mount-path PATH -HTTP传输的装载路径（默认值：/mcp）
• --host HOST -用于HTTP传输的绑定主机（默认值：0.0.0.0）
• --port PORT -用于HTTP传输的绑定端口（默认值：8000）

运输方式

STDIO模式（默认）

用于与Claude Desktop或VSCode等人工智能助手直接集成。

debvulns-mcp --transport stdio

HTTP模式

对于基于HTTP的访问，请使用 sse 或 streamable-http:

# SSE mode
debvulns-mcp --transport sse --port 8080 --mount-path /mcp

# Streamable HTTP mode
debvulns-mcp --transport streamable-http --port 8080 --mount-path /mcp

注意：HTTP模式需要在web服务器后面运行。看 HTTP服务器设置 在......下面

HTTP服务器设置

HTTP传输模式需要由WSGI/ASGI服务器提供服务。uvicorn示例：

# Install uvicorn
pip install uvicorn

# Run with stdio transport and wrap with uvicorn
uvicorn debvulns.main:mcp_app --app-dir src --host 0.0.0.0 --port 8000 --path /mcp

或者使用内置的开发服务器：

# SSE mode
debvulns-mcp --transport sse --host 0.0.0.0 --port 8000 --mount-path /mcp

可用的MCP工具

list_vulnerabilities

列出影响当前安装的软件包的所有漏洞 系统。按严重程度对其进行分类（严重、高、中、低、可忽略不计） 以及EPSS评分。

research_cves

提供CVE ID列表的详细信息，包括：

• 包名
• 紧急程度
• EPSS评分和百分位数
• 是否有可用的修复程序
• 远程利用
• 描述

添加到VSCode

要将此MCP服务器与VSCode和AI助手一起使用：

1. 打开VSCode设置（JSON）：

   • 在macOS上： Cmd + Shift + P → “首选项：打开设置（JSON）”
   • 在Linux/Windows上： Ctrl + Shift + P → “首选项：打开设置（JSON）”

2. 添加MCP服务器配置：

{
  "mcpServers": {
    "debvulns": {
      "command": "debvulns-mcp",
      "args": [],
      "env": {
        "DEBSECAN_SUITE": "bookworm"
      }
    }
  }
}

3. 替换 bookworm 使用您的Debian套件代号（例如。， trixie, sid, GENERIC)

4. 重新启动VSCode或重新加载窗口

添加到opencode

选项1:STDIO模式（默认）

对于opencode的本地使用，请使用默认的stdio传输：

{
  "mcpServers": {
    "debvulns": {
      "command": "debvulns-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "DEBSECAN_SUITE": "bookworm"
      }
    }
  }
}

选项2:HTTP模式

对于远程或容器化设置，您可以通过HTTP运行MCP服务器：

1. 启动服务器：

debvulns-mcp --transport streamable-http --port 8080 --mount-path /mcp

2. 配置opencode以通过HTTP连接：

{
  "mcpServers": {
    "debvulns": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

注意：HTTP模式要求MCP客户端支持HTTP传输。

运作原理

1. 包发现：用途 python-apt 枚举系统上所有已安装的软件包
2. 漏洞数据：从中获取压缩的漏洞数据 Debian安全跟踪器
3. EPSS富集：从下载EPSS分数 CISA 优先考虑漏洞
4. 分析：使用APT版本比较将安装的软件包版本与漏洞数据进行比较

需求

• Python 3.11+
• 基于Debian的发行版（Debian、Ubuntu等）
• 网络访问以下载漏洞数据

[！注意] python3-apt （the apt_pkg C扩展）是 可选但推荐当存在时， debvulns 使用APT缓存枚举已安装的包，从而正确解析 二进制到源代码包映射，并使用本地APT版本比较算法。

没有 python3-apt，工具将回退到 dpkg-query。这涵盖了大多数情况，但 可能会错过在与二进制文件不同的源包名称下跟踪的漏洞 包名称，导致结果不完整。

安装时使用：

复制

sudo apt install python3-apt

在虚拟环境中使用：

python3-apt 是绑定到系统Python的已编译C扩展，无法安装 通过 pip在venv内部，你有两个选择：

选项1——继承系统站点包（最简单）：

复制

python3 -m venv --system-site-packages .venv

这使venv可以访问已安装的系统 apt_pkg 模块。

选项2——从上游git存储库安装： 首先安装所需的构建依赖项，然后直接通过pip安装：

复制

sudo apt install build-essential libapt-pkg-dev python3-dev
pip install git+https://salsa.debian.org/apt-team/python-apt.git