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:
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:
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
|
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.
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
|
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.
