6つの無料脅威インテリジェンスAPIを横断してIP、ドメイン、ハッシュ、CVEを調査 — ブラウザのタブを切り替えることなく。

クイックスタート · 使い方 · アーキテクチャ · APIキー · スクリーンショット · コントリビューション

🚀 公式の Awesome OSINT リポジトリに掲載されています。

📖 概要

ThreatLens は、最も信頼されている無料OSINTソースを横断して脅威インテリジェンスの検索を統合する単一のコマンドラインツールです。IPを5つの異なるウェブサイトに貼り付ける代わりに、ThreatLensはそれらすべてを並列でクエリし、結果を正規化して、明確な判定を提供します — ターミナル上で、あるいは洗練された色分けされたExcel/JSON/CSVレポートとして。

SOCアナリスト、インシデントレスポンダー、脅威ハンター、そしてシェルを離れることなく迅速で信頼性の高いIOCエンリッチメントを求めるすべての人のために構築されています。

✨ 機能

🚀 クイックスタート

# 1. Clone & install
git clone https://github.com/AbdaullahAG/threatlens.git
cd threatlens
pip install -r requirements.txt

# 2. Configure your API keys
cp config/keys.env.example config/keys.env
# → edit config/keys.env and fill in your keys

# 3. Run your first scan
python main.py -i 45.33.32.156

💡 NVD (CVE検索) はAPIキーなしですぐに動作します。 その他のすべてのAPIは、サインアップに2分もかからない無料ティアを提供しています — 以下の APIキーを参照してください。

再現可能なインストール (依存関係をロック)

pip install --require-hashes -r requirements.lock

🧰 使い方

すべてのCLIフラグを表示

🏗️ アーキテクチャ

threat_intel_tool/
├── main.py                      # CLI entry point & argument parser
├── requirements.txt             # Runtime dependencies
├── requirements-dev.txt         # Dev/CI tooling (ruff, bandit, pip-audit, pip-tools)
├── requirements.lock            # Pinned lockfile with SHA-256 hashes
├── pytest.ini                   # pytest configuration (marks, etc.)
├── config/
│   └── keys.env                 # API keys (copy from keys.env.example)
├── output/                      # Generated reports land here
├── src/
│   ├── engine.py                # Main orchestrator (collect → enrich → report)
│   ├── models.py                # IOC & EnrichmentResult dataclasses
│   ├── storage.py               # SQLite cache & investigation history
│   ├── parsers/
│   │   └── ioc_parser.py        # Regex-based IOC extractor with validation
│   ├── enrichers/
│   │   ├── base.py              # Abstract base — safe HTTP client (redirect-block, budget, retry)
│   │   ├── registry.py          # Enricher dispatcher
│   │   ├── abuseipdb.py         # AbuseIPDB      (IP)
│   │   ├── virustotal.py        # VirusTotal     (IP / Domain / URL / Hash)
│   │   ├── otx.py               # AlienVault OTX (IP / Domain / URL / Hash)
│   │   ├── shodan.py            # Shodan         (IP)
│   │   ├── urlscan.py           # URLScan.io     (URL / Domain)
│   │   └── nvd.py               # NVD / NIST     (CVE — no key required)
│   ├── reporters/
│   │   ├── excel_reporter.py    # Color-coded Excel reports
│   │   ├── other_reporters.py   # JSON & CSV output
│   │   └── terminal_display.py  # Rich terminal tables
│   └── utils/
│       ├── config.py            # API key loader & runtime config
│       ├── logger.py            # Rich logging setup
│       ├── banner.py            # ASCII banner
│       ├── quota.py             # Per-run request budget (thread-safe)
│       └── security.py         # IOC validation, formula neutralisation, secret redaction
└── tests/
    ├── conftest.py              # pytest fixtures & --run-e2e flag
    ├── test_core.py             # IOC parser, verdict logic, cache round-trip (34 tests)
    ├── test_enrichers.py        # BaseEnricher HTTP edge-cases — mock only (9 tests)
    ├── test_reporters.py        # Excel/CSV formula protection + SQLite integration (17 tests)
    └── test_cli_e2e.py          # Full CLI run against real NVD API (opt-in, --run-e2e)

設計原則

プラグイン可能なエンリッチャー — 新しいインテリジェンスソースの追加は、BaseEnricher をサブクラス化する src/enrichers/ 内の新しいファイルのみを必要とします。他の場所での変更は不要です。
型付きIOC — IOCタイプは生の文字列ではなく列挙型であり、実行時ではなく開発時にミスを捕捉します。
安全なHTTPクライアント — BaseEnricher.get() はHTTPSのみ、ホスト許可リスト、リダイレクトブロック、429/Retry-After処理、リクエスト予算の上限を1か所で強制します。
CI/CDフレンドリーな設定 — キーは config/keys.env から読み込まれ、システム環境変数にフォールバックします。
エンリッチャーごとのレート制限 — 設定可能な遅延 (--delay) により、各APIの無料ティアの制限内に収まります。
障害の分離 — すべてのエンリッチャーエラーは捕捉され、ログに記録され、result.errors に保存されます。1つのAPIが失敗してもスキャン全体が停止することはありません。
スプレッドシートの安全性 — ExcelとCSVに書き込まれるすべての値は、数式インジェクション (=, +, -, @ プレフィックス) に対して中和されます。

