IP Groups API¶

The IP Groups API functionality 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	Delete 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 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 the third octet of ‘4’. Therefore IPs such as 10.1.4.1, 10.2.4.250, 10.99.4.98, etc. would 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 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.

Create *UK Datacenter* and *UK Office* groups for their respective subnets/IPs.
Create a parent group *UK* that will include child groups UK Datacenter and UK Office.
Create *Germany Datacenter* and *Germany Office* groups for their respective subnets/IPs.
Create a parent group *Germany* that will include child groups Germany Datacenter and Germany Office.
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 an 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:

Create two new rules for the IP Group, an IP rule and a port rule.
Update the rule with ID 84 to change IPs to match on.
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 a 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"
  ]
}