Project

ukemi

0.01
No release in over 3 years
Low commit activity in last 3 years
A CLI tool for querying passive DNS services
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

~> 2.2
~> 13.0
~> 6.0
~> 0.58
~> 3.10
~> 1.1
~> 3.14

Runtime

 Project Readme

ukemi

Gem Version Ruby CI Coverage Status CodeFactor

Ukemi is a CLI tool for querying passive DNS services.

It supports the following services.

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.