Using the IP Groups API

Overview

The IP Groups API is a simple way to add, remove, and edit IP Groups via the command line.

Note

The API only accepts requests from hosts that are part of the authorized IPs whitelist.

Getting Started

Authentication

First, find the IP of the host from where the local computer is going to access the API in the list of IP addresses that can access it. The User API uses a whitelist of IPs for authentication. The whitelist is defined in $homeDir/files/auth_ips.cfg (one host IP per line).

The response for unauthenticated request is: {“msg”:”Request cannot be authenticated.”,”err”:”oauthFailure”}

Examples

Perl

There is an example script that is included in Scrutinizer in the /scrutinizer/files/api_examples/ directory.

  • ipgroup.pl

    • This script allows the user to search/create/edit/delete IP Groups within Scrutinizer. It consists of six subroutines:

Reference Guide

rm=ipgroups

This URL field is required when making an HTTP request. This field is always equal to ipgroups.

action

Indicates the API action that can be performed with the JSON provided.

Below is a list of available actions.

search_ipgroups

Allows the user to look up details about an IP Group. There are a few parameters that can be passed to the search_ipgroups function:

  • Search By Exact Name

    search_ipgroups(name=>"My IP Group");
    
  • Search by name with like, not like

    search_ipgroups(name=>"My IP Gro", fc_name_comp => "like");
    search_ipgroups(name=>"My IP Gro", fc_name_comp => "notLike");
    
  • Search by Flow Class ID (Unique identifier for IP Group)

    search_ipgroups(fc_id=>16800916);
    
  • Retrieve IP Groups with paging

    search_ipgroups(page=>1,maxRows=>500);
    

create_ipgroup

To create IP Groups, specify flowclass rules within the API script. There are multiple ways to create a flowclass rule.

  • Single IP Address
  • IP Range
  • Network
  • Child IP Group

For each of these options, specify the data to use, then edit the $rules array to fit the requirements.

my $rules = [
 {type=>"ip", address => "10.1.1.1"},                           # Single IP Address (10.1.1.1)
 {type=>"range", eip => "10.2.1.10", sip => "10.2.1.1"},        # IP Range (10.2.1.1 -> 10.2.1.10)
 {type=>"network", address => "172.165.22.1", mask => "16"},    # Network with /16 mask (172.165.x.x)
 {type=>"child", child_id => 16900011}                          # Child IP Group (exisiting group is part of new IP Group)
];
  • Create an IP Group for a single IP address

    my $rules = [
     {type=>"ip", address => "10.1.1.1"},                           # Single IP Address (10.1.1.1)
    ];
    
    create_ipgroup(rules=>$rules, apptype=>"internal", name => "myOneServer");
    
  • Create an internal IP Group for a specific subnet

    my $rules = [
     {type=>"network", address => "192.168.100.0", mask => "24"},    # Network with /24 mask (192.168.100.x)
    ];
    
    create_ipgroup(rules=>$rules, apptype=>"internal", name => "myInternalIpGroup");
    
  • Create an external IP Group and include an existing IP Group (“UK Branch” will be part of “European Offices”)

    my $rules = [
     {type=>"child", child_id => 16900011}                          # Where '16900011' is the exisiting "UK Branch" groups fc_id
    ];
    
    create_ipgroup(rules=>$rules, apptype=>"internal", name => "European Offices");
    

update_ipgroup

The API allows the user to also edit existing IP Groups. To do this, a flow class ID of the group must be specified in order to edit it.

  • Add rules to Group

  • Change Name of IP Group

    Note

    The fc_id flag is required for this function. This value can be found in the output from search_ipgroups by passing the name.

    search_ipgroups(name=>"UK Branch");
    

    Output:

    "results": [{
      "fc_name": "UK Branch",
      "fc_id": 16900017    # This is the Flow Class ID for this exisiting IP Group
    }]
    
  • Add a single IP address to an existing group

    my $rules = [
     {type=>"ip", address => "10.20.30.100"},                           # Single IP Address (10.20.30.100) to be added
    ];
    
    update_ipgroup(fc_id => 16900017, rules => $rules, apptype => "internal", name => "UK Branch");
    
  • Modify the name of an existing group (Change existing “UK Branch” to “London Branch”)

    update_ipgroup(fc_id => 16900017, name => "London Branch");        # Where '16900017' is the exisiting "UK Branch" groups fc_id
    

