OpenTIP, command line edition

For more than a year, we have been providing free intelligence services via the OpenTIP portal. Using the web interface, anyone can upload and scan files with our antivirus engine, get a basic sandbox report, look up various network indicators (IP addresses, hosts, URLs). Later on, we presented an easy-to-use HTTPS-based programming interface, so that you could use the service in your own scripts and integrate it in existing workflow.

OpenTIP web interface – upload, look up, get results!

Of course, it is much easier to use the API when there is a set of working examples. It is also more convenient to integrate with existing tools and scripts when you have a command line utility that interacts with the service. We decided have both in one package, by releasing Python-based command line tools for the service that also implement a client class that you can reuse in your own tools.

A few words about privacy

The OpenTIP service has its own Terms of Use, End-User Agreement and a Privacy Policy; and the command line tools can only be accessed with an API token, that in turn can be only obtained after agreeing to all the terms. Please read them carefully. By default, the “opentip” scanner may upload the files being checked if their hashes are not yet known to the service, so please ensure that you are familiar with the policies. And, of course, the sample upload can be turned off.

Setting things up

The command line tools need the “apikey”, that is, a usual web API access token. You can generate it at this page (you may be required to register or log in into the web version of the service). The key can then be permanently set up as an environment variable “OPENTIP_APIKEY” or provided as a command line option “–apikey VALUE_OF_THE_KEY”. By default, the API key has certain rate limitations that may be changed in future, so please contact us if your scripts hit the rate limits.

The tools and the Python 3 client class can be all installed from pip:

pip3 install opentip

The code is also published on Github, so you can easily inspect and package it yourself. At the time of writing, the package has no external dependencies and should run on any modern Python 3 distribution.

Once installed, Python will also generate two executables (scripts, or binary wrappers, depending on the platform), named “opentip” and “check_iocs”.

The OpenTIP Scanner

The scanner is named “opentip” (or “opentip.exe”), as is the primary tool for quickly checking files and directories. The standard usage banner is pretty simple and self-descriptive:

usage: opentip [-h] [--no-upload] [--exclude EXCLUDE] [--log LOG] [--apikey APIKEY] [--quiet] path [path ...]

Check files and directories with OpenTIP.kaspersky.com, optionally upload and scan unknown files

positional arguments:
  path               File or directory location to scan

optional arguments:
  -h, --help         show this help message and exit
  --no-upload        DO NOT upload unknown files to scan with the Sandbox, default behaviour is to upload
  --exclude EXCLUDE  Do not scan or upload the files matching the pattern
  --log LOG          Write results to the log file
  --apikey APIKEY    OpenTIP API key, received from https://opentip.kaspersky.com/token
  --quiet            Do not log clean files

The easiest and most basic mode of operation is to provide the location of the files or directories to scan. Directories are processed recursively, and unknown files are uploaded for checking by default (subject to the privacy policy, use “–no-upload” to change default behavior). The results are printed on stdout, and can also be redirected to a log file. The “–exclude” option allows you to disable the checks for any path locations, and with the “–quiet” option the script will print out only the positive detections.

$ opentip .
2022-08-01 16:23:22,638 ./package/main.py: Malware: Trojan.Python.Lofy.a
2022-08-01 16:23:22,766 ./package/package.json: NotCategorized
2022-08-01 16:23:22,965 ./package/index.js: NoThreats

Typical output of the scanner

Since the package has no external dependencies, it can be used to quickly deploy the scanner and check a fleet of remote machines, and the OPENTIP_APIKEY environment variable makes it easier to use the scanner in containers.

The IOC checker script

The second tool, named “check_iocs”, has a different purpose: you can use it to quickly query the OpenTIP service for file hashes, domains, IPs and URLs.

usage: check_iocs [-h] [--apikey APIKEY] [--out OUT] type value