🔑 APIキー

🧪 テスト

# Run all unit and integration tests (no network required)
pytest tests/ -v --ignore=tests/test_cli_e2e.py

# With coverage report
pytest tests/ -v --ignore=tests/test_cli_e2e.py --cov=src --cov-report=term-missing

# Run the end-to-end CLI test (makes a real NVD request)
pytest tests/test_cli_e2e.py --run-e2e -v

テスト内容

🔐 セキュリティ

📊 出力例

ターミナル:

╭──────────────────────────── IOC Collection ─────────────────────────────╮
│ Found 4 IOCs to investigate                                              │
│   CVE: 1  Domain: 1  Hash: 1  IP: 1                                     │
╰──────────────────────────────────────────────────────────────────────────╯
✓ Active APIs: abuseipdb, virustotal, otx, shodan, urlscan, nvd

🌐 IP Address Results
┌─────────────────┬──────────────┬──────────┬─────────┬────────────────────┐
│ IP Address      │ Verdict      │ Abuse %  │ Country │ ISP / Org          │
├─────────────────┼──────────────┼──────────┼─────────┼────────────────────┤
│ 45.33.32.156    │ Suspicious   │ 42       │ US      │ Linode             │
└─────────────────┴──────────────┴──────────┴─────────┴────────────────────┘

⚠️  CVE Results
┌──────────────────┬──────────┬──────┬──────────────┐
│ CVE ID           │ Severity │ CVSS │ Published    │
├──────────────────┼──────────┼──────┼──────────────┤
│ CVE-2021-44228   │ Critical │ 10.0 │ 2021-12-10   │
└──────────────────┴──────────┴──────┴──────────────┘

Excelレポート: 色分けされた判定 (🔴 悪意あり · 🟡 疑わしい · 🟢 クリーン) を持つマルチシートワークブック。output/ThreatLens_Report_<timestamp>.xlsx に保存されます。

🖼️ スクリーンショット

IP Usage Combo lookup #2 Combo lookup #1 Clean IP verdict Malicious and safe IP comparison Hash lookup

🗺️ ロードマップ

アイデアがありますか？ Issueを開く — コントリビューションと提案を歓迎します。

🤝 コントリビューション

コントリビューションは歓迎され、感謝されます！

リポジトリをフォークする
フィーチャーブランチを作成する: git checkout -b feature/my-feature
新しい動作に対するテストを追加する
pytest tests/ -v --ignore=tests/test_cli_e2e.py がパスし、ruff check . がクリーンであることを確認する
変更内容を明確に説明したプルリクエストを開く

新しいエンリッチャー、バグ修正、ドキュメントの改善、テストカバレッジはすべて素晴らしい最初のコントリビューションです — エンリッチャーの構造についてはアーキテクチャを参照してください。

📄 ライセンス

このプロジェクトは PolyForm Noncommercial License 1.0.0 の下でライセンスされています。

個人的、教育的、または研究目的でこのコードを使用、調査、変更、共有することは自由です。著者 ([email protected]) からの事前の書面による許可なしに 商用利用は許可されていません。

⚠️ 法的免責事項

このツールは 教育および許可されたセキュリティテストの目的のみ を意図しています。統合されたAPIの利用規約および適用されるすべての法律を遵守する責任は、もっぱらユーザーにあります。著者は一切の責任を負わず、このプログラムによる誤用、違法行為、または損害について責任を負いません。

ThreatLensが時間の節約に役立ったなら、⭐を付けることを検討してください — 他の人がプロジェクトを見つけるのに役立ちます。

🎯 IOCタイプ	IP、ドメイン、URL、ファイルハッシュ (MD5 / SHA1 / SHA256)、CVE
🔌 統合API	AbuseIPDB、VirusTotal、AlienVault OTX、Shodan、URLScan.io、NVD
📄 ログ解析	任意のログまたはテキストファイルからすべてのIOCタイプを自動抽出
📊 レポート	Excel (色分け)、JSON、CSV
💾 ローカルキャッシュ	設定可能なTTLを持つSQLiteキャッシュ — 既知のIOCの再クエリをスキップ
🛡️ セキュリティ	リダイレクトブロック、ホスト許可リスト、ログ内のAPIキー秘匿化、スプレッドシート数式の中和
🔒 ロックファイル	再現可能なインストールのためのSHA-256ハッシュ付き `requirements.lock`
💻 CLI体験	リッチなプログレスバー、色付きテーブル、クリーンな判定サマリー
🧩 アーキテクチャ	モジュール式エンリッチャー、型付きモデル、関心の厳密な分離
✅ テスト済み	`pytest` による60のユニット&統合テスト、GitHub ActionsによるCI
⚡ 耐障害性	1つのAPIが失敗しても他をブロックしない — エラーは分離されログに記録される

