sec-mcp: Security Checking Toolkit

sec-mcp

ドメイン、URL、IP アドレスをリアルタイムのセキュリティブラックリストと照合できます。Python ライブラリ、ターミナル CLI、または LLM エージェントにリアルタイムの脅威コンテキストを提供する MCP サーバーとして利用できます。

sec-mcp は、10 種類の公開脅威インテリジェンスフィードをローカルの 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 範囲照合に対応しています
• 10 種類の脅威インテリジェンスフィード — OpenPhish、PhishStats、URLhaus、PhishTank、Spamhaus DROP、Dshield、CINSSCORE、EmergingThreats、FeodoTracker、BlocklistDE
• 3 つのインターフェースと 1 つのエンジン — Python API（SecMCP）、Click CLI（sec-mcp）、MCP サーバー（stdio またはストリーム可能な HTTP）。6 つの型付きツールを公開します
• 2 種類のストレージバックエンド — デフォルトの SQLite ストレージ（v1）、またはメモリ内ハイブリッド（v2、MCP_USE_V2_STORAGE=true）。型ごとの O(1) インデックスを備え、同梱のベンチマークではデータベースのみの経路と比べて最大約 28,000 倍高速に検索できます
• URL の正規化 — 両方のバックエンドで共通の正規化処理を使用します。小文字化、デフォルトスキームの処理、トラッキングパラメーター（utm_*、fbclid、…）の削除により、異なる URL 表記でも同じ判定結果になります
• 安全なフィード取り込み — HTTPS のみでダウンロードし、max_feed_bytes とエントリー数の妥当性チェックで制限します。1 つのフィードでエラーが発生しても、他のフィードは中断されません
• 毎日の定期更新 — schedule ジョブが update_time にフィードを更新します。強制更新は min_update_interval_seconds（デフォルトは 300 秒）ごとに 1 回までに制限されます
• 並行処理に対応 — SQLite は WAL モードと synchronous=NORMAL で動作し、チェックごとにスレッドローカルの共有接続を使用します。v2 バックエンドでは、ロックフリーのスナップショット読み取りに対応しています
• 構造化された MCP 出力 — 各ツールは型付きの outputSchema を公開し、結果には structuredContent が含まれます。check_batch は 3 値の判定（safe／blacklisted／invalid）を返し、ドメインエラーはプロトコルのクラッシュではなく isError の結果として通知されます
• 可観測性 — get_diagnostics MCP ツール（summary／full／health／performance／sample モード）、実際の scheduler_alive の状態、ソースごとのエントリー数を確認できます

---

デモ

プレースホルダー — 公開前にメンテナーの入力が必要です。 現在、リポジトリにはスクリーンショットやデモ用アセットは含まれていません。推奨案：sec-mcp update → sec-mcp check <url> の asciinema 録画、または Claude Desktop 内の 6 つの MCP ツールのスクリーンショットです。ファイルを docs/assets/ 配下（例：docs/assets/demo.gif）に追加し、このブロックを ![sec-mcp demo](docs/assets/demo.gif) に置き換えてください。

---

クイックスタート

5 分以内に、最初の判定結果を確認できます。

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 に同梱）
• 任意：高速な CIDR 照合には pip install "sec-mcp[fast-cidr]" で pytricia をインストールしてください。未インストールの場合は、純粋な 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 は、AI／LLM 連携（Claude Desktop、Cursor、Windsurf、…）用の stdio MCP サーバーとして動作します。リポジトリルートの 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 パスは 不要です。あるいは、任意の環境に pip install sec-mcp でインストールし、 args なしで "command": "sec-mcp-server" を使用することもできます。

MCP ツール

ツール	説明
check_batch	複数のドメイン／URL／IP を 1 回の呼び出しでチェックします
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）ごとに 1 回のみ強制更新できます。この間隔内に 2 回目の呼び出しを行うと、ダウンロードを開始せずに {"updated": false, "reason": ...} を返します。進行状況トークンを指定した呼び出し元には、ソースごとに notifications/progress が 1 件送信されます。

get_diagnostics のモード：

• summary（デフォルト）：エントリー数、ソース、最終更新時刻
• full：ヘルス、統計、パフォーマンスを含む完全な診断データ
• health：データベースへの接続状態とスケジューラーの状態のみ
• performance：検索メトリクスとヒット率（v2 ストレージのみ）
• sample：ブラックリストのエントリーからランダムにサンプルを取得します（sample_count パラメーターは 1～100）

HTTP トランスポートとランディングページのプレイグラウンド

sec-mcp-server はデフォルトで stdio を使用します。--http を追加すると、代わりにストリーミング可能な HTTP で MCP を提供できるため、ブラウザーからツールを呼び出せます。ランディングページのライブプレイグラウンドも利用できます。

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 リバインディング保護も無効にします。
• すべてのリクエストで Authorization: Bearer <token> を必須にするには、SEC_MCP_HTTP_AUTH_TOKEN を設定します。ループバック以外のホスト（例：--host 0.0.0.0）にバインドするときにトークンが設定されていない場合、その起動時にランダムなトークンが生成され、#token=… フラグメントとともに表示されます。これをランディングページの URL に追加すると、プレイグラウンドがそのトークンを使って接続します。認証を無効にするには --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,600 倍
URL チェック	5 ms	0.001 ms	0.0007 ms	約 7,000 倍
IP + CIDR チェック	200 ms	0.01 ms	0.007 ms	約 28,000 倍
100 件の一括処理	2～3 s	50～100 ms	50～100 ms	約 30 倍

メモリ使用量

• v1（デフォルト）：約 10 MB（データベースはディスク上）
• v2：フィードのサイズに応じて、インメモリーで約 40～80 MB

v2 が高速な理由

1. エントリータイプごとに 1 つのインメモリーインデックス — 単一のドメイン／URL／IP インデックスを使った O(1) のハッシュ検索を行います。再読み込み時はスクラッチインデックスを構築してロック下で切り替えるため、読み取りがブロックされず、常に完全なスナップショットを参照できます。
2. URL の正規化 — HTTP://EVIL.COM/ → http://evil.com。トラッキングパラメーター（utm_*、fbclid、…）は削除されます。両方のバックエンドで共通の正規化処理を使うため、判定結果は一致します。
3. IPv4 の整数ストレージ — IP あたり、文字列の 13 バイト以上に対して 4 バイトで保存します。
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]" が必要です。psutil は sec-mcp に同梱されています）。

./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	フィードダウンロードキャッシュのディレクトリ	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 が要求するベアラートークン	未設定（ループバック以外のホストでは実行ごとに生成）

デフォルトのデータベース保存場所

• 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 で、フィードソース、更新スケジュール、フィードの安全性に関する上限を設定します。

{
  "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_* キーは受け入れるフィードサイズの上限と下限を設定します。

---

プロジェクト構成

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 クライアント向けトップ 10 使用ガイド
docs/decisions/	アーキテクチャ決定記録（ADR）
BENCHMARK_PLAYBOOK.md	ベンチマークの手法と解釈
CONTRIBUTING.md	開発環境のセットアップ、テスト／Lint／カバレッジのコマンド、ブランチと PR の規約
SECURITY.md	サポート対象のバージョンと非公開での脆弱性報告
CHANGELOG.md	リリース履歴

---

貢献

貢献を歓迎します！開発環境のセットアップ（インストールコマンドは uv sync のみです）、テストと lint のコマンド、ブランチ／コミット／PR の規約については、CONTRIBUTING.md をご覧ください。すべての貢献者は 行動規範 に従ってください。また、セキュリティ上の問題は 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 を使用