ipscout

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
• Output
• Providers
• Installation
• Usage
• Configuration
• Rating
• Provider Details
• Changelog
• License

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.

• table
• json

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:

• red
• ascii

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
AhrefsBot	Web crawler	-
Akamai	CDN	-
Alibaba Cloud	Hosting Provider	-
Annotated	User Provided	-
Anthropic	Web crawler	-
Apple iCloud Private Relay	Anonymiser	-
Applebot	Web crawler	-
Atlassian	SaaS	-
AWS	Hosting Provider	-
Azure	Hosting Provider	-
Azure WAF	WAF	Azure access required
Bingbot	Web crawler	-
Blocklist.de	Threat Feed	-
Bunny CDN	CDN	-
CDN77	CDN	-
CINS Army List	Threat Feed	-
Cloudflare	CDN	-
Contabo	Hosting Provider	-
CriminalIP	IP Reputation	Registration required
Datadog	SaaS	-
DigitalOcean	Hosting Provider	-
DShield	Threat Feed	-
DuckDuckBot	Web crawler	-
Emerging Threats	Threat Feed	-
Fastly	CDN	-
Fly.io	Hosting Provider	-
GCP	Hosting Provider	-
GitHub	SaaS	-
Google	Hosting Provider	-
Google Special-case crawlers	Web crawler	-
Google User-triggered Fetchers	Web crawler	-
Googlebot	Web crawler	-
Hetzner	Hosting Provider	-
IBM Cloud	Hosting Provider	-
Imperva	WAF	-
IPAPI	IP Geolocation	-
IPQualityScore	IP Reputation	Registration required
IPtoASN	ASN Data	-
IPURL	User Provided	-
Leaseweb	Hosting Provider	-
Linode	Hosting Provider	-
M247	Hosting Provider	-
OpenAI	Web crawler	-
Oracle Cloud (OCI)	Hosting Provider	-
OVH	Hosting Provider	-
PerplexityBot	Web crawler	-
PTR	DNS	-
Render	Hosting Provider	-
Scaleway	Hosting Provider	-
Vultr	Hosting Provider	-
Shodan	IP Reputation	Registration required
Spamhaus DROP	Threat Feed	-
Stripe	SaaS	-
Tencent Cloud	Hosting Provider	-
UptimeRobot	SaaS	-
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

Since 0.6.2, ipscout is distributed as a Homebrew cask. If you installed an earlier version (distributed as a formula), reinstall once to migrate:

$ brew uninstall 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:

1. Cut a new v-prefixed release tag in the ip-fetcher repo (e.g. v0.0.17).
2. 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...

Rating

ipscout rate combines the results from every provider that supports rating into a single score and a block or allow recommendation.

$ ipscout rate 1.10.16.1

+------------+----------+-------+-----------------------------------------------------------+
| PROVIDER   | DETECTED | SCORE | REASONS                                                   |
+------------+----------+-------+-----------------------------------------------------------+
| spamhaus   | true     | 10.00 | listed on Spamhaus DROP (do not route or peer): SBL256894 |
| abuseipdb  | true     | 3.00  | confidence: 0.00                                          |
| ipqs       | true     | 9.00  | confidence: 0.00                                          |
| virustotal | true     | 0.00  | harmless                                                  |
+------------+----------+-------+-----------------------------------------------------------+
| AVERAGE    |          | 5.50  |                                                           |
+------------+----------+-------+-----------------------------------------------------------+
Recommendation: block

Each provider that matches the host contributes a score. The scores are averaged, and the result is compared against blockScoreThreshold: below it the recommendation is allow, otherwise block. A provider reporting a noblock threat indicator, such as an entry annotated that way in your own data, forces allow regardless of the score.

Rating configuration

No setup is required. If no rating configuration file exists, the built-in defaults are used and the path checked is reported so you know where to put one.

To write your own, start from the defaults:

$ ipscout rate config --default > $HOME/.config/ratingConfig.json

The location is set by rating.config_path in config.yaml, and <home> in that value is expanded to your home directory:

rating:
  config_path: <home>/.config/ratingConfig.json
  use_ai: false
  openai_api_key: <your-openai-api-key>

ipscout rate config prints your rating configuration file, and --path prints one from a specific location. Both validate what they read, so they are a way to check a file parses. Unlike rating itself, they require the file to exist rather than falling back to the defaults.

The configuration has a global section and a per-provider section, abbreviated here (the shipped defaults list 26 high threat country codes and carry an entry for 50 providers):

{
  "global": {
    "blockScoreThreshold": 5.0,
    "highThreatCountryCodes": ["CN", "RU", "IR"],
    "mediumThreatCountryCodes": ["NL", "CA"]
  },
  "providers": {
    "spamhaus": { "defaultMatchScore": 10.0 },
    "aws": { "defaultMatchScore": 7.0 },
    "shodan": {
      "openPortsScore": 5.0,
      "highThreatCountryMatchScore": 10.0,
      "mediumThreatCountryMatchScore": 7.0
    }
  }
}

