Magwerste/ip-scanner

# IP 扫描器 根据本地威胁情报列表和 VirusTotal 扫描一个或多个 IP 地址。最初专为 Azure AD / Entra ID 登录日志分析而设计，但也适用于任何 IP 列表。 每个公共 IP 都会首先与本地黑名单进行比对，然后提交给 VirusTotal。如果某个 IP 被本地列表匹配到，则会在输出中合并这两种检测结果——因此您总能获得完整的信息。私有和保留 IP 会被静默跳过，且绝不会发送到任何地方。 自动执行 VirusTotal Public API 限制： - **每天 500 次请求**（通过 `quota_state.json` 跨重启追踪） - **每分钟 4 次请求**（调用之间强制执行 15 秒延迟） ## 下载 前往 [Releases](../../releases) 页面并下载 `ip-scanner.exe` —— 无需安装 Python。 ## 如何获取 VirusTotal API 密钥 1. 前往 [https://www.virustotal.com](https://www.virustotal.com) 并点击 **Join us** 注册一个免费账户。 2. 登录后，点击右上角的个人资料图标并选择 **API key**。 3. 复制该密钥 —— 您将在下一步中用到它。 免费的 Public API 每天允许 500 次查询，每分钟 4 次。无需付费。 ## 安装说明 1. 将 `ip-scanner.exe` 放在您计算机上的一个文件夹中。 2. 在同一文件夹中，创建一个名为 `.env` 的文件，其中包含您的 VirusTotal API 密钥： VT_API_KEY=your_api_key_here 3. 运行扫描器 —— 无需终端： - **双击** `ip-scanner.exe` 以打开交互式提示符并直接粘贴 IP。 - 在文件资源管理器中**将 CSV 或 TXT 文件拖放到** `ip-scanner.exe` 上以自动扫描。 ## 运行原理 ``` Input IPs │ ▼ Strip private / RFC 1918 addresses (never sent anywhere) │ ▼ Check local threat intel lists (no external API calls) ├── IPsum — downloaded fresh each run ├── CINS Army — bundled with the exe ├── Tor Exit Nodes — downloaded fresh each run └── DShield — downloaded fresh each run (subnet blocklist) │ ├── MATCH → flagged (local), then ALSO queried against VirusTotal │ └── sources combined: e.g. "IPsum, VirusTotal" │ └── NO MATCH → queried against VirusTotal │ ├── Malicious / Suspicious → flagged └── Clean → not included in output │ ▼ malicious_ips.csv — flagged IPs only, with Severity and Source columns ``` 每次运行都会下载最新的 IPsum、Tor 出口节点和 DShield 副本。CINS Army 列表已内置于 exe 中。 ## 使用说明 ### 拖放（无需终端） 在文件资源管理器中将 CSV 或 TXT 文件拖放到 `ip-scanner.exe` 上。扫描器会自动打开并开始扫描。 ### 从 Entra ID / Azure AD CSV 导出文件扫描 ``` ip-scanner.exe --file SignInLogs_export.csv ``` 扫描器会自动检测 Entra ID 格式，并且仅读取 IP 地址列——所有其他列（用户、设备、位置等）都会被直接丢弃，不予存储。 ### 从纯文本文件扫描（每行一个 IP） ``` ip-scanner.exe --file suspicious_ips.txt ``` ### 直接扫描特定 IP ``` ip-scanner.exe --ips 8.8.8.8 1.1.1.1 185.220.101.5 ``` ### 交互模式（双击或无参数） ``` ip-scanner.exe ``` 粘贴一个或多个 IP，或者每行输入一个。在空行上按回车键开始扫描。 ## 选项 | 标志 | 简写 | 描述 | |---|---|---| | `--file PATH` | `-f` | 输入文件（纯文本或 CSV） | | `--ips IP [IP ...]` | `-i` | 作为参数传入的一个或多个 IP | | `--output PATH` | `-o` | 恶意 IP CSV 的自定义路径（默认：`output/malicious_ips.csv`） | | `--no-report` | | 跳过保存 CSV 报告 | | `--quiet` | `-q` | 禁止输出每个 IP 的结果，仅显示摘要 | | `--no-enrich` | | 对本地列表命中的结果跳过 VirusTotal（节省配额，但会丢失合并的来源数据） | ## 输出 **终端：** 每个 IP 的颜色编码结果： - **红色** —— 标记为恶意 - **黄色** —— 标记为可疑 - **绿色** —— 干净 被本地列表匹配到的 IP 会以 `MALICIOUS (local)` 的形式连同匹配的源名称在内联中打印出来。 **CSV 报告：** 每次扫描后保存到 `output/malicious_ips.csv`（除非使用了 `--no-report`）。如果 `output/` 文件夹不存在，则会自动创建。仅写入被标记的 IP —— 不包括干净的 IP。列： `ip`, `severity`, `source`, `malicious_engines`, `suspicious_engines`, `reputation`, `country`, `asn`, `as_owner`, `network`, `last_analysis_date`, `scan_timestamp` | 列 | 描述 | |---|---| | `severity` | `HIGH`、`MEDIUM` 或 `LOW` —— 通俗的英文风险评级 | | `source` | 命中来源 —— 例如 `IPsum`、`VirusTotal`，或同时被两者命中则为 `IPsum, VirusTotal` | | `malicious_engines` | 在查询的引擎总数中将其标记为恶意的引擎数量 —— 例如 `3\|94` | | `suspicious_engines` | 在查询的引擎总数中将其标记为可疑的引擎数量 —— 例如 `1\|94` | 引擎计数会根据 VirusTotal 在该 IP 的特定扫描中运行的引擎数量而调整。当使用 `--no-enrich` 时，对于仅本地命中的结果会显示 `N/A`。 ### 严重性评级 | 级别 | 条件 | |---|---| | `HIGH` | 4 个或更多恶意引擎检测 | | `MEDIUM` | 1-3 个恶意引擎检测 | | `LOW` | 仅有可疑引擎（无恶意），或 Tor 出口节点 / 无 VT 恶意命中记录的本地列表 | 本地列表命中和 VirusTotal 检测是独立计算的。如果 VT 发现了恶意引擎，则使用该计数（两个来源检测到了相同的威胁）。如果 VT 未发现异常，则每个标记了该 IP 的本地列表计为一次检测 —— 因此，如果某个 IP 同时在 IPsum 和 DShield 中且没有 VT 恶意数据，则其得分为 2 → `MEDIUM`。 ## 本地威胁情报来源 | 来源 | 类型 | 更新 | |---|---|---| | [IPsum](https://github.com/stamparm/ipsum) | 已知的恶意 IP（从多个黑名单聚合） | 每次运行时下载 | | [Tor Exit Nodes](https://www.dan.me.uk/torlist/) | 活跃的 Tor 出口节点 IP | 每次运行时下载 | | [DShield](https://www.dshield.org/block.txt) | 排名前列的攻击源子网 | 每次运行时下载 | | CINS Army | 已知的恶意 IP（Collective Intelligence Network Security） | 已内置 —— 无需下载 | 如果下载失败，运行将继续而不包含该列表 —— 会打印一条警告，但不会跳过任何 IP。 ## API 配额 VirusTotal Public API 允许**每天 500 次请求**。扫描器会在 `quota_state.json` 中跟踪使用情况，并在 UTC 午夜自动重置。当剩余请求少于 50 次时会显示警告。 默认情况下，每个公共 IP 都会在 VirusTotal 中进行查询 —— 包括那些已经被本地列表捕获的 IP，以便合并来源。如果您正在扫描一个非常大的文件并且需要节省配额，请传入 `--no-enrich` 以针对本地列表命中的结果跳过 VT。 如果要扫描的 IP 数量超过您剩余的每日配额，则会在扫描开始前打印一条警告，以便您决定是继续执行还是使用 `--no-enrich`。 ## 面向开发者 ### 从源码运行 请参阅 [setup.md](setup.md) 获取完整指南（开发者/源码安装）。有关面向非技术用户的最终用户指南，请参阅 [walkthrough.md](walkthrough.md)。快速开始： ``` git clone https://github.com/Magwerste/ip-scanner cd vt-py-ip-scanner python -m venv .venv .venv\Scripts\activate pip install -e ".[dev]" ``` 使用您的 API 密钥创建一个 `.env` 文件，然后运行： ``` ip-scanner --file SignInLogs_export.csv ``` ### 项目结构 ``` vt-py-ip-scanner/ ├── src/ │ └── ip_scanner/ │ ├── __init__.py # Package marker │ ├── __main__.py # Entry point — CLI, input handling, scan loop │ ├── client.py # VirusTotal API calls and response parsing │ ├── config.py # Config loading from .env and constants │ ├── output.py # Terminal display (Rich) and CSV writing │ ├── rate_limiter.py # Per-minute and daily quota enforcement │ └── threat_intel.py # Local list download, loading, and lookup ├── tests/ # Test suite (see tests/README.md) ├── vt-scan.spec # PyInstaller build spec ├── .env # Your API key (never share or commit this) ├── .env.example # Safe template — copy this to .env ├── pyproject.toml # Package metadata and entry point definition ├── quota_state.json # Auto-created — tracks daily API usage across restarts ├── threat_intel/ # Auto-created — downloaded list files cached here ├── threat_intel_static/ # Bundled static lists (CINS Army) │ └── cinsarmy_badguys.txt # CINS Army blocklist (included in repo, bundled in exe) ├── output/ │ └── malicious_ips.csv # Auto-created — flagged IPs from each run └── .venv/ # Virtual environment (created during setup) ``` ## 致谢 如果没有以下免费且开放的资源，这个工具将无法实现： - **[VirusTotal](https://www.virustotal.com)** —— 感谢其提供免费的 Public API，使每个人都能进行大规模的 IP 信誉查询。其慷慨的每天 500 次请求配额使该工具在实际应用中切实可行。 - **[IPsum](https://github.com/stamparm/ipsum)** 由 [@stamparm](https://github.com/stamparm) 提供 —— 这是一个由社区维护的聚合黑名单，将来自数十个来源的威胁情报整合到了一个可靠的订阅源中。 - **[Tor Project / dan.me.uk](https://www.dan.me.uk/torlist/)** —— 感谢其维护了一个公开访问的活跃 Tor 出口节点列表，从而能够在登录日志中检测匿名流量。 - **[DShield / SANS Internet Storm Center](https://www.dshield.org)** —— 感谢其提供包含最活跃攻击源子网的黑名单，该名单根据安全社区贡献的真实防火墙数据每日更新。 - **[CINS Army / Collective Intelligence Network Security](https://cinsscore.com)** —— 感谢其免费分发已知恶意行为者的黑名单，该名单已直接包含在此工具中，因此无需额外设置即可开箱即用。 感谢所有维护这些数据源并免费向社区开放的人们。

标签：Ask搜索, IP查询, VirusTotal, Web技术栈, 威胁情报, 安全运营, 开发者工具, 扫描框架, 漏洞挖掘, 逆向工具