checkip

Sometimes I come across an IP address, for example when reviewing logs. And I'd like to find out more about this numerical label. Checkip is CLI tool and Golibrary that provides information on and security posture of IP addresses. Most checks are passive. Active checks (like ping and tls) are not aggressive.

Quick start

go install github.com/jreisinger/checkip@latestcheckip 1.1.1.1

Usage examples

Check an IP address:

❯ checkip 91.228.166.47--- 91.228.166.47 ---db-ip.com       Petržalka, Slovakiadns name        skh1-webredir01-v.eset.comiptoasn.com     ESET-ASis on AWS       falseisc.sans.edu    attacks: 0, abuse contact: domains@eset.skping            100% packet loss (5/0), avg round-trip 0 mstls             TLS 1.3, exp. 2024/01/02!!, www.eset.com, eset.commalicious prob. 8% (1/12) ✅

Check multiple IP addresses coming from STDIN:

❯ dig +short eset.sk | checkip--- 91.228.167.128 ---db-ip.com       Petržalka, Slovakiadns name        h3-webredir02-v.eset.comiptoasn.com     ESET-ASis on AWS       falseisc.sans.edu    attacks: 0, abuse contact: domains@eset.skping            100% packet loss (5/0), avg round-trip 0 mstls             TLS 1.3, exp. 2024/01/02!!, www.eset.com, eset.commalicious prob. 9% (1/11) ✅--- 91.228.166.47 ---db-ip.com       Petržalka, Slovakiadns name        skh1-webredir01-v.eset.comiptoasn.com     ESET-ASis on AWS       falseisc.sans.edu    attacks: 0, abuse contact: domains@eset.skping            100% packet loss (5/0), avg round-trip 0 mstls             TLS 1.3, exp. 2024/01/02!!, www.eset.com, eset.commalicious prob. 8% (1/12) ✅

Use detailed JSON output to filter out those checks that consider the IP address to be malicious:

❯ checkip -j 91.228.166.47 | jq '.checks[] | select(.ipAddrIsMalicious == true)'{  "description": "tls",  "type": "InfoAndIsMalicious",  "ipAddrIsMalicious": true,  "ipAddrInfo": {    "SAN": [      "www.eset.com",      "eset.com"    ],    "Version": 772,    "Expiry": "2024-01-02T23:59:59Z"  }}

Continuously generaterandom IP addresses and check them (hit Ctrl-C to stop):

❯ while true; do ./randip; sleep 2; done | checkip 2> /dev/null--- 155.186.85.125 ---db-ip.com       Ashburn, United Statesdns name        syn-155-186-085-125.res.spectrum.comiptoasn.com     CHARTER-20115is on AWS       falseisc.sans.edu    attacks: 0, abuse contact: abuse@charter.netping            100% packet loss (5/0), avg round-trip 0 msmalicious prob. 0% (0/10) ✅--- 115.159.53.216 ---db-ip.com       Shenzhen (Futian Qu), Chinaiptoasn.com     TENCENT-NET-AP Shenzhen Tencent Computer Systems Company Limitedis on AWS       falseisc.sans.edu    attacks: 0, abuse contact: ipas@cnnic.cnping            100% packet loss (5/0), avg round-trip 0 msmalicious prob. 0% (0/10) ✅

Generate 100 random IP addresses and select Russian or Chinese:

❯ ./randip 100 | checkip -p 20 -j 2> /dev/null | \jq -r '.ipAddr as $ip | .checks[] | select (.description == "db-ip.com" and (.ipAddrInfo.iso_code == "RU" or .ipAddrInfo.iso_code == "CN")) | $ip'218.19.226.129119.32.13.38139.210.45.205

Find out who is trying to SSH into your Linux system:

❯ sudo journalctl --unit ssh --since "1 hour ago" | \grep 'Bye Bye' | perl -wlne '/from ([\d\.]+)/ && print $1' | sort | uniq | \checkip 2> /dev/null--- 167.172.105.64 ---db-ip.com       Frankfurt am Main, Germanyiptoasn.com     DIGITALOCEAN-ASNping            0% packet loss (5/5), avg round-trip 21 mstls             TLS 1.3, exp. 2024/12/27, portal.itruck.com.sa, www.portal.itruck.com.samalicious prob. 43% (3/7) 🤏--- 180.168.95.234 ---db-ip.com       Shanghai, Chinaiptoasn.com     CHINANET-SH-AP China Telecom Groupping            0% packet loss (5/5), avg round-trip 213 msmalicious prob. 50% (3/6) 🚫

Installation

To install the CLI tool

# optional; to install inside a containerdocker run --rm -it golang /bin/bashgo install github.com/jreisinger/checkip@latest

or download arelease binary (from under "Assets") for your system and architecture.

Configuration

For some checks to start working you need to register and get an API (LICENSE) key. See the service web site for how to do that. An absent key is not reported as an error, the check is simply not executed andmissingCredentials JSON field is set.

Store the keys in$HOME/.checkip.yaml file:

ABUSEIPDB_API_KEY: aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffff11111111222222223333333344444444MAXMIND_LICENSE_KEY: abcdef1234567890SHODAN_API_KEY: aaaabbbbccccddddeeeeffff11112222URLSCAN_API_KEY: abcd1234-a123-4567-678z-a2b3c4b5d6e7VIRUSTOTAL_API_KEY: aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffff1111111122222222

You can also use environment variables with the same names.

Data used by some checks are downloaded (cached) to$HOME/.checkip/ folder. They are periodically re-downloaded so they are fresh.

Development

Checkip is easy to extend. If you want to add a new way of checking IP addresses:

1. Write a function of typecheck.Func.
2. Add it tocheck.Funcs variable.

Typical workflow:

make run # test and rungit commitgit tag | sort -V | tail -1git tag -a v0.2.0 -m "new check func"git push --follow-tags # will build a new release on GitHub