sec-mcp: Security Checking Toolkit

sec-mcp

将域名、URL 和 IP 地址与实时安全黑名单进行比对——可作为 Python 库、终端 CLI，或为 LLM Agent 提供实时威胁上下文的 MCP 服务使用。

sec-mcp 将十个公开威胁情报源汇总到本地 SQLite 数据库中，并在微秒级时间内回答“这个域名/URL/IP 是否具有恶意？”你可以在任何 Python 应用中使用它，通过终端运行 sec-mcp，或将其用作 Model Context Protocol 服务，让 Claude Desktop、Cursor 和 Windsurf 等工具根据真实黑名单数据筛查指标。

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

---

目录

• 功能
• 演示
• 快速开始
• 安装
• 用法
  • CLI
  • Python API
  • MCP 服务
• 性能优化
• 基准测试
• 配置
• 项目结构
• 文档
• 贡献
• 相关出版物
• 许可证
• 致谢

---

功能

• 全面的安全检查 — 验证域名、URL 和 IPv4/IPv6 地址，采用域名→URL 级联语义（列入黑名单的域名会使其 URL 和子域名也被判定为黑名单；列入黑名单的 URL 不会使其域名也被判定为黑名单），并对 IP 进行 CIDR 范围匹配
• 十个威胁情报源 — OpenPhish、PhishStats、URLhaus、PhishTank、Spamhaus DROP、Dshield、CINSSCORE、EmergingThreats、FeodoTracker 和 BlocklistDE
• 三个接口，一个引擎 — Python API（SecMCP）、Click CLI（sec-mcp）和 MCP 服务（sec-mcp-server，支持 stdio 或 streamable HTTP），提供六个带类型的工具
• 两种存储后端 — 默认使用 SQLite 存储（v1），或使用内存混合存储（v2，MCP_USE_V2_STORAGE=true），并按类型建立 O(1) 索引；在随附的基准测试中，查找速度最高比仅使用数据库的路径快约 28,000 倍
• URL 规范化 — 两种后端共用一个规范化器：统一小写、处理默认 scheme 并剥离跟踪参数（utm_*、fbclid 等），使 URL 的不同变体共享同一判定结果
• 安全的情报源摄取 — 仅通过 HTTPS 下载，并受 max_feed_bytes 和条目数合理性检查限制；一个情报源失败不会中止其他情报源
• 每日定时更新 — schedule 作业会在 update_time 刷新情报源；强制更新受频率限制，间隔至少为 min_update_interval_seconds（默认 300 s）
• 并发友好 — SQLite 使用 WAL 模式和 synchronous=NORMAL，每次检查使用线程本地共享连接，v2 后端支持无锁快照读取
• 结构化 MCP 输出 — 每个工具都会发布带类型的 outputSchema，结果包含 structuredContent，check_batch 会报告三态判定结果（safe / blacklisted / invalid），域名失败会以 isError 结果呈现，而不会导致协议崩溃
• 可观测 — get_diagnostics MCP 工具支持 summary / full / health / performance / sample 模式，提供真实的 scheduler_alive 状态报告和每个来源的条目计数

---

演示

占位内容 — 发布前需要维护者提供意见。 当前仓库没有附带截图或演示素材。建议：录制一段 asciinema 视频，演示 sec-mcp update → sec-mcp check <url>，或截取 Claude Desktop 中六个 MCP 工具的画面。将文件添加到 docs/assets/ 下（例如 docs/assets/demo.gif），并将此区块替换为 ![sec-mcp 演示](docs/assets/demo.gif)。

---

快速开始

不到五分钟，从零开始获取判定结果：

pip install sec-mcp
sec-mcp update                        # download + index the feeds (first run only)
sec-mcp check https://example.com     # → Status: Safe / Blacklisted
sec-mcp status                        # entry counts + per-source breakdown

若要将其作为 MCP 服务运行，请跳转到 MCP 服务 — 除 uvx 外无需安装其他内容。

---

安装

pip install sec-mcp

系统要求

• Python 3.11 或更高版本（CI 测试范围为 3.11–3.14）
• SQLite 3（随 Python 一同提供）
• 可选：通过 pip install "sec-mcp[fast-cidr]" 安装 pytricia，以实现快速 CIDR 匹配；若不安装，则使用纯 Python 的 ipaddress 匹配器（pytricia 需要从源码构建，因此需要 C 编译器）

