ukemi

Ukemi is a CLI tool for querying passive DNS services.

It supports the following services.

• CIRCL passive DNS
• DNSDB
• OTX
• PassiveTotal
• SecurityTrails
• VirusTotal

It outputs passive DNS resolutions as JSON.

Requirements

• Ruby 2.7+ or Ruby 3.x

Installation

gem install ukemi

Configuration

Configuration is done via environment variables.

Key	Desc.
CIRCL_PASSIVE_PASSWORD	CIRCL passive DNS password
CIRCL_PASSIVE_USERNAME	CIRCL passive DNS username
DNSDB_API_KEY	DNSDB API key
OTX_API_KEY	OTX API key
PASSIVETOTAL_API_KEY	PassiveTotal API key
PASSIVETOTAL_USERNAME	PassiveTotal username
SECURITYTRAILS_API_KEY	SecurityTrails API key
VIRUSTOTAL_API_KEY	VirusTotal API key

Usage

$ ukemi
Commands:
  ukemi help [COMMAND]      # Describe available commands or one specific command
  ukemi lookup [IP|DOMAIN]  # Lookup passive DNS services

$ ukemi help lookup
Usage:
  ukemi lookup [IP|DOMAIN]

Options:
  [--order-by=ORDER_BY]  # Ordering of the passve DNS resolutions (last_seen or first_seen)
                         # Default: -last_seen

Lookup passive DNS servicess

$ ukemi lookup example.com
{
  "93.184.216.34": {
    "first_seen": "2016-03-01",
    "last_seen": "2020-03-16",
    "sources": [
      {
        "first_seen": "2016-10-07",
        "last_seen": "2018-10-30",
        "source": "CIRCL"
      },
      {
        "first_seen": "2016-03-01",
        "last_seen": "2020-03-16",
        "source": "SecurityTrails"
      },
      {
        "first_seen": "2020-03-03",
        "last_seen": "2020-03-03",
        "source": "VirusTotal"
      }
    ]
  },
  ...
}

$ ukemi lookup 195.123.226.243
{
  "example.org": {
    "first_seen": "2011-04-11",
    "last_seen": "2020-03-16",
    "sources": [
      {
        "first_seen": "2011-04-11",
        "last_seen": "2011-04-11",
        "source": "CIRCL"
      },
      {
        "first_seen": "2016-10-09",
        "last_seen": "2018-10-28",
        "source": "CIRCL"
      },
      {
        "first_seen": "2014-12-09",
        "last_seen": "2020-03-16",
        "source": "PassiveTotal"
      },
      {
        "first_seen": null,
        "last_seen": null,
        "source": "SecurityTrails"
      }
    ]
  },
  ...
}

# or you scan skip "lookup"
$ ukemi example.com
$ ukemi 195.123.226.243

# You can specify the order of resolutions

# Order by last_seen DESC
$ ukemi lookup example.com --order-by -last_seen

# Order by last_seen ASC
$ ukemi lookup example.com --order-by last_seen

# Order by first_seen DESC
$ ukemi lookup example.com --order-by -first_seen

# Order by first_seen ASC
$ ukemi lookup example.com --order-by first_seen

Using with jq

jq's powerful processor helps to interact with the output.

# List up resolutions only
$ ukemi lookup example.com | jq "keys"
[
  "192.0.32.10",
  "192.0.43.10",
  "208.77.188.166",
  "209.67.208.202",
  "221.121.159.162",
  "93.184.216.119",
  "93.184.216.34"
]

# List up the first 2 objects
$ ukemi lookup example.com  | jq "to_entries | .[:2] | from_entries"
{
  "93.184.216.34": {
    "first_seen": "2016-03-01",
    "last_seen": "2020-03-16",
    "sources": [
      {
        "first_seen": "2016-10-07",
        "last_seen": "2018-10-30",
        "source": "CIRCL"
      },
      {
        "first_seen": "2016-03-01",
        "last_seen": "2020-03-16",
        "source": "SecurityTrails"
      },
      {
        "first_seen": "2020-03-03",
        "last_seen": "2020-03-03",
        "source": "VirusTotal"
      }
    ]
  },
  "221.121.159.162": {
    "first_seen": "2019-11-04",
    "last_seen": "2019-11-04",
    "sources": [
      {
        "first_seen": "2019-11-04",
        "last_seen": "2019-11-04",
        "source": "VirusTotal"
      }
    ]
  }
}

License

The gem is available as open source under the terms of the MIT License.