checkip

README

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 Go library that provides generic and security information about IP addresses in a quick way.

$ checkip 91.228.166.47
--- 91.228.166.47 ---
db-ip.com       Petržalka, Slovakia
dns name        skh1-webredir01-v.eset.com
iptoasn.com     ESET-AS
is on AWS       false
ping            100% packet loss (5/0), avg round-trip 0 ms
shodan.io       OS: n/a, open: tcp/80 (nginx), tcp/443 (nginx), vulns: n/a
tls             TLS 1.3, exp. 2024/01/02, www.eset.com, eset.com
malicious       0% (0/7) ✅

$ checkip -j 34.250.182.30 | jq '.checks[] | select(.malicious == true)'
{
  "name": "shodan.io",
  "type": 2,
  "malicious": true,
  "info": {
    "org": "Amazon Data Services Ireland Limited",
    "data": [
      {
        "product": "lighttpd",
        "version": "1.4.53",
        "port": 80,
        "transport": "tcp"
      },
      {
        "product": "AWS ELB",
        "version": "2.0",
        "port": 443,
        "transport": "tcp"
      }
    ],
    "os": "",
    "ports": [
      80,
      443
    ],
    "vulns": [
      "CVE-2022-22707",
      "CVE-2019-11072"
    ]
  }
}

See Wiki for more usage examples.

Installation

To install the CLI tool

# optional; to install inside a container
docker run --rm -it golang /bin/bash

go install github.com/jreisinger/checkip/cmd/checkip@latest

or download a release 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 ignored.

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

ABUSEIPDB_API_KEY: aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffff11111111222222223333333344444444
MAXMIND_LICENSE_KEY: abcdef1234567890
SHODAN_API_KEY: aaaabbbbccccddddeeeeffff11112222
URLSCAN_API_KEY: abcd1234-a123-4567-678z-a2b3c4b5d6e7
VIRUSTOTAL_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 type Check.
2. Add the new check to check.All variable
3. Optional: consider adding the new check to check.Default variable.

Typical workflow:

make run # test, install and run

git commit -m "backwards compatible bug fix" main.go

git tag | sort -V | tail -1
git tag -a v0.16.1 -m "patch" # will build a new release on GitHub when pushed

git push --follow-tags

Documentation

Overview

Package checkip defines how to Check an IP address.

Example

package main

import (
	"encoding/json"
	"fmt"
	"net"

	"github.com/jreisinger/checkip"
	"github.com/jreisinger/checkip/cli"
)

// IsWellKnown implements checkip.Check.
func IsWellKnown(ipaddr net.IP) (checkip.Result, error) {
	res := checkip.Result{Name: "well known"}

	wellKnown := []net.IP{
		net.ParseIP("1.1.1.1"),
		net.ParseIP("4.4.4.4"),
		net.ParseIP("8.8.8.8"),
	}

	for _, wk := range wellKnown {
		if string(ipaddr) == string(wk) {
			res.Info = WellKnown(true)
		}
	}

	return res, nil
}

// WellKnown implements checkip.Info.
type WellKnown bool

func (wk WellKnown) Json() ([]byte, error) {
	return json.Marshal(wk)
}

func (wk WellKnown) Summary() string {
	return fmt.Sprintf("%v", wk)
}

func main() {
	ipaddr := net.ParseIP("1.1.1.1")
	results, _ := cli.Run([]checkip.Check{IsWellKnown}, ipaddr)
	results.PrintSummary()
}

Output:

well known      true

Index

• type Check
• type Info
• type Result
• type Type
  • func (t Type) String() string

Examples

• Package

Types

type Check

type Check func(ipaddr net.IP) (Result, error)

Check provides generic and/or security information about an IP address.

type Info

type Info interface {
	Summary() string       // summary info
	Json() ([]byte, error) // all info in JSON format
}

Info is generic information provided by a TypeInfo or TypeInfoSec Check.

type Result

type Result struct {
	Name      string `json:"name"`      // check name, max 15 chars
	Type      Type   `json:"type"`      // check type
	Malicious bool   `json:"malicious"` // provided by TypeSec check type
	Info      Info   `json:"info"`
}

Result is the information provided by a Check.

type Type

type Type int32

Type is the type of a Check.

const (
	TypeInfo    Type = iota // generic information about the IP address
	TypeSec                 // whether the IP address is considered malicious
	TypeInfoSec             // both of the above
)

Existing Check types.

func (Type) String

func (t Type) String() string

String returns the name of the Check type: Info, Sec or InfoSec.