xzarate/oculix

# Oculix 多源 IP 威胁情报，支持级联回退。 **AbuseIPDB → VirusTotal → Shodan → AlienVault OTX** 如果主要服务商达到速率限制或失败，Oculix 会自动回退到下一个。生成包含分数、国家、ISP、类别和来源的 CSV、TXT、HTML 和 JSON 报告。 零外部依赖 —— 仅使用 Python 3 标准库。 ## 要求 - Python 3.8+ - 至少一个 API key（推荐：AbuseIPDB + VirusTotal） | 服务商 | 注册地址 | 免费额度 | |----------|-------------|-----------| | [AbuseIPDB](https://www.abuseipdb.com) | Settings → API | 1,000 次/天 | | [VirusTotal](https://www.virustotal.com) | 个人资料中的 API key | 4 次/分钟, 500 次/天 | | [Shodan](https://www.shodan.io) | Account → API | 1 次/秒 (受限) | | [AlienVault OTX](https://otx.alienvault.com) | 免费账户 | 无严格限制 (无 key 也可工作) | ## 快速开始 ``` # 克隆 git clone https://github.com/xzarate/oculix.git cd oculix # 设置 API keys（可选 -- 也可通过 CLI 或交互式提示传递） export ABUSEIPDB_KEY="your_key" export VIRUSTOTAL_KEY="your_key" export SHODAN_KEY="your_key" # 交互模式 python3 oculix.py # CLI 模式 python3 oculix.py --file ips_ejemplo.txt ``` ## 使用说明 ### 交互模式 (无参数) ``` python3 oculix.py ``` 逐步引导操作：API keys → IP 输入 (支持 CIDR，例如 `203.0.113.0/28`) → 配置 → 执行。 ### CLI 模式 ``` # 单一 provider python3 oculix.py --key ABUSE_KEY --file ips.txt # 多源 cascade python3 oculix.py --key ABUSE_KEY --vt-key VT_KEY --shodan-key SH_KEY --file ips.txt # IPs 作为参数（支持 CIDR） python3 oculix.py --key ABUSE_KEY --ips 1.2.3.4 203.0.113.0/28 # JSON output + 静默模式（用于自动化） python3 oculix.py --key ABUSE_KEY --file ips.txt --json --quiet # 恢复中断的运行 python3 oculix.py --key ABUSE_KEY --file ips.txt --resume ``` 可以通过环境变量设置 API keys： ``` export ABUSEIPDB_KEY="your_key" export VIRUSTOTAL_KEY="your_key" export SHODAN_KEY="your_key" export OTX_KEY="your_key" python3 oculix.py --file ips.txt ``` ## CLI 参数 | 参数 | 默认值 | 描述 | |----------|---------|-------------| | `--key` | env `ABUSEIPDB_KEY` | AbuseIPDB API key | | `--vt-key` | env `VIRUSTOTAL_KEY` | VirusTotal API key | | `--shodan-key` | env `SHODAN_KEY` | Shodan API key | | `--otx-key` | env `OTX_KEY` | AlienVault OTX API key (可选) | | `--file` | — | 包含 IP 的文本文件 (每行一个，支持 CIDR) | | `--ips` | — | 以空格分隔的 IP 参数 | | `--days` | `90` | 历史查询范围 (天) | | `--out` | `reports/ip_report` | 输出文件前缀 | | `--delay` | `0.6` | 请求之间的延迟秒数 | | `--retries` | `3` | 网络/服务器错误时的重试次数 | | `--resume` | `false` | 继续中断的运行 | | `--json` | `false` | 同时生成 JSON 报告 | | `--quiet` | `false` | 抑制控制台输出 | | `--about` | — | 显示版本和作者信息 | ## 私有 / 保留 IP Oculix 会自动检测私有和保留 IP（RFC 1918、loopback、link-local 等）并发出警告**跳过它们**。威胁情报 API 仅对全球可路由地址返回有意义的数据。 ## 级联回退 ``` AbuseIPDB --(rate limit/error)--> VirusTotal --(rate limit/error)--> Shodan --(rate limit/error)--> AlienVault OTX ``` - 第一个成功响应的服务商胜出 - 已耗尽的服务商将在本次运行的剩余时间内被跳过 - 如果所有服务商都已耗尽，运行将停止，并可以使用 `--resume` 恢复 - 报告中的 `source` 字段指示哪个服务商响应了该 IP - 所有服务商均支持 IPv6 地址（包括 AlienVault OTX） ## 输出 报告默认写入 `reports/` 目录。 | 文件 | 内容 | |------|---------| | `reports/ip_report.csv` | 完整表格：source, score, country, ISP, categories 等。 | | `reports/ip_report.txt` | 突出显示关键 IP 的执行摘要 | | `reports/ip_report.html` | 具有可排序列的交互式 HTML 报告 | | `reports/ip_report.json` | 机器可读输出 (需使用 `--json` 标志) | ## 分数标准化 每个服务商使用自己的指标，并标准化为 0–100： | 服务商 | 原始指标 | 标准化方式 | |----------|----------------|---------------| | AbuseIPDB | `abuseConfidenceScore` (0–100) | 直接使用 | | VirusTotal | 恶意/可疑引擎数 vs 总数 | `(mal + sus×0.5) / total × 100` | | Shodan | 漏洞 + 标签 | 基于 CVE 数量和威胁标签的启发式算法 | | AlienVault OTX | Pulse 数量 | 0→0, 1–2→15, 3–5→35, 6–10→55, 11–25→75, 26+→90 | ### 判定结果 | 判定 | 分数 | |---------|-------| | `MALICIOUS` | ≥ 80 | | `SUSPICIOUS` | 25–79 | | `LOW RISK` | 1–24 | | `CLEAN` | 0 | ## 退出代码 | 代码 | 含义 | |------|---------| | `0` | 所有 IP 干净 | | `1` | 至少发现一个恶意 IP | | `2` | 所有服务商已耗尽 (使用 `--resume`) | ## 大规模工作流 对于包含 1,000+ 个 IP 的列表： **第 1 天** — 运行直到服务商耗尽： ``` python3 oculix.py --key ABUSE_KEY --vt-key VT_KEY --file large_list.txt --out reports/client_x ``` **第 2 天** — 从中断处恢复： ``` python3 oculix.py --key ABUSE_KEY --vt-key VT_KEY --file large_list.txt --out reports/client_x --resume ``` ## 仓库结构 ``` . ├── oculix.py # Main tool ├── ips_ejemplo.txt # Example IP list ├── LICENSE └── README.md ``` ## 作者 **Alexis Zarate** - GitHub: [github.com/xzarate](https://github.com/xzarate) - LinkedIn: [linkedin.com/in/alexiszarate](https://www.linkedin.com/in/alexiszarate/) ## 许可证 [MIT](LICENSE)

标签：AbuseIPDB, API集成, Ask搜索, ESC4, FTP漏洞扫描, GitHub, HTTP/HTTPS抓包, IP信誉查询, IP黑名单, OSINT, Python, SOAR, VirusTotal, 可观测性, 多功能安全工具, 威胁情报, 安全编排, 开发者工具, 态势感知, 恶意IP检测, 插件系统, 无后门, 无线安全, 深度包检测, 混合加密, 网络安全, 网络安全分析, 聊天机器人, 自动化安全工具, 自动化报告, 蓝队防御, 软件开发安全, 隐私保护, 零依赖