Most providers take a single defaultMatchScore, applied when the host matches their data. Threat feeds default to 10.0 and hosting providers to 7.0-8.0, so appearing on a blocklist weighs more than merely being hosted somewhere. CriminalIP, Shodan and VirusTotal take finer-grained scores for the specific conditions they report.

AI rating

With --ai, the threat indicators each provider reports are shown and then sent to OpenAI, which returns a written assessment in place of the scored table:

$ ipscout rate --ai 1.10.16.1

This requires an OpenAI API key, set with --openai-api-key or rating.openai_api_key in config.yaml.

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

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.

IPtoASN

iptoasn.com publishes a free, hourly-updated IP address to ASN mapping. The combined IPv4+IPv6 dataset is downloaded and cached, and the target host is matched against it to report the announcing AS number, name, country and address range.

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

AhrefsBot

AhrefsBot is the web crawler for the Ahrefs SEO platform. Ahrefs publishes the IP ranges used by its crawler at api.ahrefs.com/v3/public/crawler-ip-ranges. IPScout downloads this list and checks whether the target IP is within those ranges.

Akamai

Akamai is a content delivery network that publishes the IP ranges used by its edge platform at ip-ranges.akamai.com. IPScout downloads this list and checks whether the target IP is within those ranges.

Applebot

Applebot is Apple's web crawler, used by products such as Siri and Spotlight. Apple publishes the IP ranges used by the crawler at search.developer.apple.com/applebot.json. IPScout downloads this list and checks whether the target IP is within those ranges.

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.

Cloudflare

Cloudflare is a content delivery network that publishes the IP ranges used by its edge network at cloudflare.com/ips-v4 and cloudflare.com/ips-v6. IPScout downloads these lists 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.

DuckDuckBot

DuckDuckBot is the web crawler for the DuckDuckGo search engine. DuckDuckGo publishes the IP addresses used by the crawler at duckduckgo.com/duckduckbot.json. IPScout downloads this list and checks whether the target IP is within those ranges.

Fastly

Fastly is a content delivery network that publishes the IP ranges used by its edge network via its public IP list API. 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.

GitHub

GitHub publishes the IP ranges used by its services (web, API, Actions, Pages and others) via its meta API. IPScout downloads this list and reports the services associated with any matching range.

Google User-triggered Fetchers

Google publishes the IP ranges used by its user-triggered fetchers, tools that fetch pages on behalf of a user request. IPScout downloads this list and checks whether the target IP is within those ranges.

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.

Oracle Cloud (OCI)

Oracle Cloud Infrastructure publishes the IP ranges used by its services. IPScout downloads this list and reports the region and service tags associated with any matching range.

PerplexityBot

PerplexityBot is the web crawler for the Perplexity answer engine. Perplexity publishes the IP ranges used by the crawler at perplexity.com/perplexitybot.json. IPScout downloads this list and checks whether the target IP is within those ranges.

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.

Anthropic

Anthropic publishes the IP ranges used by its crawlers, including ClaudeBot and the Claude user-triggered fetchers, at claude.com/crawling/bots.json. IPScout downloads this list and checks whether the target IP is within those ranges.

Blocklist.de

Blocklist.de is a community-run service that collects reports of hosts attacking other systems via SSH, mail, web and other services. The aggregated list of reported addresses is published at lists.blocklist.de/lists/all.txt. IPScout downloads this list and checks whether the target IP appears in it.

CINS Army List

The CINS Army List is the freely available subset of the Collective Intelligence Network Security score, listing addresses with a poor reputation that are not yet widely blocked. It is published at cinsscore.com/list/ci-badguys.txt. IPScout downloads this list and checks whether the target IP appears in it.

DShield

DShield is the SANS Internet Storm Center's distributed intrusion detection system. Its recommended block list, covering the networks responsible for the most reported attacks, is published at feeds.dshield.org/block.txt. IPScout downloads this list and checks whether the target IP is within those networks, reporting the attack count and network owner where available.

Emerging Threats

Emerging Threats publishes open rulesets and reputation data for intrusion detection systems. Its list of known compromised hosts is published at rules.emergingthreats.net/blockrules/compromised-ips.txt. IPScout downloads this list and checks whether the target IP appears in it.

Spamhaus DROP

Spamhaus DROP (Don't Route Or Peer) lists netblocks that Spamhaus considers wholly controlled by criminal operations. The lists are published at spamhaus.org/drop/drop_v4.json and spamhaus.org/drop/drop_v6.json. IPScout downloads both lists and checks whether the target IP is within those netblocks, reporting the associated SBL identifier and RIR.

UptimeRobot

UptimeRobot is a website and service monitoring platform. The IP ranges used by its monitoring probes are published at uptimerobot.com/inc/files/ips/IPv4andIPv6.txt. IPScout downloads this list and checks whether the target IP is within those ranges.

Changelog

See CHANGELOG.md for release notes.

License

IPScout is licensed under the Apache 2.0 License.