opentip-cli

Python library and CLI for the Kaspersky OpenTIP (Threat Intelligence Portal) API

Overview

opentip-cli is a Python library and command-line client for the Kaspersky OpenTIP API. It covers every public API endpoint: hash, IP, domain, and URL lookups, file submission to the Sandbox, and full analysis report retrieval.

Endpoints

Installation

From PyPI (Recommended)

pip install opentip-cli

From Source

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

Request a token in the OpenTIP web interface, then provide it in one of these ways (checked in this order):

1. --api-key CLI flag or the api_key argument of OpenTipClient.
2. OPENTIP_API_KEY environment variable.
3. Config file at ~/.config/opentip/config.ini (override with --config):

[opentip]
api_key = <your token>

Security notes:

• Restrict the config file to your user (chmod 600 ~/.config/opentip/config.ini on Linux/macOS).
• Prefer the environment variable or the config file over --api-key: command-line arguments are visible to other local processes and end up in your shell history.

Quick Start

# Look up a file hash
opentip hash 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f

# Look up an IP address
opentip ip 8.8.8.8

# Submit a file to the Sandbox
opentip scan ./sample.bin

# Choose the output format (default: table)
opentip --format json ip 8.8.8.8
opentip --format toon ip 8.8.8.8
opentip --format sarif hash 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f

Usage

Command Line Interface

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

By default results are printed as a readable table; use --format for machine-readable output. On API errors the command prints the reason to stderr and exits with code 1.

+---------------------------+----------------------+
| Field                     | Value                |
+---------------------------+----------------------+
| Zone                      | Green                |
| IpGeneralInfo.Status      | known                |
| IpGeneralInfo.CountryCode | US                   |
| IpGeneralInfo.FirstSeen   | 2014-06-07T18:51:00Z |
+---------------------------+----------------------+

Note: the URL endpoint requires a web address with a path (for example example.com/index.html); the API answers 400 Bad Request for bare hosts — use the domain command for those.

Available Commands

Global Options

Output Formats

Python Library

Basic Usage

from opentip import OpenTipClient

client = OpenTipClient()  # token from env var or config file
verdict = client.lookup_hash(
    "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
)
print(verdict["Zone"])

File Submission and Reports

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"])

Error Handling

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}")

All methods return the API response as a dict and raise opentip.OpenTipError (with status_code) on failure.

Output Formatters

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

Requirements

• Python 3.14+
• All dependencies (runtime and development) live in requirements.txt

Development

python3.14 -m venv venv
venv/bin/pip install -r requirements.txt

Quality and security gates (all must pass with zero findings):

black --check .
ruff check .
mypy .
bandit -c pyproject.toml -r .
pip-audit

Tests run against the real API (no mocks) and require OPENTIP_API_KEY to be set. Coverage below 100% fails the run:

OPENTIP_API_KEY=<your token> venv/bin/pytest

Contributing

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support the Project

If this project is useful in your workflows, you can support development:

License

This project is licensed under the MIT license. See LICENSE.

Attribution

• Author: Marc Rivero López | @seifreed
• Repository: github.com/seifreed/OpenTip

_{Built for practical threat intelligence lookups and security automation}