从源码安装

需要 uv（如有需要，可运行 pip install uv 安装）：

git clone https://github.com/Montimage/sec-mcp.git
cd sec-mcp
uv sync    # creates .venv, installs the package editable + dev tools, pinned by uv.lock

---

用法

CLI

# Single check — auto-detects domain vs URL vs IP
sec-mcp check https://example.com
sec-mcp check malicious-domain.com
sec-mcp check 192.168.1.1

# Type-specific checks
sec-mcp check-domain example.com
sec-mcp check-url https://example.com/path
sec-mcp check-ip 192.168.1.1

# Batch check from a file (one value per line)
sec-mcp batch urls.txt

# Status, updates, sampling and cache control
sec-mcp status
sec-mcp update
sec-mcp sample -n 20
sec-mcp flush-cache

除 sample 外，每条命令都支持 --json，用于生成机器可读的输出。

Python API

from sec_mcp import SecMCP

client = SecMCP()          # optional: SecMCP(db_path="/path/to/mcp.db")
client.update()            # download + index the feeds (first run only)

# Single check — check() returns CheckResult(blacklisted, explanation)
result = client.check("https://example.com")
print(result.blacklisted, result.explanation)
# result.to_dict() -> {"is_safe": True, "explain": "Not blacklisted"}

# Type-specific checks
client.check_domain("example.com")
client.check_url("https://example.com/path")
client.check_ip("192.168.1.1")

# Batch check
urls = ["https://example.com", "https://test.com", "192.168.1.1"]
for value, r in zip(urls, client.check_batch(urls)):
    print(f"{value}: {'BLOCKED' if r.blacklisted else 'SAFE'}")

# Status — StatusInfo(entry_count, last_update, sources, server_status)
status = client.get_status()
print(status.entry_count, status.last_update, client.scheduler_alive())

MCP 服务

sec-mcp 作为 stdio MCP 服务运行，用于 AI/LLM 集成（Claude Desktop、Cursor、Windsurf 等）。仓库根目录下的 server.json 提供了对应的 MCP Registry 条目（io.github.montimage/sec-mcp）。

1. 安装 uv（它会提供 uvx）：参阅 uv 安装文档，或运行 pip install uv。

2. 初始化一次黑名单：

   uvx --from sec-mcp sec-mcp update
   

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

   {
     "mcpServers": {
       "sec-mcp": {
         "command": "uvx",
         "args": ["--from", "sec-mcp", "sec-mcp-server"],
         "env": { "MCP_USE_V2_STORAGE": "true" }
       }
     }
   }
   

   工作原理：uvx 会从 PyPI 下载 sec-mcp 包并运行其 sec-mcp-server 入口点 — 无需虚拟环境或 Python 绝对路径。 也可以将 sec-mcp 安装到任意环境中（pip install sec-mcp），并使用 "command": "sec-mcp-server"，无需设置 args。

MCP 工具

工具	说明
check_batch	在一次调用中检查多个域名/URL/IP
get_status	黑名单状态：条目数量、按来源分类的明细、scheduler_alive
update_blacklists	立即强制更新（受速率限制；按来源发送进度）
get_diagnostics	诊断信息 — 模式：summary、full、health、performance、sample
add_entry	手动添加黑名单条目（URL/域名或 IP，可选评分）
remove_entry	按域名、URL 或 IP 移除黑名单条目

update_blacklists 每隔 min_update_interval_seconds（默认在 config.json 中为 300）最多允许一次强制更新：在此间隔内再次调用时，会返回 {"updated": false, "reason": ...}，但不会启动下载；提供进度令牌的调用方会收到每个来源对应的一条 notifications/progress。

get_diagnostics 模式：

• summary（默认）：条目数量、来源和上次更新时间
• full：完整诊断数据，包括健康状态、统计信息和性能
• health：仅数据库可访问性和调度器状态
• performance：查找指标和命中率（仅限 v2 存储）
• sample：随机抽取黑名单条目（sample_count 参数，1–100）

HTTP 传输与落地页 Playground

sec-mcp-server 默认使用 stdio。添加 --http 可改为通过可流式 HTTP 提供 MCP 服务，这样浏览器（包括落地页上的实时 Playground）便能调用这些工具：

sec-mcp update                       # populate the database once
sec-mcp-server --http                # → http://127.0.0.1:8000/mcp
sec-mcp-server --http --host 0.0.0.0 --port 9000

