README
¶
IPScout
IPScout is a command-line tool for security analysts to enrich IP addresses with their origin and threat ratings. All of the host reputation providers require registration but each of them offers a free tier.
Table of Contents
Features
- Query multiple reputation and hosting providers concurrently
- Cache provider metadata and lookup results
- Manage cached data with
ipscout cache - Show or output configuration with
ipscout config - Rate hosts using
ipscout rate, optionally with AI assistance - Supports Zscaler IP range lookups
Output
format
Results are displayed in a table by default but can also be outputted as JSON format using the --output flag.
style
Table styles include ascii (for basic terminals), cyan, red, yellow, green, blue, and can be specified in the config.yaml file or with the --style flag.
Examples:
Providers
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 |
| Alibaba Cloud | Hosting Provider | - |
| Annotated | User Provided | - |
| Apple iCloud Private Relay | Anonymiser | - |
| Atlassian | SaaS | - |
| AWS | Hosting Provider | - |
| Azure | Hosting Provider | - |
| Azure WAF | WAF | Azure access required |
| Bingbot | Web crawler | - |
| Bunny CDN | CDN | - |
| CDN77 | CDN | - |
| Contabo | Hosting Provider | - |
| CriminalIP | IP Reputation | Registration required |
| Datadog | SaaS | - |
| DigitalOcean | Hosting Provider | - |
| Fly.io | Hosting Provider | - |
| GCP | Hosting Provider | - |
| Hosting Provider | - | |
| Google Special-case crawlers | Web crawler | - |
| Googlebot | Web crawler | - |
| Hetzner | Hosting Provider | - |
| IBM Cloud | Hosting Provider | - |
| Imperva | WAF | - |
| IPAPI | IP Geolocation | - |
| IPQualityScore | IP Reputation | Registration required |
| IPURL | User Provided | - |
| Leaseweb | Hosting Provider | - |
| Linode | Hosting Provider | - |
| M247 | Hosting Provider | - |
| OpenAI | Web crawler | - |
| OVH | Hosting Provider | - |
| PTR | DNS | - |
| Render | Hosting Provider | - |
| Scaleway | Hosting Provider | - |
| Vultr | Hosting Provider | - |
| Shodan | IP Reputation | Registration required |
| Stripe | SaaS | - |
| Tencent Cloud | Hosting Provider | - |
| VirusTotal | IP Reputation | Registration required |
| Zscaler | Security | - |
Installation
Binaries for macOS, Linux and Windows are available on the releases page.
macOS - Homebrew
$ brew tap jonhadfield/ipscout
$ brew install ipscout
Linux
Install latest release.
curl -sL https://raw.githubusercontent.com/jonhadfield/ipscout/add_install_script/install | sh
other distributions
Download the latest release from the releases page.
Build from source
Go 1.24 or later is required to compile ipscout. Clone the repository and run:
go build ./...
This will create an ipscout binary in the current directory.
Updating the ip-fetcher dependency
Most providers source their IP-range data via ip-fetcher. It is pinned in go.mod to a v-prefixed release tag — that released module, not a local checkout, is the source of truth for upstream data formats. To pick up changes:
- Cut a new
v-prefixed release tag in the ip-fetcher repo (e.g.v0.0.17). - In this repo:
go get github.com/jonhadfield/ip-fetcher@vX.Y.Z && go mod tidy.
The commented replace directive in go.mod is for local development only and must never be committed enabled.
Usage
$ ipscout <host>
<host> can be an IP address or a fully qualified domain name.
Additional commands are available:
$ ipscout cache # manage cached results
$ ipscout config # view or output configuration
$ ipscout rate # rate a host using provider data
Configuration
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
ports: ["443/tcp"] # filter results by port [tcp,udp,443/tcp,...]
output: table # output format: table or json
style: cyan # output style [ascii, cyan, green, yellow, red, blue]
providers:
# list of providers with their configurations below...
Providers
Providers are configured in the config.yaml file.
A number of providers are enabled by default, but can be disabled by setting enabled: false.
AbuseIPDB
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: false
Alibaba Cloud
Alibaba Cloud is a hosting provider. IP ranges are retrieved from the BGPView API and checked for matches against the target host.
Annotated
The 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 Annotation
A list of files can be specified in the provider's paths section:
providers:
annotated:
enabled: true
paths:
- /path/to/file.yaml
Apple iCloud Private Relay
IP anonymisation service from Apple.
iCloud Private Relay — part of an iCloud+ subscription — helps protect your privacy when you browse the web in Safari.
Amazon Web Services
AWS is a Hosting Provider that publishes network prefixes used by their services.
Azure
Azure is a hosting provider that publishes network prefixes used by their services.
Azure WAF
Azure WAF is a Web Application Firewall used to secure services hosted on Azure. This currently supports Azure Global WAF, used to secure Azure Front Door, and will show custom rules and prefixes matching the provided host. Authentication will be read from the environment.
Bingbot
Bingbot is the web crawler for the Bing search engine. Bing publishes network prefixes used by their crawlers.
CriminalIP
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.
Set environment variable CRIMINAL_IP_API_URL with your API key.
DigitalOcean
DigitalOcean is a hosting provider that publishes network prefixes used by their services.
Google Cloud Platform
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.
Google Special Crawlers
Google provides a list of IP addresses used by their non-Googlebot crawlers here.
Googlebot
Googlebot is a web crawler and publishes network prefixes used by their bots.
Hetzner
Hetzner is a hosting provider. IP ranges are retrieved from the BGPView API and checked for matches against the target host.
iCloud Private Relay
iCloud Private Relay is an anonymising service provided by Apple. They publish their network prefixes here.
IPAPI
Query the ipapi API for geolocation data. The API is free for up 30,000 requests per day.
IPQualityScore
Query the IPQualityScore API for host reputation data. The API is free to registered users for 5,000 requests.
Set environment variable IPQS_API_KEY with your API key.
IPURL
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
Linode is a hosting provider that publishes network prefixes used by their services.
M247
M247 is a global hosting and connectivity provider. IP ranges are retrieved from the BGPView API and checked for matches against the target host.
OpenAI
OpenAI operates a number of bots and publishes the network prefixes they crawl and browse from: GPTBot, OAI-SearchBot and ChatGPT-User. A match shows which of the bots' lists contain the target host.
OVH
OVH is a hosting provider that publishes network prefixes used by their services.
Scaleway
Scaleway is a European hosting provider. IP ranges are retrieved from the BGPView API and checked for matches against the target host.
Vultr
Vultr is a cloud hosting provider. IP ranges are retrieved from the BGPView API and checked for matches against the target host.
PTR
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:53
Shodan
Query the Shodan API for information on an IP address, with open ports, and services.
Set environment variable SHODAN_API_KEY with your API key.
VirusTotal
Query the VirusTotal API for information from various providers on an IP address.
Set environment variable VIRUSTOTAL_API_KEY with your API key.
Zscaler
Zscaler publishes a list of IP prefixes used by its services.
IPScout downloads this list and checks whether the target IP is within those ranges.
The default source URL is https://api.config.zscaler.com/zscaler.net/cenr/json and
can be overridden in the configuration file.
zscaler:
enabled: true
url: https://api.config.zscaler.com/zscaler.net/cenr/json
document_cache_ttl: 1440 # minutes
Atlassian
Atlassian publishes the IP ranges used by its cloud products (Jira, Confluence, Bitbucket and others). IPScout downloads this list and checks whether the target IP is within those ranges.
Bunny CDN
Bunny CDN is a content delivery network that publishes the IP ranges used by its edge servers. IPScout downloads this list and checks whether the target IP is within those ranges.
CDN77
CDN77 is a content delivery network that publishes the prefixes used by its edge network. IPScout downloads this list and checks whether the target IP is within those ranges.
Contabo
Contabo is a hosting provider. IP ranges are retrieved from the RIPE stat / BGPView APIs and checked for matches against the target host.
Datadog
Datadog is an observability platform that publishes the IP ranges used by its services. IPScout downloads this list and checks whether the target IP is within those ranges.
Fly.io
Fly.io is an application hosting provider. IP ranges are retrieved from the RIPE stat / BGPView APIs and checked for matches against the target host.
IBM Cloud
IBM Cloud is a hosting provider. IP ranges are retrieved from the RIPE stat / BGPView APIs and checked for matches against the target host.
Imperva
Imperva (Incapsula) is a web application firewall and CDN that publishes the IP ranges used by its network. IPScout downloads this list and checks whether the target IP is within those ranges.
Leaseweb
Leaseweb is a hosting provider. IP ranges are retrieved from the RIPE stat / BGPView APIs and checked for matches against the target host.
Render
Render is an application hosting provider. IP ranges are retrieved from the RIPE stat / BGPView APIs and checked for matches against the target host.
Stripe
Stripe publishes the IP ranges used by its API and webhook infrastructure. IPScout downloads this list and checks whether the target IP is within those ranges.
Tencent Cloud
Tencent Cloud is a hosting provider. IP ranges are retrieved from the RIPE stat / BGPView APIs and checked for matches against the target host.
Changelog
See CHANGELOG.md for release notes.
License
IPScout is licensed under the Apache 2.0 License.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package present contains utilities for rendering output from provider results.
|
Package present contains utilities for rendering output from provider results. |