IPScout is a command line tool for network administrators and security analysts to quickly identify the origin and threat of an IP address.
IPScout supports multiple well known sources. You can also provide custom sources with the Annotated and IPURL providers.
Provider data and search results can be cached to reduce API calls and improve performance.
| Provider | Category | Notes |
|---|---|---|
| AbuseIPDB | IP Reputation | Registration required |
| Annotated | User Provided | - |
| Apple iCloud Private Relay | Anonymiser | - |
| AWS | Hosting Provider | - |
| Azure | Hosting Provider | - |
| CriminalIP | IP Reputation | Registration required |
| DigitalOcean | Hosting Provider | - |
| GCP | Hosting Provider | - |
| Googlebot | Web crawler | - |
| IPAPI | IP Geolocation | - |
| IPURL | User Provided | - |
| Linode | Hosting Provider | - |
| PTR | DNS | - |
| Shodan | IP Reputation | Registration required |
| VirusTotal | IP Reputation | Registration required |
Binaries for macOS, Linux and Windows are available on the releases page.
$ brew tap jonhadfield/ipscout
$ brew install ipscout
Download the latest release from the releases page.
$ ipscout <ip address>A default configuration is created
on first run and located at: $HOME/.config/ipscout/config.yaml.
Some configuration can be overridden on the command line, see ipscout --help.
---
global:
indent_spaces: 2 # number of spaces to indent output
max_value_chars: 300 # limit the number of characters output in results
max_age: 90d # maximum age of reports to consider
max_reports: 5 # maximum number of reports to display
output: table # output format: table or json
ports: [ ] # filter results by port [tcp,udp,443/tcp,...]
providers:
# list of providers with their configurations below...Providers are configured in the config.yaml file.
A number of providers are enabled by default, but can be disabled by setting enabled: false.
This provider queries the AbuseIPDB API for information on an IP address, with a threat confidence score, and any reports filed for them. A free plan exists for individuals, with a limit of 1000 requests per day.
Environment variable ABUSEIPDB_API_KEY must be set with your API key.
providers:
abuseipdb:
enabled: falseThe Annotated provider parses one or more user provided files containing prefixes and accomanying annotations.
---
- prefixes: [ "20.20.20.0/24", "20.20.21.0/24" ]
annotations:
- date: 2024/04/19 18:58
author: john doe <john.doe@example.com>
notes:
- My First Annotation
- My Second Annotation
- prefixes: [ "9.9.9.9/32" ]
annotations:
- date: 2024/04/19 19:00
author: jane doe <jane.does@example.com>
notes:
- Another AnnotationA list of files can be specified in the provider's paths section:
providers:
annotated:
enabled: false
paths:
- /path/to/file.yamlAWS is a Hosting Provider that publishes network prefixes used by their services.
Azure is a hosting provider that publishes network prefixes used by their services.
Query the CriminalIP API for information on an IP address/endpoint, with risk ratings, and any abuse reports filed for them. A free plan exists with a small number of free credits.
Environment variable CRIMINAL_IP_API_KEY must be set with your API key.
DigitalOcean is a hosting provider that publishes network prefixes used by their services.
GCP is a hosting provider that publishes network prefixes used by their services.
Google provides a list of IP addresses used by customers of their services and publishes them here.
Googlebot is a web crawler and publishes network prefixes used by their bots.
iCloud Private Relay is an anonymising service provided by Apple. They publish their network prefixes here.
Query the ipapi API for geolocation data. The API is free for up 30,000 requests per day.
IPURL retrieves lists of IP prefixes from user provided URLs and checks the target IP address against them. Documents are expected to contain a list of prefixes in CIDR format, one per line.
Example configuration:
ipurl:
enabled: true
urls:
- "https://iplists.firehol.org/files/firehol_level1.netset"
- "https://iplists.firehol.org/files/firehol_level2.netset"
- "https://iplists.firehol.org/files/blocklist_de.ipset"A match for target IP 3.68.116.6 in two of the above may return:
Prefixes
3.68.116.0/28
|----- https://iplists.firehol.org/files/firehol_level2.netset
|----- https://iplists.firehol.org/files/blocklist_de.ipset
Linode is a hosting provider that publishes network prefixes used by their services.
The PTR provider does a reverse lookup for the target IP.
See:
- https://en.wikipedia.org/wiki/Reverse_DNS_lookup
- https://www.cloudflare.com/en-gb/learning/dns/dns-records/dns-ptr-record/
Custom nameservers can be specified in the config.yaml file with port defaulting to 53 if not specified.
ptr:
enabled: true
nameservers:
- 1.1.1.1:53
- 8.8.8.8
- 8.8.4.4:53Query the Shodan API for information on an IP address, with open ports, and services.
Set environment variable SHODAN_API_KEY with your API key.
Query the VirusTotal API for information from various providers on an IP address.
Set environment variable VIRUSTOTAL_API_KEY with your API key.