`# Investigate a single IP python main.py -i 45.33.32.156`	基本的な単一IOC検索
`# Investigate multiple IOC types at once python main.py -i 45.33.32.156 -d malware.example.com \ -s d41d8cd98f00b204e9800998ecf8427e -c CVE-2021-44228`	1回の実行でIOCタイプを組み合わせる
`# Parse a log file — all IOCs auto-extracted python main.py --file /var/log/apache2/access.log`	生ログから直接一括調査
`# Output JSON instead of Excel python main.py -i 8.8.8.8 --format json`	パイプライン向けの機械可読出力
`# Use only specific APIs python main.py -i 8.8.8.8 --apis abuseipdb virustotal`	エンリッチメントを選択したソースに制限
`# Generate every report format at once python main.py --file access.log --format all`	1回の実行でExcel + JSON + CSV
`# Lookup a CVE — no API key needed python main.py -c CVE-2021-44228 --apis nvd --format json`	NIST NVDによるCVEエンリッチメント (無料、キー不要)
`# Verbose / debug mode python main.py -i 8.8.8.8 -v`	トラブルシューティング用の完全なリクエスト/レスポンスログ

`-i, --ip`	調査するIPアドレス
`-d, --domain`	調査するドメイン
`-s, --hash`	ファイルハッシュ — MD5 / SHA1 / SHA256
`-c, --cve`	CVE ID、例: `CVE-2021-44228`
`--file`	IOCを自動抽出するログ/テキストファイルのパス
`--apis`	エンリッチメントを特定のAPIセットに制限
`--format`	出力形式: `excel` (デフォルト) \| `json` \| `csv` \| `all`
`--output`	レポートを保存するディレクトリ (デフォルト: `./output`)
`--no-report`	結果をターミナルにのみ出力し、ファイル保存をスキップ
`--cache-path`	ローカルキャッシュのSQLiteパス (デフォルト: `.threatlens/investigations.db`)
`--cache-ttl`	キャッシュの有効期間 (秒) (デフォルト: 3600)
`--no-cache`	ローカルキャッシュを完全にバイパス
`--max-requests`	1回の実行あたりの外部API呼び出しの上限 (デフォルト: 250)
`--max-iocs`	1回の実行あたりの最大ユニークIOC数 (デフォルト: 1000)
`--allow-private-iocs`	プライベート/ループバックIPを許可 (デフォルトでは無効)
`--delay`	レート制限調整のためのAPI呼び出し間の遅延
`-v, --verbose`	デバッグログを有効化

`test_core.py`	IOCパーサー (すべてのタイプ + エッジケース)、判定ロジック、SQLiteキャッシュのラウンドトリップ
`test_enrichers.py`	`BaseEnricher.get()` — リダイレクトブロック、予算枯渇、429+Retry-After、ログ内のAPIキー秘匿化、非JSONレスポンス、無効なJSON、ホスト許可リスト、HTTPスキームブロック
`test_reporters.py`	Excel & CSVの数式インジェクション中和 (7つのプレフィックスバリアント)、数値パススルー、SQLite TTL期限切れ、アップサート、調査記録
`test_cli_e2e.py`	完全なサブプロセス実行: `python main.py -c CVE-2021-44228 --apis nvd --format json` → 終了コード0、有効なJSON、正しい判定

HTTPSのみ	`BaseEnricher.get()` はリクエストを行う前に `https://` 以外のURLを拒否します
ホスト許可リスト	各エンリッチャーは `allowed_hosts` を宣言し、未知のホストへのリクエストは暗黙的に破棄されます
リダイレクトブロック	すべてのリクエストは `allow_redirects=False` を使用します
429 / Retry-After	`Retry-After` ヘッダーを尊重した1回の自動リトライ (最大15秒)
リクエスト予算	`--max-requests` は1回の実行あたりの総API呼び出しをハードキャップします
APIキー秘匿化	例外とログ行の生のキー値は `[REDACTED]` に置き換えられます
数式インジェクション	すべてのExcelおよびCSVセル値は `spreadsheet_value()` でサニタイズされます
IOC検証	CLIから提供されたすべてのIOCはエンリッチメント前に検証および正規化されます
プライベートIPガード	プライベート/ループバックアドレスはデフォルトで拒否されます (上書きするには `--allow-private-iocs`)
依存関係監査	`pip-audit` がCIで実行されます。`requirements.lock` は再現可能なインストールのためにすべてのハッシュを固定します

AbuseIPDB	無料	1日1,000チェック
VirusTotal	無料	4リクエスト/分 · 500リクエスト/日
AlienVault OTX	無料	無制限 (公開フィード)
Shodan	無料	限定的な検索
URLScan.io	無料	5,000リクエスト/日 (検索は無料)
NVD / NIST	任意	キー不要

ThreatLens

人気