The IPR (IP Reputation Classification) package analyzes IP addresses (given as IPv4 or IPv6), and returns matching categories and corresponding category values. The classification result helps to define whether a given IP address has a good or bad reputation.

The results can be used to block unwanted connections to or from IP addresses with a bad reputation.

Initialization

To use the IPR classification functions, the IPR classification package must first be initialized. To do this, create an instance of the dca_ipr::IprClassification module using dca_ipr::IprClassification::create().

Set up a connection to an IPR database using the database type dca_ipr::DBT_Ipr. Refer to Setting up a Database Connection for the steps required to do this.

Once a connection to the IPR database has been established, an instance of a dca_ipr::IprClassifier must be created. Use dca_ipr::IprClassification::createClassifier(), passing as parameter the newly created database connection object.

The IprClassifier classifies either a dca_ipr::Ip, dca_ipr::Ipv6 or dca_ipr::Ipv4 object as input and returns as result a dca_ipr::IprClassificationResults object that contains all matching categories and corresponding values.

Classification

The IPR classification returns a set of matched categories and corresponding values. The following categories are currently supported:

Geo Location
Spam
Anonymous Proxies
Botnet Clients

A complete list of suppported IPR categories can be found at https://exchange.xforce.ibmcloud.com/faq#info_for_ip_report

The IP address input objects support a number of different constructors. Keep in mind that providing a generic dca_ipr::Ip class and free formatted text as the IP address is the slowest method of constructing an IP address object, as the IPR module has to perform a validation of the input data, and determine whether the address is IPv6 or IPv4.

The result of the IPR classification is a set of matched categories together with the corresponding values for the categories:

Example
An IP classification returns a result dca_ipr::IprClassificationResult::categoryId = 1 and dca_ipr::IprClassificationResult::value = 6

CategoryId 1 denotes the Geo Location category (dca_ipr::IPR_CATEGORY_ID_GEOLOCATION). This category has associated enum objects, (dca_ipr::IprCategory::enumsSize() > 0), and so the value relates to an enumeration object. Using dca_ipr::IprCategory::enumByValue() and dca_ipr::IprEnums::byId() to return the corresponding dca_ipr::IprEnum object, we can see that this refers to the Geo Location "United Arab Emirates".

Enumeration

To enumerate all known categories and enums etc. you can use a dca_ipr::IprCategoriesInfo object. This can be obtained from the dca_ipr::IprClassification::getCategoriesInfo() function.

We provide the following class structures:

Categories (dca_ipr::IprCategories)

This is a container for dca_ipr::IprCategory objects. It lists all supported categories.

Enums (dca_ipr::IprEnums)

This is a container for dca_ipr::IprEnum objects.

Locales (dca_ipr::IprLocales)

This is a container for dca_ipr::IprLocale objects. It lists all supported locales. Locales are used to provide language specific names for the available categories and enum objects.

The default locale is "en_US". If you wish to use a different locale, the function name(), provided by the relevant objects, takes an optional parameter where the locale can be specified. If the locale does not exist, or a localization for the particular string is not available, the default locale will be used.

See also: dca_ipr::IprCategory, dca_ipr::IprEnum, dca_ipr::IprLocale

Example code

The following code demonstrates the IPR classification.

// assume we have a valid DcaInstance (myDca) and License (myLicense)
 
IprClassification myIprClassification;
myIprClassification = IprClassification::create( myDca, myLicense );
 
IprClassifier myIprClassifier;
myIprClassifier = myIprClassification.createClassifier( myAppVars.myDbConnection );
 
// a valid IP v6 mapped IP v4 address
const char buffer[ ] = "::ffff:192.168.52.112";
 
// set up the input data of the classification
const Ipv6 myIp( buffer, sizeof(buffer) );
 
// start IPR classification
IprClassificationResults myResults;
FunctionResult myFR = myIprClassifier.classify( myIp, myResults );
 
// received an error?
if( !myFR ) {
        error( myFR );
        return;
}
 
// check - did we get a match?
if( myResults.size() == 0 ) {
        std::cout << "No match returned from IPR classification." << std::endl;
        return;
}
 
// iterate over the results to display the categories
std::cout << "Results returned from IPR Classification: " << std::endl;
for( DCA_INDEX_TYPE i = 0; i < myResults.size(); ++i ) {
        const IprClassificationResult aResult = myResults[ i ];
        std::cout << "category id: " << myResults[ i ].categoryId <<
                     " value: " << myResults[ i ].value << std::endl;
}