Check IOCS (file hashes, IP addresses, domain names, URLs using the service OpenTIP.kaspersky.com

positional arguments:
  type               hash, ip, domain, url
  value              Value of the IOC (hash, ip, domain, url, filename with the iocs)

optional arguments:
  -h, --help         show this help message and exit
  --apikey APIKEY    OpenTIP API key, received from https://opentip.kaspersky.com/token
  --out OUT, -o OUT  Write output as JSON to this filename

The script requires two arguments: the type of the input data (“hash”, “ip”, “domain”, “url”, “filename”) and either the actual value of the data to check, or the path of the filename that contains the list of values, one per line.

$check_iocs hash list_of_md5.txt 
[IOC]: d41d8cd98f00b204e9800998ecf8427e : Unknown
[IOC]: 46c5070ed139ca8121c07eda20587e3f : {'Zone': 'Grey', 'FileGeneralInfo': {'FileStatus': 'NotCategorized', 'Sha1': '24F7BAF656DCAC1FF43E4479AD8A5F4DF8052900', 'Md5': '46C5070ED139CA8121C07EDA20587E3F', 'Sha256': '04FC2B072775EA05AB6C9E117EFBFD1C56D2F1B45D1AC175001A186452269F3C', 'FirstSeen': '1970-01-01T00:00:00Z', 'LastSeen': '1970-01-01T00:00:00Z', 'Size': 464, 'Type': 'text'}, 'DynamicAnalysisResults': {'Detections': [{'Zone': 'Red'}, {'Zone': 'Yellow'}], 'SuspiciousActivities': [{'Zone': 'Red'}, {'Zone': 'Yellow'}, {'Zone': 'Grey'}], 'NetworkActivities': [{'Zone': 'Red'}, {'Zone': 'Yellow'}, {'Zone': 'Green'}, {'Zone': 'Grey'}]}}
[IOC]: 0067bc5d4d92fe9445e41f347944196e : {'Zone': 'Red', 'FileGeneralInfo': {'FileStatus': 'Malware', 'Sha1': 'F666104C83CB18F2ED345A11C34EE9A32CD2ABC1', 'Md5': '0067BC5D4D92FE9445E41F347944196E', 'Sha256': '8B615582D92D42FEEFCEEBA03E65D16773F2B227ED1CD17C82462641A9D249D9', 'FirstSeen': '2022-07-27T11:48:00Z', 'LastSeen': '2022-07-30T12:44:00Z', 'Size': 10466, 'Type': 'Txt', 'HitsCount': 10}, 'DetectionsInfo': [{'LastDetectDate': '2022-07-30T12:50:35.887Z', 'Zone': 'Red', 'DetectionName': 'Trojan.Python.Lofy.a'}], 'DynamicAnalysisResults': {'Detections': [{'Zone': 'Red'}, {'Zone': 'Yellow'}], 'SuspiciousActivities': [{'Zone': 'Red'}, {'Zone': 'Yellow'}, {'Zone': 'Grey'}], 'NetworkActivities': [{'Zone': 'Red'}, {'Zone': 'Yellow'}, {'Zone': 'Green'}, {'Zone': 'Grey'}]}}
[IOC]: e1dc5ff6a1febdd4db11901fc295364f : {'Zone': 'Green', 'FileGeneralInfo': {'FileStatus': 'NoThreats', 'Sha1': '49217E09D0C33FF3C958AFBDCB60F977E10104E0', 'Md5': 'E1DC5FF6A1FEBDD4DB11901FC295364F', 'Sha256': 'EAB0020A475BB1CF70CA5C9569DEFE5F1A7160A9D334144DA47924418EE2C9E7', 'FirstSeen': '2022-07-30T10:03:00Z', 'LastSeen': '2022-07-30T10:20:00Z', 'Size': 34768, 'Type': 'Js', 'HitsCount': 10}, 'DynamicAnalysisResults': {'Detections': [{'Zone': 'Red'}, {'Zone': 'Yellow'}], 'SuspiciousActivities': [{'Zone': 'Red'}, {'Zone': 'Yellow'}, {'Zone': 'Grey'}], 'NetworkActivities': [{'Zone': 'Red'}, {'Zone': 'Yellow'}, {'Zone': 'Green'}, {'Zone': 'Grey'}]}}

Typical output of the check_iocs tool

The output is much more comprehensive than the one provided by the scanner and is JSON-encoded, so that it can be parsed automatically.

The Python API class

Both command line tools are actually using a single Python class to access the OpenTIP service, and you can use the source code of the tools as a reference for your own scripts.

The OpenTIP client can be easily instantiated with a few lines:

from opentip.client import OpenTIP
client = OpenTIP(APIKEY)

To query the OpenTIP for a known indicator, use a single call:

client.get_verdict_by_ioc(ioc_type, ioc)

For example:

>>> client.get_verdict_by_ioc('hash', '0067bc5d4d92fe9445e41f347944196e')
'{"Zone":"Red","FileGeneralInfo":{"FileStatus":"Malware","Sha1":"F666104C83CB18F2ED345A11C34EE9A32CD2ABC1","Md5":"0067BC5D4D92FE9445E41F347944196E","Sha256":"8B615582D92D42FEEFCEEBA03E65D16773F2B227ED1CD17C82462641A9D249D9","FirstSeen":"2022-07-27T11:48:00Z","LastSeen":"2022-07-30T12:44:00Z","Size":10466,"Type":"Txt","HitsCount":10},"DetectionsInfo":[{"LastDetectDate":"2022-07-30T12:50:35.887Z","Zone":"Red","DetectionName":"Trojan.Python.Lofy.a"}],"DynamicAnalysisResults":{"Detections":[{"Zone":"Red"},{"Zone":"Yellow"}],"SuspiciousActivities":[{"Zone":"Red"},{"Zone":"Yellow"},{"Zone":"Grey"}],"NetworkActivities":[{"Zone":"Red"},{"Zone":"Yellow"},{"Zone":"Green"},{"Zone":"Grey"}]}}'

To scan a file (with upload turned on by default), returning a tuple of (filename, results), call:

client.scan_file(filename)

Example:

>>> client.scan_file('package/main.py')
('package/main.py', '{"Zone":"Red","FileGeneralInfo":{"FileStatus":"Malware","Sha1":"F666104C83CB18F2ED345A11C34EE9A32CD2ABC1","Md5":"0067BC5D4D92FE9445E41F347944196E","Sha256":"8B615582D92D42FEEFCEEBA03E65D16773F2B227ED1CD17C82462641A9D249D9","FirstSeen":"2022-07-27T11:48:00Z","LastSeen":"2022-07-30T12:44:00Z","Size":10466,"Type":"Txt","HitsCount":10},"DetectionsInfo":[{"LastDetectDate":"2022-07-30T12:50:35.887Z","Zone":"Red","DetectionName":"Trojan.Python.Lofy.a"}],"DynamicAnalysisResults":{"Detections":[{"Zone":"Red"},{"Zone":"Yellow"}],"SuspiciousActivities":[{"Zone":"Red"},{"Zone":"Yellow"},{"Zone":"Grey"}],"NetworkActivities":[{"Zone":"Red"},{"Zone":"Yellow"},{"Zone":"Green"},{"Zone":"Grey"}]}}')

To disable file upload for unknown files, instantiate the OpenTIP with no_upload=True.

>>> client = OpenTIP(OPENTIP_APIKEY, no_upload=True)
>>> client.no_upload
True

Any ideas are welcome

This is just the beginning, and we welcome any kind of input, pull requests and feature requests to make the service more convenient. If you have any issues or questions regarding the scripts, please contact us by creating a Github issue or using the OpenTIP contact form.