NAME

ccfilter - SiLK Plug-In to map IPs to country codes

SYNOPSIS

  rwfilter [--scc=ID] [--dcc=ID] ...

  rwcut --fields=scc,dcc ...

  rwsort --fields=scc,dcc ...

  rwuniq --fields=scc,dcc ...

DESCRIPTION

The Country Code plug-in provides a mapping from an IP address to two-letter, lowercase abbreviation of the country that owns the IP address. With this plug-in, SiLK flow records can be partitioned (rwfilter(1)), displayed (rwcut(1)), sorted (rwsort(1)), and counted (rwuniq(1)) by country.

The abbreviations used by the Country Code plug-in are those used by the Root-Zone Whois Index (see for example http://www.iana.org/cctld/cctld-whois.htm) or one of the following special codes:

--: N/A (e.g. private and experimental reserved addresses)
a1: anonymous proxy
a2: satellite provider
o1: other

Creating the pmap file that maps an IP to its country code requires the GeoIP Country(R) or free GeoLite database created by MaxMind, available from http://www.maxmind.com, as described in the MAPPING FILE section below.

OPTIONS

The Country Code plug-in provides the following options to the indicated applications.

rwfilter Switches

--scc=COUNTRY_CODE_LIST: Pass the record if the source IP maps to a country code that appears in the comma separated list of lowercase two-letter country codes and/or special codes. For example, --scc=cx,uk,kr,jp,--.
--dcc=COUNTRY_CODE_LIST: As --scc for the destination IP address.

rwcut, rwsort, and, rwuniq Switches

--fields=FIELDS: FIELDS refers to a list of fields to use for the operation. The Country Code plug-in makes two additional fields, scc (alias 18) and dcc (19) available for display, sorting, and counting using the rwcut(1), rwsort(1), and rwuniq(1) tools:

MAPPING FILE

To map from IP addresses to country codes you will need to create the country_codes.pmap data file and install it in the appropriate location (see the FILES section below).

The pmap data file is based on the GeoIP Country(R) or free GeoLite database created by MaxMind and available from http://www.maxmind.com/. We do not distribute the database nor the data file, but we provide Perl scripts that will convert the GeoIP database to the format that ccfilter.so expects.

MaxMind distributes multiple versions of their GeoIP Country database; one is a free evaluation copy that is 97% accurate. In addition, they sell versions with higher accuracy, and they offer various subscription services.

The rwgeoip2ccmap(1) program converts the MaxMind GeoIP file to the form that the SiLK tools require.

FILES

SiLK applications look for the Country Code plug-in the the following locations. ($SILK_PATH is value of the SILK_PATH environment variable, if it is set; the use of /usr/local/ assumes the tool exists in the /usr/local/bin/ directory.)

  $SILK_PATH/share/lib/silk/ccfilter.so
  $SILK_PATH/share/lib/ccfilter.so
  $SILK_PATH/lib/ccfilter.so
  /usr/local/share/lib/silk/ccfilter.so
  /usr/local/share/lib/ccfilter.so
  /usr/local/lib/ccfilter.so

If the fields and/or switches are not available in an application, verify that ccfilter.so is installed in the correct location. To aid in debugging, one may invoke:

  env SILK_DYNLIB_DEBUG=1 rwcut

to print the directory paths where rwcut is looking for ccfilter.so.

The tools will look for the data file that maps IPs to country codes in the following locations:

  $SILK_PATH/share/silk/country_codes.pmap
  $SILK_PATH/share/country_codes.pmap
  /usr/local/share/silk/country_codes.pmap
  /usr/local/share/country_codes.pmap

BUGS

Prefix map files do not support IPv6 addresses.