From 050a2e10f04d9d04ad45c6d77187da629182fafc Mon Sep 17 00:00:00 2001 From: Jon Hadfield Date: Mon, 6 May 2024 07:11:13 +0100 Subject: [PATCH] update README with details of providers. --- README.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 164 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index f62946a..9dea5d0 100644 --- a/README.md +++ b/README.md @@ -2,31 +2,178 @@ IPScout is a command line tool useful for network administrators and security analysts to quickly identify the origin and threat of -an IP address. Results can be cached to reduce API calls and improve performance. +an IP address. ## Providers IPScout supports multiple well known sources. You can also provide custom sources with the [Annotated](#Annotated) and [IPURL](#IPURL) providers. -The following are currently supported: +Provider data and search results can be cached to reduce API calls and improve performance. -| Provider | Category | Needs Registration | -|:-------------------------------------------------------------------------------------------|:--------------:|:------------------:| -| [AWS](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html#aws-ip-download) | Cloud Provider | | -| [AbuseIPDB](https://www.abuseipdb.com/) | IP Reputation | 🔑 | -| [Annotated](#Annotated) | User Provided | | -| [Azure](https://www.microsoft.com/en-gb/download/details.aspx?id=56519) | Cloud Provider | | -| [CriminalIP](https://www.criminalip.io/) | IP Reputation | 🔑 | -| [DigitalOcean](https://www.criminalip.io/) | Cloud Provider | | -| [IPURL](#IPURL) | User Provided | | -| [PTR](https://www.cloudflare.com/en-gb/learning/dns/dns-records/dns-ptr-record/) | DNS | | -| [Shodan](https://www.shodan.io/) | IP Reputation | 🔑 | +| Provider | Category | Notes | +|:----------------------------------------------------------|:----------------:|:---------------------:| +| [AbuseIPDB](#AbuseIPDB) | IP Reputation | Registration required | +| [Annotated](#Annotated) | User Provided | - | +| [Apple iCloud Private Relay](#Apple-iCloud-Private-Relay) | Anonymiser | - | +| [AWS](#Amazon-Web-Services) | Hosting Provider | - | +| [Azure](#Azure) | Hosting Provider | - | +| [CriminalIP](#CriminalIP) | IP Reputation | Registration required | +| [DigitalOcean](#DigitalOcean) | Hosting Provider | - | +| [GCP](#Google-Cloud-Platform) | Hosting Provider | - | +| [IPURL](#IPURL) | User Provided | - | +| [Linode](#Linode) | Hosting Provider | - | +| [PTR](#PTR) | DNS | - | +| [Shodan](#Shodan) | IP Reputation | Registration required | -## Getting Started +## Installation -### Installation +Binaries for macOS, Linux and Windows are available on the [releases](https://github.com/jonhadfield/ipscout/releases) +page. -### +### macOS - Homebrew + +``` +$ brew tap jonhadfield/ipscout +$ brew install ipscout +``` + +## Configuration + +A default configuration is created +on first run and located at: `$HOME/.config/ipscout/config.yaml`. + +```yaml +--- +global: +# common settings for output and caching + +providers: +# list of providers with their configurations +``` + +## 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](https://www.abuseipdb.com/) API for information on an IP address, with a threat +confidence score, and any reports filed for them. +A [free plan](https://www.abuseipdb.com/pricing) exists for individuals, with a limit of 1000 requests per day. + +Environment variable `ABUSEIPDB_API_KEY` must be set with your API key. + +```yaml +providers: + abuseipdb: + enabled: false +``` + +### Annotated + +The Annotated provider parses one or more user provided files containing prefixes and accomanying annotations. + +```yaml +--- +- prefixes: [ "20.20.20.0/24", "20.20.21.0/24" ] + annotations: + - date: 2024/04/19 18:58 + author: john doe + notes: + - My First Annotation + - My Second Annotation +- prefixes: [ "9.9.9.9/32" ] + annotations: + - date: 2024/04/19 19:00 + author: jane doe + notes: + - Another Annotation +``` + +A list of files can be specified in the provider's `paths` section: + +```yaml +providers: + annotated: + enabled: false + paths: + - /path/to/file.yaml +``` + +### Amazon Web Services + +[AWS](https://aws.amazon.com/) is a Hosting Provider +that [publishes](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html#aws-ip-download) network prefixes +used by their services. + +### Apple iCloud Private Relay + +[iCloud Private Relay](https://support.apple.com/en-us/102602) is an anonymising service provided by Apple. They publish +their network prefixes [here](https://mask-api.icloud.com/egress-ip-ranges.csv). + +### Azure + +[Azure](https://azure.microsoft.com/) is a hosting provider +that [publishes](https://www.microsoft.com/en-gb/download/details.aspx?id=56519) network prefixes used by their +services. + +### CriminalIP + +Query the [CriminalIP](https://www.criminalip.io/) API for information on an IP address/endpoint, with risk ratings, and +any abuse reports filed for them. +A [free plan](https://www.criminalip.io/pricing) exists with a small number of free credits. + +Environment variable `CRIMINAL_IP_API_KEY` must be set with your API key. + +### DigitalOcean + +[DigitalOcean](https://www.digitalocean.com/) is a hosting provider +that [publishes](https://www.digitalocean.com/geo/google.csv) network prefixes used by their services. + +### Google Cloud Platform +[GCP](https://cloud.google.com/) is a hosting provider +that [publishes](https://cloud.google.com/compute/docs/faq#find_ip_range) network prefixes used by their +services. + +### IPURL + +IPURL retrieves lists of IP prefixes from user provided URLs and checks the target IP address against them. +Documents are expected to contains a list of prefixes in CIDR format, one per line. + +Example configuration: +```yaml + 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](https://www.linode.com/) is a hosting provider +that [publishes](https://geoip.linode.com/) network prefixes used by their services. + +### 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/ + +### Shodan + +Query the [Shodan](https://www.shodan.io/) API for information on an IP address, with open ports, and services. + +Set environment variable `SHODAN_API_KEY` with your API key. -### Sources