opentip-cli

用于 Kaspersky OpenTIP (Threat Intelligence Portal) API 的 Python 库和 CLI

## 概述 **opentip-cli** 是一个用于 [Kaspersky OpenTIP API](https://opentip.kaspersky.com/Help/Doc_data/WorkingWithAPI.htm) 的 Python 库和命令行客户端。它涵盖了所有的公开 API endpoint：hash、IP、domain 和 URL 查询，向 Sandbox 提交文件，以及获取完整的分析报告。 ### Endpoints | Endpoint | 库方法 | CLI 命令 | |----------|----------------|-------------| | `GET /search/hash` | `lookup_hash` | `opentip hash ` | | `GET /search/ip` | `lookup_ip` | `opentip ip

` | | `GET /search/domain` | `lookup_domain` | `opentip domain ` | | `GET /search/url` | `lookup_url` | `opentip url

` | | `POST /scan/file` | `scan_file` | `opentip scan ` | | `POST /getresult/file` | `get_file_report` | `opentip report ` | ## 安装说明 ### 从 PyPI 安装（推荐） ``` pip install opentip-cli ``` ### 从源码安装 ``` git clone https://github.com/seifreed/OpenTip.git cd OpenTip python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install . ``` ## API Token 在 [OpenTIP Web 界面](https://opentip.kaspersky.com/)中申请一个 token，然后通过以下方式之一提供（按以下顺序进行检查）： 1. `--api-key` CLI 标志或 `OpenTipClient` 的 `api_key` 参数。 2. `OPENTIP_API_KEY` 环境变量。 3. 位于 `~/.config/opentip/config.ini` 的配置文件（使用 `--config` 覆盖）： ``` [opentip] api_key = ``` 安全提示： - 将配置文件的权限限制为仅限您的用户使用（在 Linux/macOS 上使用 `chmod 600 ~/.config/opentip/config.ini`）。 - 相比于 `--api-key`，优先使用环境变量或配置文件：命令行参数对其他本地进程可见，并且会被记录在您的 shell 历史记录中。 ## 快速入门 ``` # 查找文件 hash opentip hash 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f # 查找 IP 地址 opentip ip 8.8.8.8 # 提交文件到 Sandbox opentip scan ./sample.bin # 选择输出格式（默认：table） opentip --format json ip 8.8.8.8 opentip --format toon ip 8.8.8.8 opentip --format sarif hash 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f ``` ## 用法 ### 命令行界面 ``` opentip hash 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f opentip ip 8.8.8.8 opentip domain example.com opentip url https://example.com/index.html opentip scan ./sample.bin --filename sample.bin opentip report 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f ``` 默认情况下，结果将以易读的表格形式打印；使用 `--format` 获取机器可读的输出。发生 API 错误时，命令会将原因打印到 stderr 并以退出码 1 退出。 ``` +---------------------------+----------------------+ | Field | Value | +---------------------------+----------------------+ | Zone | Green | | IpGeneralInfo.Status | known | | IpGeneralInfo.CountryCode | US | | IpGeneralInfo.FirstSeen | 2014-06-07T18:51:00Z | +---------------------------+----------------------+ ``` 注意：URL endpoint 需要带有路径的 Web 地址（例如 `example.com/index.html`）；API 对纯粹的主机名会返回 `400 Bad Request` —— 对于这类情况请使用 `domain` 命令。 ### 可用命令 | 命令 | 描述 | |---------|-------------| | `opentip hash` | 查询文件的 MD5、SHA1 或 SHA256 hash | | `opentip ip` | 查询 IP 地址 | | `opentip domain` | 查询 domain | | `opentip url` | 查询 Web 地址 | | `opentip scan` | 提交文件以进行 Sandbox 分析（使用 `--filename` 覆盖名称） | | `opentip report` | 获取先前提交的 hash 的完整分析报告 | ### 全局选项 | 选项 | 描述 | |--------|-------------| | `--api-key ` | API token（默认为 `OPENTIP_API_KEY` 或配置文件） | | `--config ` | 包含 `[opentip]` 部分下 `api_key` 的配置文件路径 | | `--format ` | 输出格式：`table`（默认）、`json`、`toon` 或 `sarif` | ### 输出格式 | 格式 | 描述 | |--------|-------------| | `table` | 带有扁平化字段的 Prettytable 风格 ASCII 表格（默认） | | `json` | 格式化打印的 JSON，原始 API 响应 | | `toon` | [TOON (Token-Oriented Object Notation)](https://github.com/toon-format/toon) — 紧凑、节省 token 的输出，专为 LLM pipeline 设计 | | `sarif` | [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/) 日志，其中判定结果映射到结果级别（`Red` → `error`，`Orange`/`Yellow` → `warning`，`Green`/`Grey` → `note`），并且完整的 API 响应会嵌入到结果属性中 | ## Python 库 ### 基本用法 ``` from opentip import OpenTipClient client = OpenTipClient() # token from env var or config file verdict = client.lookup_hash( "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f" ) print(verdict["Zone"]) ``` ### 文件提交与报告 ``` from opentip import OpenTipClient client = OpenTipClient() report = client.scan_file("sample.bin") full_report = client.get_file_report(report["FileGeneralInfo"]["Sha256"]) print(full_report["Status"]) ``` ### 错误处理 ``` from opentip import MissingApiKeyError, OpenTipClient, OpenTipError try: client = OpenTipClient() result = client.lookup_domain("example.com") except MissingApiKeyError as error: print(f"No token configured: {error}") except OpenTipError as error: print(f"API error {error.status_code}: {error}") ``` 所有方法都会将 API 响应作为 `dict` 返回，并在失败时引发 `opentip.OpenTipError`（包含 `status_code`）。 ### 输出格式化器 ``` from opentip import OpenTipClient, to_json, to_sarif, to_table, to_toon client = OpenTipClient() result = client.lookup_ip("8.8.8.8") print(to_table(result)) # prettytable-style ASCII table print(to_json(result)) # pretty-printed JSON print(to_toon(result)) # TOON, token-efficient for LLM prompts print(to_sarif(result, "ip", "8.8.8.8")) # SARIF 2.1.0 log ``` ## 环境要求 - Python 3.14+ - 所有依赖项（运行时和开发环境）均位于 [requirements.txt](requirements.txt) 中 ## 开发说明 ``` python3.14 -m venv venv venv/bin/pip install -r requirements.txt ``` 质量和安全门禁（全部必须以零发现通过）： ``` black --check . ruff check . mypy . bandit -c pyproject.toml -r . pip-audit ``` 测试在真实 API 环境下运行（不使用 mock），并且需要设置 `OPENTIP_API_KEY`。覆盖率低于 100% 将导致运行失败： ``` OPENTIP_API_KEY= venv/bin/pytest ``` ## 许可证 本项目采用 MIT 许可证授权。详情请见 [LICENSE](LICENSE)。 **署名信息** - 作者：**Marc Rivero López** | [@seifreed](https://github.com/seifreed) - 代码仓库：[github.com/seifreed/OpenTip](https://github.com/seifreed/OpenTip)

_{专为实用的威胁情报查询和安全自动化而构建}

标签：API客户端, DAST, Python, 卡巴斯基, 威胁情报, 开发者工具, 恶意软件分析, 文档结构分析, 无后门, 逆向工具