• CORS 允许 SEC_MCP_CORS_ORIGINS 中指定的来源（默认值：端口为 3000/4173 的本地 Vite 开发/预览环境，以及 https://montimage.github.io）；始终不允许使用凭据。 * 允许任意来源，同时也会禁用 DNS 重绑定保护。
• 设置 SEC_MCP_HTTP_AUTH_TOKEN 可要求每个请求都携带 Authorization: Bearer <token>。绑定非环回主机（例如 --host 0.0.0.0）且未设置该变量时，每次运行都会生成随机令牌并将其打印为 #token=… 片段：将它追加到落地页 URL 后，Playground 会使用该令牌连接。传入 --no-auth 可选择禁用认证（会记录警告）。

---

性能优化

启用内存中的 v2 后端，大幅提升查找速度：

export MCP_USE_V2_STORAGE=true

测量结果

以下数据来自随附的测试工具（run_benchmark.sh，参见基准测试）：

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

内存用量

• v1（默认）：约 10 MB（数据库位于磁盘上）
• v2：内存占用约 40–80 MB，具体取决于信息源的大小

v2 速度快的原因

1. 每种条目类型各使用一个内存索引 — 使用单一的域名/URL/IP 索引进行 O(1) 哈希查找；重新加载时会先构建临时索引，再在锁内进行切换，因此读取操作不会被阻塞，并且始终能看到完整快照。
2. URL 规范化 — HTTP://EVIL.COM/ → http://evil.com；会移除跟踪参数（utm_*、fbclid、…）。两个后端共用同一个规范化器，因此判定结果一致。
3. IPv4 整数存储 — 每个 IP 占 4 字节，而非以字符串存储时的 13+ 字节。
4. CIDR 匹配 — 安装 fast-cidr 可选依赖时使用 pytricia，否则使用纯 Python ipaddress。

性能监控

# v2 storage only — the get_diagnostics MCP tool exposes the same data
metrics = client.storage.get_metrics()
# {"total_lookups": ..., "cache_hits": ..., "hit_rate": ...,
#  "avg_lookup_time_ms": ..., "memory_usage_mb": ..., "using_pytricia": ...}

回滚到 v1

export MCP_USE_V2_STORAGE=false   # or unset MCP_USE_V2_STORAGE

---

基准测试

使用随附的测试工具比较存储后端（完整比较需要 pip install "sec-mcp[fast-cidr]"；sec-mcp 自带 psutil）：

./run_benchmark.sh --quick            # 10K entries, ~30 s
./run_benchmark.sh                    # 50K entries, ~2 min
./run_benchmark.sh --full --memory    # 100K entries + memory profiling
./run_benchmark.sh --v1 --v2opt       # compare specific versions
./run_benchmark.sh --all              # all versions

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

方法和预期输出：BENCHMARK_PLAYBOOK.md。

---

配置

环境变量

变量	说明	默认值
MCP_DB_PATH	自定义 SQLite 数据库位置	平台相关（见下文）
MCP_USE_V2_STORAGE	true 选择内存中的 HybridStorage 后端	false（v1 存储）
MCP_LOG_PATH	日志文件位置	platformdirs 日志目录
MCP_CACHE_DIR	Feed 下载缓存目录	platformdirs 缓存目录
MCP_DISABLE_SCHEDULER	设为 1 可不启动每日更新调度器线程	未设置（调度器会运行）
SEC_MCP_CORS_ORIGINS	sec-mcp-server --http 的逗号分隔 CORS 来源；* = 任意来源	本地 Vite 端口 + GitHub Pages
SEC_MCP_HTTP_AUTH_TOKEN	sec-mcp-server --http 所需的 Bearer 令牌	未设置（在非回环主机上每次运行时生成）

默认数据库位置

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

配置文件

随附的 sec_mcp/config.json 用于控制 Feed 来源、更新计划和 Feed 安全限制：

{
  "blacklist_sources": { "OpenPhish": "...", "PhishStats": "...", "URLhaus": "...", "...": "10 feeds total" },
  "update_time": "00:00",
  "min_update_interval_seconds": 300,
  "cache_size": 10000,
  "max_feed_bytes": 67108864,
  "min_feed_entries": 1,
  "max_feed_entries": 500000,
  "max_range_addresses": 65536,
  "log_level": "INFO"
}

