IP Groups API

The IP Groups API is a simple way to add, remove, and edit IP Groups.

Prerequisite

When using the API the following will be used on all requests:

authToken
The authentication token from Plixer Scrutinizer that allows access to API
rm
The runmode for accessing the API. It is specific to each section of the product. ipgroups will be used for each of the following examples
action
The list of available actions will change with each request. Below are the actions available within the user_api run mode
Action Description
saveRule Create a defined IP Group
update Re-define/modify an existing IP Group
loadTreeRootFast Load condensed list all IP Group names and IDs
search Search for an IP Group by name
loadRules View all rule definitions for an IP Group
deleteRule Remove a rule from an IP Group
delete Delete an IP Group
deleteAll Deletes all defined IP Groups from Scrutinizer

Rules

The IP Groups API provides the ability to define what makes the network traffic unique.

  • IP Host - one or multiple IPs can be used to define a rule
  • IP Range - use a range of IPs instead of multiple IP rules
  • IP Subnet - use a network subnet and mask of IPs instead of multiple IP rules or ranges
  • All IPs - specify every IP to be used in an IP Group definition
  • Wildcard Mask - specify a wildcard mask that will define hosts available for examination
  • Child Group - create a hierarchy of groups, with a child group being more specific than its parent.

Rule type examples

IP host

IP host - one or multiple IPs can be used to define a rule.

[
 {
  "type": "ip",
  "sip": "10.1.1.1"
  }
]
[
 {
  "type": "ip",
  "sip": "192.168.1.1"
 },
 {
  "type": "ip",
  "sip": "192.168.2.2"
 }
]

IP range

IP range - use a range of IPs instead of multiple IP rules

[
 {
  "type": "range",
  "sip": "10.1.1.1",
  "eip": "10.1.1.254"
 }
]

Note

the ‘range’ IP rule type requires a start IP (sip) and end IP (eip) to define the start and end of the range.

IP subnet

IP subnet - use a subnet and mask instead of multiple IP rules or ranges

[
 {
  "type": "network",
  "address": "192.168.0.0",
  "mask": "16"
 }
]

Note

A subnet rule uses the ‘network’ type. A subnet mask is required.

All IPs

All IPs - specify all IPs to be used in an IP Group definition

[
 {
  "type": "ipall",
  "all": 1
 }
]

Wildcard

Wildcard - specify a rule based on mask of bits that indicates which parts of an IP address are to be used for defining the IP Group hosts

[
 {
  "type": "wildcard",
  "address": "10.0.4.0",
  "mask": "0.255.0.255"
 }
]

Note

The example above will tag all hosts with the first octet of ‘10’ and third octet of ‘4’. Therefore IPs such as 10.1.4.1, 10.2.4.250, 10.99.4.98, etc. would be be included in the defined IP Group as the first and third octets match in the wildcard rule.

Child group

Child group - Nest IP Groups to create a hierarchy with a child groups’ rules being more specific than their parent.

[
 {
  "type": "child",
  "child_id": "16900062"
 }
]

Important

A child group definition is based on the parent group. Define smaller and more distinct child groups, then create the parent group so that you can add the child group that already exists.

  1. Create *UK Datacenter* and *UK Office* groups for their respective subnets/IPs.
  2. Create a parent group *UK* that will include child groups UK Datacenter and UK Office.
  3. Create *Germany Datacenter* and *Germany Office* groups for their respective subnets/IPs.
  4. Create a parent group *Germany* that will include child groups Germany Datacenter and Germany Office.
  5. Finally, create a parent group *European Offices* that will include child groups UK and Germany.

The workflow above will create the following hierarchy:

* European Offices         10.0.0.0/8
  ** UK                       10.30.0.0/16
        *** UK Datacenter           10.30.10.1/32
        *** UK Office               10.30.20.0/24
  ** Germany                   10.40.0.0/16
         *** Germany Datacenter      10.40.10.1/32
         *** Germany Office          10.40.20.0/24

Create an IP Group

When creating IP Groups with the API, use the saveRule action. There is 1 additional field that can be used:

new_fc
Provide a name for the IP Group.
added
Specify a Json array of rules to add to/define the IP Group.

Here is an example of how to use the added field for tagging a single IP address:

JSON object expected:

[
 {
  "type": "ip",
  "address": "10.1.4.66"
 }
]

Example API call

