Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 717 Commits
.github/workflows		.github/workflows
check		check
cli		cli
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.goreleaser.yml		.goreleaser.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
checkip.go		checkip.go
go.mod		go.mod
go.sum		go.sum
randip		randip

Repository files navigation

checkip

Sometimes I come across an IP address, reviewing logs for example, and I want to know more about this numerical label. Checkip is CLI tool and Golibrary that provides (security) information on IP addresses. It runs various checks to get the information. Most checks are passive, i.e. not interacting directly with the IP address. Active checks, like ping and tls, are not aggressive.

Quick start

$ go install github.com/jreisinger/checkip@latest$ checkip 1.1.1.1 91.228.166.47--- 1.1.1.1 ---db-ip.com       Sydney, Australiadns name        one.one.one.oneiptoasn.com     CLOUDFLARENETis on AWS       falseisc.sans.edu    attacks: 0, abuse contact: abuse@cloudflare.comping            0% packet loss (5/5), avg round-trip 4 mstls             TLS 1.3, exp. 2026/01/21, cloudflare-dns.com, *.cloudflare-dns.com, one.one.one.onevirustotal.com  network: 1.1.1.0/24, SAN: cloudflare-dns.com, *.cloudflare-dns.com, one.one.one.one, 1.0.0.1, 1.1.1.1, 162.159.36.1, 162.159.46.1, 2606:4700:4700::1001, 2606:4700:4700::1111, 2606:4700:4700::64, 2606:4700:4700::6400malicious prob. 0% (0/12) ✅--- 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            0% packet loss (5/5), avg round-trip 5 mstls             TLS 1.3, exp. 2024/01/02!!, www.eset.com, eset.comvirustotal.com  network: 91.228.164.0/22, SAN: www.eset.com, eset.commalicious prob. 17% (2/12) 🤏

More usage examples

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)'

Check multiple IP addresses coming from STDIN:

dig +short eset.sk | checkip

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

while true; do ./randip; sleep 2; done | checkip 2> /dev/null

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'

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

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 and cache

For some checks to start working you need to sign up on a web site (likehttps://www.abuseipdb.com) and get an API (or LICENSE) key. Checkip doesn't report an absent API key as an error; the check is simply not executed andmissingCredentials JSON field is set to the name of the API key (likeABUSEIPDB_API_KEY).

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 is downloaded (cached) to$HOME/.checkip/ folder. Is gets periodically re-downloaded so it is fresh.

Development

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

Write a function of typecheck.Func.
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