grepcidr 3.0 - Filter IP addresses matching IPv4 and IPv6 CIDR specification
Parts Copyright (C) 2004-2005  Jem E. Berkes <jberkes@pc-tools.net>
	http://www.pc-tools.net/unix/grepcidr/

Revised by John Levine <johnl@standcore.com> Dec 2013-Dec 2020

PURPOSE
-------
grepcidr can be used to filter a list of IP addresses against one or more
Classless Inter-Domain Routing (CIDR) specifications, or arbitrary networks
specified by an address range. As with grep, there are options to invert
matching and load patterns from a file. grepcidr is capable of comparing
thousands or even millions of IPs to networks with little memory usage and
in reasonable computation time.

grepcidr has endless uses in network software, including: mail filtering and
processing, network security, log analysis, and many custom applications.

COMPILING & INSTALLING
----------------------
Edit Makefile to customize the build. Then,
make
make install


COMMAND USAGE
-------------
Usage:
        grepcidr [-V] [-cCDvhaiso] PATTERN [FILE ...]
        grepcidr [-V] [-cCDvhaiso] [-e PATTERN | -f FILE] [FILE ...]

-V	Show software version
-a	Anchor matches to beginning of line, otherwise match anywhere
-c	Display count of the lines that would have been shown, instead of showing them
-C	Parse CIDR ranges in input and only match if a search term encompasses the entire range.
-D	Parse CIDR ranges in input and match if a search term matches any part of the range.
-v	Invert the sense of matching, to select non-matching IP addresses
-e	Specify pattern(s) on command-line
-f	Obtain CIDR and range pattern(s) from file
-i	Ignore patterns that are not valid CIDRs or ranges
-h	Do not print filenames when matching multiple files
-o	Print matching CIDR pattern instead of input line. When an IP matches
	multiple overlapping patterns, automatically selects the narrowest
	(most specific) match. Useful for reverse lookups to identify which
	network/service an IP belongs to.

PATTERN specified on the command line may contain multiple patterns
separated by whitespace or commas. For long lists of network patterns,
specify a -f FILE to load where each line contains one pattern. Comment
lines starting with # are ignored, as are comments following white space
after a pattern.  Use -i to ignore invalid pattern lines.

Each pattern, whether on the command line or inside a file, may be:
CIDR format	a.b.c.d/xx or aa:bb::cc:dd/xx
IP range	a.b.c.d-e.f.g.h
Single IP	a.b.c.d or aa:bb:cc:dd

IPv6 addresses can be written in any format including embedded IPv4.
The zero address :: is accepted as a pattern but does not match in
files.  (Use regular grep if that's what you're looking for.)  It does
not accept IPv6 ranges, since few people use them.

Grepcidr uses a state machine to look for IP addresses in the input,
and a binary search to match addresses against patterns.  Its speed is
roughly O(N) in the size of the input, and O(log N) in the number of
patterns.  A prepass over the patterns merges adjacent and overlapping
patterns so there is negligible speed penalty for matching, e.g.
1.2.2.0/24 and 1.2.3.0/24 rather than 1.2.2.0/23.

Input files are mapped into memory if possible, so the state machine
can make one pass over the whole file.  If mapping fails, it reads the
input a line at a time.

EXAMPLES
--------

grepcidr -f ournetworks blocklist > abuse.log
	Find our customers that show up in blocklists

grepcidr 127.0.0.0/8,::1 iplog
	Searches for any localnet IP addresses inside the iplog file

grepcidr "192.168.0.1-192.168.10.13" iplog
	Searches for IPs matching indicated range in the iplog file

script | grepcidr -ivf whitelist > blocklist
	Create a blocklist, with whitelisted networks removed (inverse)

grepcidr -if list1 list2
	Cross-reference two lists, outputs IPs common to both lists

grepcidr -o -f networks.txt access.log
	Print the matching network pattern for each IP in access.log
	(reverse lookup: IP → CIDR pattern)

echo "192.168.1.200" | grepcidr -o -f patterns.txt
	Find which CIDR pattern contains the given IP address.
	When multiple overlapping patterns match, returns the most specific one.

lsof -i -nP | grep -oE '[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+' | grepcidr -o -f aws-cidrs.txt
	Identify AWS services from network connections. If patterns file contains
	tab-delimited entries like "52.94.0.0/16<TAB>EC2", the service name is
	included in the output.


TESTING
-------
A comprehensive test suite is available in the tests/ directory.

To run all tests:
	make test

See tests/README.md for detailed information on running tests and test organization.