https://github.com/ninoseki/ukemi
A CLI tool for querying passive DNS services
https://github.com/ninoseki/ukemi
passive-dns
Last synced: about 2 months ago
JSON representation
A CLI tool for querying passive DNS services
- Host: GitHub
- URL: https://github.com/ninoseki/ukemi
- Owner: ninoseki
- License: mit
- Created: 2020-03-14T08:31:47.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-12-15T02:18:39.000Z (almost 2 years ago)
- Last Synced: 2024-04-26T03:45:13.115Z (over 1 year ago)
- Topics: passive-dns
- Language: Ruby
- Homepage:
- Size: 49.8 KB
- Stars: 41
- Watchers: 3
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ukemi
[](https://badge.fury.io/rb/ukemi)
[](https://github.com/ninoseki/ukemi/actions/workflows/test.yaml)
[](https://coveralls.io/github/ninoseki/ukemi?branch=master)
[](https://www.codefactor.io/repository/github/ninoseki/ukemi)
Ukemi is a CLI tool for querying passive DNS services.
It supports the following services.
- [CIRCL passive DNS](https://www.circl.lu/services/passive-dns/)
- [DNSDB](https://api.dnsdb.info/)
- [OTX](https://otx.alienvault.com)
- [PassiveTotal](https://community.riskiq.com/)
- [SecurityTrails](https://securitytrails.com/)
- [VirusTotal](http://virustotal.com)
It outputs passive DNS resolutions as JSON.
## Requirements
- Ruby 2.7+ or Ruby 3.x
## Installation
```bash
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
```bash
$ 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
```
```bash
$ 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](https://stedolan.github.io/jq/)'s powerful processor helps to interact with the output.
```bash
# 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](https://opensource.org/licenses/MIT).