update_time 设置每日更新的时间，min_update_interval_seconds 限制强制更新的频率，cache_size 限制 v1 正向命中 LRU 的大小，max_*/min_* 键则限制可接受的 Feed 大小。

---

项目结构

sec-mcp/
├── sec_mcp/                  # The package
│   ├── __init__.py           # Public API: SecMCP, CheckResult, StatusInfo, __version__
│   ├── sec_mcp.py            # SecMCP facade (check/check_batch/update/get_status/…)
│   ├── cli.py                # `sec-mcp` CLI (click)
│   ├── mcp_server.py         # Six MCP tools (SDK 2.x MCPServer)
│   ├── start_server.py       # `sec-mcp-server` entry point (stdio, or --http)
│   ├── http_transport.py     # Streamable-HTTP app: CORS, DNS-rebinding, bearer auth
│   ├── storage.py            # Backend selector + v1 database-only storage
│   ├── storage_queries.py    # v1 read/query half
│   ├── storage_base.py       # Shared schema, DB-path resolution, normalize_url
│   ├── storage_v2.py         # v2 HybridStorage (in-memory indexes + metrics)
│   ├── storage_v2_db.py      # v2 persistence layer (all SQLite access)
│   ├── storage_v2_index.py   # v2 in-memory indexes + CIDR matching
│   ├── storage_v2_writes.py  # v2 write path (persistence + rollback)
│   ├── storage_v2_stats.py   # v2 stats/reporting mixin
│   ├── feed_parsers.py       # One parser per blacklist feed source
│   ├── update_blacklist.py   # Feed download, scheduling and ingestion
│   ├── utility.py            # Validation, logging, config
│   ├── config.json           # Shipped defaults (sources, schedule, bounds)
│   └── tests/                # pytest suite (pytest.ini sets testpaths)
├── docs/                     # ARCHITECTURE, DEVELOPMENT, DEPLOYMENT, agent-env, playbook, decisions/, archive/
├── scripts/                  # check_test_baseline.sh (CI floor gate)
├── .github/                  # CI + PyPI + landing workflows, issue & PR templates
├── benchmark.py              # Benchmark script
├── run_benchmark.sh          # Benchmark helper
├── server.json               # MCP Registry metadata
├── react-landing-page/       # Standalone Vite site (not part of the package)
├── CONTRIBUTING.md           # Dev setup, tests, conventions, PR process
├── CODE_OF_CONDUCT.md        # Contributor Covenant
├── SECURITY.md               # Vulnerability reporting policy
├── CHANGELOG.md              # Release history (Keep a Changelog)
├── LICENSE                   # Apache-2.0
└── README.md                 # This file

---

文档

文档	内容
docs/ARCHITECTURE.md	设计概览：组件、存储后端、检查语义、MCP 层
docs/DEVELOPMENT.md	开发工作流中心：设置、仓库布局、CI 门槛、约定
docs/DEPLOYMENT.md	PyPI 发布流程、面向终端用户的 MCP 服务部署、落地页部署
docs/agent-env.md	工具链、环境变量、探测隔离
docs/playbook.md	面向 MCP 客户端的十大使用指南
docs/decisions/	架构决策记录（ADR）
BENCHMARK_PLAYBOOK.md	基准测试方法和结果解读
CONTRIBUTING.md	开发环境设置、测试/代码检查/覆盖率命令、分支和 PR 约定
SECURITY.md	支持的版本和私密漏洞报告
CHANGELOG.md	发布历史

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解开发环境设置（uv sync 是唯一的安装命令）、测试和 lint 命令，以及分支、提交和 PR 规范。所有贡献者都应遵守行为准则，安全问题则应按照 SECURITY.md 中的说明私下报告。

• 问题：GitHub Issues — 提供错误报告和功能请求模板
• 邮箱：[email protected]
• 网站：https://www.montimage.eu

---

相关出版物

目前尚无已知引用 sec-mcp 的出版物。如果您在学术研究、演讲或博客文章中使用了 sec-mcp，请提交 issue，以便我们在此列出。

---

许可证

Apache License 2.0 — 版权所有 2026 Montimage。

---

致谢

• 威胁情报提供商：OpenPhish、PhishStats、URLhaus、PhishTank、Spamhaus、Dshield、CINSSCORE、EmergingThreats、FeodoTracker 和 BlocklistDE
• 基于 Model Context Protocol Python SDK 构建
• 由 Python、SQLite、Click 和 httpx 提供支持