技术文档摘要

sec-mcp: 安全检查工具包

一个用于域名、URL、IP地址等安全检查的Python工具包。可以轻松集成到任何Python应用程序中，通过终端命令行使用，或作为MCP服务器运行以实时丰富LLM上下文中的威胁洞察。

由专注于网络安全和网络监控解决方案的公司Montimage开发。

<p align="left"> <a href="https://pepy.tech/projects/sec-mcp"><img src="https://static.pepy.tech/badge/sec-mcp" alt="PyPI 下载量"></a> <a href="https://pypi.org/project/sec-mcp/"><img src="https://img.shields.io/pypi/v/sec-mcp.svg?label=PyPI&color=blue" alt="PyPI"></a> <a href="https://pypi.org/project/sec-mcp/"><img src="https://img.shields.io/pypi/pyversions/sec-mcp.svg?label=Python&color=informational" alt="Python 版本"></a> <a href="https/opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT 许可证"></a> </p>

---

目录

• 功能
• 安装
• 快速开始
• 用法
  • CLI 使用
  • Python API
  • MCP 服务器
• 性能优化
• 基准测试
• 配置
• 开发
• 许可证

---

功能

• 全面的安全检查：针对多个黑名单源验证域名、URL和IP地址
• 多种威胁来源：OpenPhish、PhishTank、PhishStats、URLhaus、BlocklistDE、CINSSCORE等
• 高性能：超快的内存存储，比仅数据库方法快1000-20,000倍
• 智能优化：分层查找、URL规范化和IPv4整数存储以实现最大效率
• 灵活集成：作为Python库、CLI工具或MCP服务器用于LLM集成
• 线程安全：SQLite存储采用WAL模式和内存缓存支持并发操作
• 自动更新：每天从威胁情报源进行计划更新
• 丰富的监控：内置指标、健康检查和性能跟踪

---

安装

pip install sec-mcp

要求

• Python 3.8+
• SQLite 3
• 可选：pytricia 和 psutil 用于基准测试

---

快速开始

1. 创建虚拟环境（推荐）：

   python3 -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate.bat
   

2. 安装 sec-mcp：

   pip install sec-mcp
   

3. 初始化并更新数据库：

   sec-mcp update
   

4. 检查状态：

   sec-mcp status
   

5. 检查一个URL：

   sec-mcp check https://example.com
   

---

用法

CLI 使用

单个检查

sec-mcp check https://example.com
sec-mcp check malicious-domain.com
sec-mcp check 192.168.1.1

批量检查

# 从文件（每行一个URL/域名/IP）
sec-mcp batch urls.txt

# 输出到文件
sec-mcp batch urls.txt --output results.json

状态和更新

# 检查黑名单状态
sec-mcp status

# 更新黑名单
sec-mcp update

# 获取详细统计信息
sec-mcp stats

Python API

from sec_mcp import SecMCP

# 初始化客户端
client = SecMCP()

# 更新数据库（安装后运行一次）
client.update()

# 单个检查
result = client.check("https://example.com")
print(f"安全: {result.is_safe}")
print(f"来源: {result.source}")

# 批量检查
urls = ["https://example.com", "https://test.com", "192.168.1.1"]
results = client.check_batch(urls)
for r in results:
    print(f"{r.value}: {'安全' if r.is_safe else '阻止'}")

# 获取状态
status = client.get_status()
print(f"总条目数: {status.total_entries}")
print(f"上次更新时间: {status.last_update}")

MCP 服务器

sec-mcp 可以作为MCP服务器运行以集成AI/LLM（例如Claude、Windsurf、Cursor）。

设置

1. 在虚拟环境中安装 sec-mcp（参见快速开始）

2. 更新黑名单：

   sec-mcp update
   

