`intel`

Threat-intelligence lookups for IPs, domains, URLs and file hashes using VirusTotal, AbuseIPDB and URLhaus. Every lookup gives back {"source", "indicator", "verdict" ("malicious", "suspicious", "harmless" or "unknown"), "score" (0-100, higher is worse), "details", "raw"}. API keys come from the last argument or the environment variables VT_API_KEY, ABUSEIPDB_API_KEY and URLHAUS_API_KEY; TB never prints them.

This library calls threat-intelligence services over the internet, so it needs the TB app on your computer. The examples here show the code; run them with tb file.tb.

import intel

Example

Needs the TB app on your computer, so there is no Run button here.

import intel

# Keys come from the VT_API_KEY and ABUSEIPDB_API_KEY environment variables.
if not intel.has_key("virustotal") {
  say(intel.key_help())
} else {
  let r = intel.virustotal_file("44d88612fea8a8f36de82e1278abb02f")
  say(f"{r.source}: {r.verdict} (score {r.score})")
}

Functions

virustotal_file(hash, key?)

returns map

Look up a file by its MD5, SHA-1 or SHA-256 hash on VirusTotal (it never uploads the file). details has malicious/suspicious/harmless/undetected engine counts, name, type and a link. An unknown hash gives verdict "unknown". Needs VT_API_KEY.

virustotal_ip(ip, key?)

returns map

Look up an IP address on VirusTotal. details has engine counts, country, owner (the network that holds it) and a link. Needs VT_API_KEY.

virustotal_domain(domain, key?)

returns map

Look up a domain name like "example.com" on VirusTotal. details has engine counts, registrar and a link. Needs VT_API_KEY.

virustotal_url(url, key?)

returns map

Look up a web address on VirusTotal (it only reads existing reports; it doesn't submit the URL for scanning). A URL nobody has scanned yet gives verdict "unknown". Needs VT_API_KEY.

abuseipdb(ip, key?, days?)

returns map

Check an IP address on AbuseIPDB: how many people reported it for attacks in the last days (default 90). score is AbuseIPDB's confidence of abuse (0-100): 75+ is "malicious", 25+ "suspicious". details has reports, country, isp, usage, domain, whitelisted and last_reported. Needs ABUSEIPDB_API_KEY.

urlhaus_url(url, key?)

returns map

Check a web address against URLhaus, abuse.ch's list of URLs that spread malware. A listed URL is "malicious" (score 100 while online, 80 once offline); an unlisted one is "unknown" (URLhaus only knows bad URLs). details has listed, status, threat, tags and a link. abuse.ch may ask for a free Auth-Key: set URLHAUS_API_KEY (or pass it).

has_key(service)

returns bool

True if an API key for "virustotal", "abuseipdb" or "urlhaus" is set in the environment. (It never shows the key.)

key_help()

returns text

How to get and set the API keys the intel library uses (good to print when a key is missing).