curl --location  --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken={{authToken}}' \
--form 'rm=ipgroups' \
--form 'action=saveRule' \
--form 'new_fc=UK Data Center' \
--form 'added=[
        {
                "type": "ip",
                "address": "10.30.10.1"
        }
]'

JSON object returned:

{
  "removed": [],
  "updated": [],
  "added": [
      {
          "rule_id": 506588,
          "cid": null,
          "type": "ip",
          "address": "10.30.10.1"
      }
  ],
  "warnings": [],
  "fc_id": 16900006,
  "myrules": "IP Address:10.30.10.1",
  "fc_name": "UK Datacenter",
  "rule_id": 506588,
  "total": 1
}

Update IP Group

You can update or remove existing rules or add new ones with one request. There are four additional fields that can be optionally used with the update action:

name
Optional. If specified, the name will be updated. Otherwise, the name of the IP Group remains unchanged.
added
Optional. Specify a Json array of rules to add to/define the IP Group.
updated
Optional. Specify a Json array of rules to modify the IP Group. The rule_id field must be defined to change a rule.

Important

When updating IP Groups, the rule type must remain the same. For example, you can not change an IP rule to a subnet rule. The workflow in that case is to remove the old rule type and create a new one.

removed
Optional. Specify a Json array of rule IDs to be removed.

Note

You can leave any of the [name|added|updated|removed] fields empty.

Here is an example of the added field for tagging traffic for a single IP address on a specific port:

[
 {
  "type": "ip",
  "address": "10.1.4.66"
 }
]

Use the updated field to change an existing rules:

[
 {
  "rule_id": "84",
  "type": "network",
  "address": "10.30.0.0",
  "mask": "16"
 }
]

Here is an example of the removed field syntax:

[ 81, 82, 83 ]

Note

The result of the three examples above would do the following:

  1. Create two new rules for the IP Group, an IP rule and a port rule.
  2. Update the rule with ID 84 to change IPs to match on.
  3. Remove rules 81, 82, and 83 that already existed in the IP Group definition.

Example API call

curl --location  --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken={{authToken}}' \
--form 'rm=ipgroups' \
--form 'action=update' \
--form 'fc_id={{new_ipgroup_fcid}}' \
--form 'name=Renamed Group' \
--form 'added=[
        {
                "type": "ip",
                "address": "10.1.4.66"
        }
]' \
--form 'updated=[
        {
                "rule_id": "84",
                "type": "ip",
                "address": "192.1.0.0"
        }
]' \
--form 'removed=[114]'

Search IP Groups

This feature is useful for searching Plixer Scrutinizer for IP Groups with a partial string or full name. Search for IP Groups with comparisons such as ” like ‘UK Office’ ” or ” notLike ‘Email Server’ “. There are four additional fields that you can use with the search action.

name
The name of the IP Group (or string) to find in Plixer Scrutinizer
fc_name_comp
Specify the comparison criteria for search results. Valid options are [like|notLike]
page
Default is 1, which would load the first page of pagination.
maxRows
The number of results per page returned in the API response.

Example API call

curl --location  --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken={{authToken}}' \
--form 'rm=ipgroups' \
--form 'action=search' \
--form 'name={{search_term}}' \
--form 'fc_name_comp={{search_type}}' \
--form 'page=1' \
--form 'maxRows=10'

Delete entry from an IP Group

Use this command to remove a single IP from a specific IP Group. The rule_id is required and can be obtained by viewing the rules of an IP Group. The update action also has an optional ‘removed’ field that can be used for deleting rules from an IP Group.

Example API call

curl --location  --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken={{authToken}}' \
--form 'rm=ipgroups' \
--form 'action=deleteRule' \
--form 'rule_id=506588'

JSON object returned:

{
  "fc_id": 16900006,
  "success": 1,
  "myrules": "",
  "rule_id": "506588",
  "total": 0
}

Delete IP Groups

You can remove more than one IP Group at a time by specifying more IDs in the array. There is an additional field that is required with the delete action:

json
Array of IP Group IDs to be deleted

For example, here’s how you define the json field for removing a single IP Group:

[
 {
  "id": "16900032"
 }
]

This is the json field for removing multiple IP Groups:

[
 {
  "id": "16900032"
 },
 {
  "id": "16900033"
 }
]

Example API call

curl --location  --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken={{authToken}}' \
--form 'rm=ipgroups' \
--form 'action=delete' \
--form 'json=[
        {
        "id": "16900032"
        }
]'

JSON object returned:

{
  "processedCount": 1,
  "removed": [
      "16900006"
  ]
}