3. 配置您的MCP客户端（例如claude_desktop_config.json）：

   {
     "mcpServers": {
       "sec-mcp": {
         "command": "/绝对路径/to/.venv/bin/python",
         "args": ["-m", "sec_mcp.start_server"],
         "env": {
           "MCP_USE_V2_STORAGE": "true"
         }
       }
     }
   }
   

   重要：使用虚拟环境Python可执行文件的绝对路径。

   • macOS/Linux: /path/to/.venv/bin/python
   • Windows: C:\path\to\.venv\Scripts\python.exe

可用的MCP工具

工具名称	描述
check_batch	一次性检查多个域名/URL/IP
get_status	获取黑名单状态，包括条目数量和按来源细分的信息
update_blacklists	强制立即更新所有黑名单
get_diagnostics	获取诊断信息，模式有：摘要、全部、健康、性能、样本
add_entry	手动添加黑名单条目
remove_entry	根据URL或IP地址删除黑名单条目

注意：这些工具经过优化以减少令牌使用同时保持全部功能。get_diagnostics工具整合了多种监控功能，并提供了不同的模式。

诊断工具模式

get_diagnostics工具提供了以下模式的灵活监控：

• 摘要（默认）：条目数量、来源和最后更新时间
• 全部：完整的诊断数据，包括健康状况、统计数据和性能
• 健康：仅数据库和调度器健康状况
• 性能：性能指标和命中率（仅适用于v2存储）
• 样本：随机抽取黑名单条目（使用sample_count参数）

示例用法：

# 获取基本摘要
await get_diagnostics()

# 检查系统健康状况
await get_diagnostics(mode="健康")

# 获取性能指标
await get_diagnostics(mode="性能")

# 抽取20个条目
await get_diagnostics(mode="样本", sample_count=20)

---

🚀 性能优化

高性能模式（v0.3.0+）

启用超快的内存存储以获得显著的性能提升：

export MCP_USE_V2_STORAGE=true

性能对比

操作	v1（数据库）	v0.3.0（混合）	v0.4.0（优化）	与v1相比加速倍数
域名检查	10ms	0.01ms	0.006ms	1,600x
URL检查	5ms	0.001ms	0.0007ms	7,000x
IP + CIDR检查	200ms	0.01ms	0.007ms	28,000x
批量100项	2-3秒	50-100毫秒	50-100毫秒	30x

内存使用

• v1（默认）：约10MB（磁盘上的数据库）
• v0.3.0（v2）：约60-80MB（内存中125K条目）
• v0.4.0（v2优化）：约40-50MB（内存中450K条目） - 节省30-40%！

v0.4.0 优化

1. 分层查找（热/冷源）：

   • 先检查频繁命中的源以提前退出
   • 70-90%的查找命中热源
   • 基于生产数据分析

2. URL规范化：

   • 自动捕获变体：HTTP://EVIL.COM/ → http://evil.com
   • 移除跟踪参数：?utm_source=spam，?fbclid=123
   • 减少15-25%的内存使用

3. 整数IPv4存储：

   • 每个IP占用4字节（字符串形式需要13+字节）
   • 比较速度快5-10%
   • 节省约1-2MB内存

监控性能

# 通过MCP工具或Python API
metrics = client.get_storage_metrics()

# 返回：
{
  "总查找次数": 1234,
  "域名查找次数": 567,
  "URL查找次数": 432,
  "IP查找次数": 235,
  "平均查找时间（毫秒）": "0.0123",
  "内存使用（MB）": "45.3",
  "命中率": 0.89,
  "使用pytricia": true
}

回滚至v1

unset MCP_USE_V2_STORAGE
# 或
export MCP_USE_V2_STORAGE=false

---

基准测试

运行基准测试

比较不同存储实现的性能：

# 安装依赖
pip install pytricia psutil

# 快速基准测试（10K条目，约30秒）
./run_benchmark.sh --quick

# 标准基准测试（50K条目，约2分钟）
./run_benchmark.sh

# 完整基准测试（100K条目，约5分钟）
./run_benchmark.sh --full --memory