delete_ipgroup

Remove an IP Group from the system or delete multiple groups at once.

  • Delete Multiple IP Groups

    delete_ipgroup(ipgroups => [{"id"=>"16800362"},{"id"=>"16800363"}]);        # Where the 'id' is the exisiting group's fc_id
    

delete_rule

Remove a rule from an IP Group: this can be used to remove a single IP from an IP Group that has many rules in it.

Note

The fc_id flag is required for this function. This value can be found in the output from search_ipgroups and passing the name.

search_ipgroups(name=>"Office", fc_name_comp => "like");      # Search for groups with name like 'Office'

Output:

{
  "allLoaded": 1,
  "page": 1,
  "totalRowCount": 1,
  "to": 0,
  "IPGroups": 1,
  "from": 0,
  "fc": {
    "algo_name": null,
    "fa_id": null,
    "numrules": "1",
    "fc_type_name": "ip_group",
    "fc_type": "ip_group",
    "use_in_reporting": 1,
    "ipg_type": "internal",
    "fc_name": "European Offices",                     # Name of the IP Group
    "has_fa_id": 0,
    "fc_type_id": 2,
    "fc_id": 16900019,                                 # The flow class ID for this group
    "modified_ts": "2018-02-27 14:36:10.433812",
    "is_internal": 1
  },
  "is_internal": "internal",
  "results": [{
    "childname": "UK Branch",                          # Name of the Child IP Group
    "child_id": "16900017",                            # The Child Group's flow class ID
    "fc_id": "16900019",                               # The parent flow class ID for this group
    "modified_ts": "2018-02-27 14:36:10.401185",
    "type": "child",
    "rule_id": "47"                                    # The ID of this specific flow class rule
    }
  ]
}
  • Delete a rule from an existing IP Group (Remove ‘UK Branch’ from ‘European Offices’)

    delete_rule(rule_id=>47);        # Where the '47' is the exisiting child group's rule_id from above
    

retrieve_rules

  • Retrieve rules for IP Group, 1000 entries per page

    retrieve_rules(fc_id=>16900014,page=>1,maxRows=>1000);
    
  • Retrieve rules for IP Group, 10 entries per page, starting from page=2

    retrieve_rules(fc_id=>16900014,page=>2,maxRows=>10);
    

    Note

    The fc_id flag is required for this function. This value can be found in the output from search_ipgroups and passing the name.

    search_ipgroups(name=>"My IP Group");
    

    Output:

    "results": [{
      "fc_name": "My IP Group",
      "fc_id": 16900014    # This is the Flow Class ID for this exisiting IP Group
    }]
    

Using the CLI

The command scrut_util.exe can also be leveraged as a CLI API.

The most common use case is importing data on a regular basis. To see options, call help via the CLI passing the mode.

$ ./scrut_util.exe –help import

Command

import

Usage

./scrut_util.exe –import aclfile ./scrut_util.exe –import asns [–file <path/file>] [–delimiter <delimiter>]

./scrut_util.exe –import csv_to_gps –file <csv_file> –group <group_id|group_name>

[–create_new] [–file_format <file_format>]

./scrut_util.exe –import csv_to_membership –file <csv_file>

[–create_new –grouptype <flash|google>] [–file_format <file_format>]

./scrut_util.exe –import hostfile ./scrut_util.exe –import ifinfo –file <ifinfo_file> [–delimiter <delimiter>] ./scrut_util.exe –import flowclass [–type [application|ipgroup]] [–file <path/file>] [–reset]

Description

Run various import commands to bring external sources of data into Scrutinizer. For more details on individual commands, type ‘help import <command>’ from interactive mode.