# 比较特定版本
./run_benchmark.sh --v1 --v2opt    # 比较v1 vs v0.4.0
./run_benchmark.sh --all           # 比较所有版本

基准测试选项

标志	描述
--quick	快速基准测试，10K条目（500次迭代）
--full	完整基准测试，100K条目（1000次迭代）
--all	比较所有版本（v1、v0.3.0、v0.4.0）
--v1	基准测试v1（仅数据库存储）
--v2	基准测试v0.3.0（混合存储）
--v2opt	基准测试v0.4.0（优化的混合存储）
--memory	包括内存分析（需要psutil）

示例输出

基准测试结果比较
================================================================================
操作                 v1（数据库）         v0.3.0（混合）      v0.4.0（优化）   加速倍数
----------------------------------------------------------------------------------------------------
域名查找             9.8234毫秒        0.0098毫秒             0.0059毫秒             1,664x
URL查找              4.5632毫秒        0.0009毫秒             0.0007毫秒             6,519x
IP查找               198.2341毫秒      0.0103毫秒             0.0071毫秒             27,920x
批量100项            2453.21毫秒       87.45毫秒              72.31毫秒              33.9x

v0.4.0 优化指标
================================================================================
域名查找             热源命中率：100.0%
URL查找              热源命中率：98.9%
IP查找               热源命中率：88.9%

详细的基准测试说明和方法，请参阅BENCHMARK_PLAYBOOK.md。

---

配置

环境变量

变量	描述	默认值
MCP_DB_PATH	自定义数据库位置	平台特定（见下文）
MCP_USE_V2_STORAGE	启用高性能模式	false

默认数据库位置

• macOS：~/Library/Application Support/sec-mcp/mcp.db
• Linux：~/.local/share/sec-mcp/mcp.db
• Windows：%APPDATA%\sec-mcp\mcp.db

自定义数据库路径

export MCP_DB_PATH=/path/to/custom/location/mcp.db

配置文件

编辑config.json来自定义：

{
  "blacklist_sources": {
    "PhishTank": "https://...",
    "URLhaus": "https://..."
  },
  "update_time": "00:00",
  "cache_size": 10000,
  "log_level": "INFO"
}

---

开发

设置开发环境

# 克隆仓库
git clone https://github.com/montimage/sec-mcp.git
cd sec-mcp

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 以开发模式安装
pip install -e .

# 安装开发依赖
pip install pytricia psutil pytest

运行测试

# 运行所有测试
pytest

# 运行带有覆盖率报告
pytest --cov=sec_mcp --cov-report=html

项目结构

sec-mcp/
├── sec_mcp/              # 主要包
│   ├── __init__.py
│   ├── storage.py        # v1存储（仅数据库）
│   ├── storage_v2.py     # v2存储（混合内存）
│   ├── start_server.py   # MCP服务器
│   └── cli.py           # CLI接口
├── benchmark.py          # 基准测试脚本
├── run_benchmark.sh      # 基准测试辅助脚本
├── dev-docs/            # 开发文档（git忽略）
├── tests/               # 测试套件
└── README.md            # 本文档

---

许可证

MIT 许可证 - 详情请参阅LICENSE文件。

---

关于 Montimage

sec-mcp 由专注于网络安全和网络监控解决方案的公司Montimage开发和维护。Montimage 提供创新的安全工具和服务，帮助组织保护其数字资产并确保网络的安全性。

支持

• 问题：GitHub Issues
• 邮件：contact@montimage.eu
• 网站：https://www.montimage.eu

---

贡献

欢迎贡献！请随时提交Pull Request。

1. 分叉仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加一些惊人的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开Pull Request

---

致谢

• 威胁情报来源：OpenPhish、PhishTank、PhishStats、URLhaus、BlocklistDE、CINSSCORE等
• 使用模型上下文协议（MCP）构建
• 由Python和SQLite驱动