APIs

Scrutinizer supports API access for the following function sets:

On this page:

Capture rule configuration

Capture rule configuration

IP group management

IP group management

Reporting

Reporting

User account management

User account management

Capture rule configuration

Selective packet capture (requires FlowPro) rules can be added via API, which requires the following fields:

• authToken - Admin authentication token generated by Scrutinizer (required for API access)

• rm - flowpro_capture_rules (runmode corresponding to the function set being accessed)

• name - Name to assign to the new capture rule

• server_ip - Packet source/server IP address or CIDR

• client_ip - Packet destination/client IP address or CIDR

• max_packets - Maximum number of packets to capture

• stops_on - End date/time for capturing packets as UNIX epoch timestamp

• well_known_port - Well-known port to monitor for packets

• retention_hours - Duration to store captured packet data

• enabled - State to add the rule in (1: enabled; 0: disabled)

• action - add (adds/creates a new capture rule as defined in the request)

Request example

New rule API call

curl --location 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=flowpro_capture_rules' \
--form 'name="LDAP Traffic 2"' \
--form 'server_ip="1.1.1.1/32"' \
--form 'client_ip="2.2.2.2/32"' \
--form 'max_packets="1000"' \
--form 'stops_on="1743048000"' \
--form 'well_known_port="393605"' \
--form 'retention_hours="168"' \
--form 'enabled="1"' \
--form 'action=add'

IP group management

The following fields are required for all IP group management API requests:

• authToken - Admin authentication token generated by Scrutinizer (required for API access)

• rm - ipgroups (runmode corresponding to the function set being accessed)

• action - One or more of the following actions to be initiated by the request:

  • saveRule - Creates an IP group with the specified rule

  • update - Modifies an existing IP group

  • loadTreeRootFast - Loads a condensed list of all IP group names and IDs

  • search - Searches for an IP group by name

  • loadRules - Loads a list of all rule definitions for an IP group

  • deleteRule - Removes a rule from an IP group

  • delete - Deletes an IP group

  • deleteAll - Deletes all IP group definitions from Scrutinizer

Rule definitions

Use the following JSON object formats to pass IP group inclusion rule definitions in requests:

Single IP address(es)

[
 {
  "type": "ip"
  "address": "<IP_ADDRESS_1>"
 },
 {
  "type": "ip"
  "address": "<IP_ADDRESS_2>"
 }
]

IP address range

[
 {
  "type": "range"
  "sip": "<START_IP>"
  "eip": "<END_IP>"
 }
]

Subnet

[
 {
  "type": "network"
  "address": "<ADDRESS>"
  "mask": "<SUBNET_MASK>"
 }
]

Wildcard mask

[
 {
  "type": "wildcard"
  "address": "<ADDRESS>"
  "mask": "<WILDCARD_MASK>"
 }
]

Child group

Child groups must be created before they can be added to parent groups.

[
 {
  "type": "child"
  "child_id": "<CHILD_IPGROUP_ID>"
 }
]

All IP addresses

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

Request examples

Below are additional details and request examples for IP group management API call action field.

saveRule

Creating new IP groups using the saveRule action requires the following additional fields:

• new_fc - Specifies a name for the new IP group

• added - Specifies a JSON array of one or more inclusion rule definitions to add to the new IP group

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=ipgroups' \
--form 'action=saveRule' \
--form 'new_fc=UK Data Center' \
--form 'added=[
    {
        "type": "ip",
        "address": "10.30.10.1"
    }
]'

Returned JSON object

{
  "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 Data Center",
  "rule_id": 506588,
  "total": 1
}

update

Modifying existing IP groups using the update action requires an fc_id field and accepts the following optional fields for adding, replacing, or removing rule definitions:

• name - Replaces the current name of the IP group if included

• added - Specifies a JSON array of one or more inclusion rule definitions to add to the IP group

• updated - Specifies a JSON array of rules (based on the included rule_id field) that will be overwritten with the new definitions provided

• removed - Specifies a JSON array of rule IDs to be deleted

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=ipgroups' \
--form 'action=update' \
--form 'fc_id=16900006' \
--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

Searching IP groups using the search action requires the following additional fields:

• name - IP group name or string to search for

• fc_name_comp - Specifies the comparison operator to search with (like or notlike)

• page - Specifies the number of pages of results to load (default: one page)

• maxRows - Specifies the maximum number of results per page in the response

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=ipgroups' \
--form 'action=search' \
--form 'name=UK' \
--form 'fc_name_comp=like' \
--form 'page=1' \
--form 'maxRows=10'

deleteRule

Deleting rule definitions using the deleteRule action requires the following additional field:

• rule_id - The ID of the rule definition to delete from its IP group

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=ipgroups' \
--form 'action=deleteRule' \
--form 'rule_id=506588'

Returned JSON object

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

delete

Deleting IP groups using the delete action requires an additional json field containing an array of IP group objects with id fields specifying the group IDs to be deleted.

API request example

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

Returned JSON object

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

Reporting

The following fields are required for all IP group management API requests:

• authToken - Admin authentication token generated by Scrutinizer (required for API access)

• rm - report_api (runmode corresponding to the function set being accessed)

• action - get (runs the report defined in the request)

• rpt_json - JSON object defining the parameters of the report to be run

• data_requested - Specifies the elements of the report to be included in the response

Report parameters

Each report API request must specify the parameters for the report using the following elements of the rpt_json object:

Parameter details

Object Element/Field	Report Parameter	Available Options	Example
reportTypeLang	Report type	conversations: Conversations WKP host2host: Host to host ipGroupGroup: IP group to IP group applications: Applications defined country2country: Country to country	json<br/>"reportTypeLang": "conversations"<br/>
filters	Exporter and interface filter	in_<EXPORTER_IP_HEX>_ALL: Includes all interfaces on the specified exporter in_<EXPORTER_IP_HEX>_<HEX_INTERFACE_N>: Includes interface index N	json<br/>"filters": {<br/>    "sdfDips_0": "in_0A190101_ALL"<br/>}<br/>
reportDirections	Traffic directionality (relative to interfaces included)	inbound or outbound	json<br/>"reportDirections": {<br/>    "selected": "inbound"<br/>}<br/>
times	Report time range/window and time zone to display dates in (use scrut_util --show tzlist for a list of valid timezones)	LastFiveMinutes LastTenMinutes LastFifteenMinutes LastTwentyMinutes LastThirtyMinutes LastFortyFiveMinutes LastHour LastFullHour LastThreeDays LastSevenDays LastThirtyDays Today Yesterday Last24Hours ThisWeek LastWeek ThisMonth LastMonth ThisYear LastYear Custom (requires additional start and end fields to specify)	json<br/>"times": {<br/>    "dateRange": "LastFiveMinutes",<br/>    "clientTimezone": "America/New_York"<br/>}<br/>
dataMode	Aggregation method to apply to collected data	saf (default) traditional (used for legacy support)	json<br/>"dataMode": {<br/>    "selected": "saf"<br/>}<br/>
rateTotal	Selects between rate (packets/s, bits/s, etc.) or total traffic in the report output	rate or total	json<br/>"rateTotal": {<br/>    "selected": "total"<br/>}<br/>
dataGranularity	Source data granularity	auto (API selects an appropriate source data bucket) 1m 5m 30m 2h 12h	json<br/>"dataGranularity": {<br/>    "selected": "auto"<br/>}<br/>
bbp	Selects the measurement units to use in the report output data	bits bytes percent (rateTotal provided is ignored)	json<br/>"bbp": {<br/>    "selected": "bits"<br/>}<br/>

Response data

The data_requested field specifies how to format the graph and table of the report output.

JSON object example

{
    "inbound": {
        "graph": "none",
        "table": {
            "query_limit": {
                "offset": 0,
                "max_num_rows": 10
            }
        }
    }
}

Note

The directionality specified in the data_requested object must match the reportDirections field.

Request example

The following API call runs a default report against all interfaces of the specified device for the last 5 minutes:

API request and response details

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=report_api' \
--form 'action=get' \
--form 'rpt_json=
{
    "reportTypeLang": "conversations",
    "filters": {
        "sdfDips_0": "in_0A190101_ALL"
    },
    "reportDirections": {
        "selected": "inbound"
    },
    "times": {
        "dateRange": "LastFiveMinutes"
        "clientTimezone": "America/New_York"
    },
    "dataMode": {
        "selected": "saf"
    },
    "rateTotal": {
        "selected": "total"
    },
    "dataGranularity": {
        "selected": "auto"
    },
    "bbp": {
        "selected": "bits"
    },
    "reportDirections": {
    {
        "type": "ip",
        "address": "10.30.10.1"
    }
}' \
--form 'data_requested'=
{
    "inbound": {
        "graph": "none",
        "table": {
            "query_limit": {
                "offset": 0,
                "max_num_rows": 10
            }
        }
    }
}'

Returned JSON object

The following condensed response shows the typical structure of the object returned for a report API request:

{
    "report": {
        "request_id": "0xed184820e4b611eab58f1fc02130f7f9",
        "table": {
            "inbound": {
                "totalRowCount": 1,
                "footer": [],
                "columns": [],
                "rows": []
            }
        },
        "time_details": {},
        "exporter_details": {},
        "graph": {}
    }
}

Field details:

Field	Sub-field	Description
table (will include separate data for inbound and outbound if applicable)	columns	elementName: Name of the data element in the column format: Formatting details for data in the column label: Table header label
	rows	rawValue: Unformatted value (as returned from the database) label: Formatted value including bits, bytes, or percent
	footer	[0]: Represents the Others data for a calculated column, which is the sum of the data in all rows not included in the table [1]: Represents Total for a calculated column, which is the sum of the data in all included rows plus the Others value for the same column
	totalRowCount	Integer specifying the total number of rows available
graph	all	Includes data for all graph types
	pie	Values for graphing table data as a pie chart
	timeseries	Values for graphing table data as a line graph
	none	Includes only default graph (pie) data

User account management

The following fields are required for all user account management API requests:

• authToken - Admin authentication token generated by Scrutinizer (required for API access)

• rm - user_api (runmode corresponding to the function set being accessed)

• action - One or more of the following actions to be initiated by the request:

  • createUser - Creates one or more new Scrutinizer user accounts with the option to assign each to user groups

  • delUsers - Deletes one or more user accounts

  • createUsergroup - Creates one or more user groups with the option to add users to each group

  • delUsergroups - Deletes one or more user groups

  • membership - Adds and/or removes users to or from specified user groups

  • prefs - Edits preferences for a single user

  • permissions - Edits permissions for one or more user groups

  • changeUsername - Renames an existing user account

Request examples

Below are additional details and request examples for the user account management API call action field.

createUser

Creating user accounts using the createUser action requires an additional json field containing an array (users) of the following:

• name - Username for the account

• pass - Password for the account

• membership - Array of one or more user group IDs to assign the user account to

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=createUser' \
--form 'json=
{
    "users": [
        {
            "name": "NewAdmin",
            "pass": "NewAdminPassword",
            "membership": [1]
        },
        {
            "name": "NewGuest",
            "pass": "NewGuestPassword",
            "membership": [2]
        }
    ]

}'

Returned JSON object

{
    "data": [
       {
           "id": 3,
           "name": "NewAdmin"
       },
       {
           "id": 4,
           "name": "NewGuest"
       }
    ]
}

Note

User group IDs are stored in the plixer.usergroups table. By default, 1 is the administrators group and 2 is the guest users group.

delUser

Deleting user accounts using the delUser action requires an additional json field containing an array (delUsers) of the usernames and/or user IDs of the accounts to be deleted:

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=delUser' \
--form 'json=
{
    "delUsers": [
        11,
        "NewGuest",
        207
    ]
}'

Returned JSON object

{
    "data": [
       "Deleting user id 11 (1 matched)",
       "Deleting user named 'NewGuest' (1 matched)",
       "Deleting user id 207 (0 matched)"
    ]
}

createUsergroup

Creating user groups using the createUsergroup action requires an additional json field containing an array (usergroups) of the following:

• name - User group name

• template_usergroup - Existing user group ID of the existing group to use as the template for the new user group

• users - Array of usernames or user IDs to be added to the group (if an empty array is passed, an empty user group will be created)

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=createUsergroup' \
--form 'json=
{
    "usergroups": [
        {
            "name": "My Group",
            "template_usergroup": 1,
            "users": [1,"AnotherUser"]
        },
        }
            "name": "Other Group",
            "template_usergroup": 2,
            "users": ["MyUser",2]
        }
    ]

}'

Returned JSON object

{
    "data": [
       {
           "id": 5,
           "name": "My Group",
           "members": [1,"AnotherUser"]
       },
       {
           "name": "Other Group",
           "error": "A usergroup already exists with that name"
       }
    ]
}

delUsergroups

Deleting user groups using the delUsergroups action requires an additional json field containing an array (delUsergroups) of the names and/or IDs of the user groups to be deleted.

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=delUsergroups' \
--form 'json=
{
    "delUsergroups": [
        3,
        "My User Group"
    ]
}'

Returned JSON object

{
    "data":[
       "Deleting usergroup id 3 (1 matched)",
       "Deleting usergroup named 'My User Group' (0 matched)",
    ]
}

membership

Editing user group membership using the membership action requires an additional json field containing add and/or remove arrays to specify the usernames/user IDs and user groups to add/remove them to/from.

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=membership' \
--form 'json=
{
    "membership":
    {
        "add": [
            {
                "user_id": 13,
                "usergroup_id": 5
            },
            {
                "user_name": "NewUser",
                "usergroup_name": "Other Group"
            }
        ],
        "remove": [
            {
                "user_name": "USER3",
                "usergroup_id": 4
            }
        ]
    }

}'

Returned JSON object

{
    "data":
        "added": [
            "User 13 added to usergroup 5",
            "User 14 added to usergroup 3"
        ],
        "removed": [
            "User 15 removed from usergroup 4"
        ]
}

prefs

The prefs action modifies one or more user preferences for a single user account and requires an additional json field containing an array (prefs) of all preference changes.

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=prefs' \
--form 'json=
{
    "user_id": 11,
    "prefs": [
        {
            "pref": "statsTopn",
            "setting": 10
        },
        {
            "pref": "language",
            "setting": "english"
        }
    ]
}

Returned JSON object

{
    "data": {
        "updated": [
            "statusTopn updated to 10 for user_id 11",
            "language updated to english for user_id 11"
        ],
        "errors": []
    }
}

permissions

The permissions action updates permissions for one or more user groups and requires an additional json field containing all user groups names/IDs and permission changes as add and remove arrays.

The following table lists all available permission_type and seccode (for use with the “plixer” permission_type) options in the request:

Permission Type	Value/Code	Description
permission_type	device	IP address of a device in hex (e.g. ‘0A010107’)
	interface	IP address of a device in hex and the interface index separated by a hyphen (e.g. ‘0A010107-1’)
	group	Group ID of a mapping/device group from plixer.groups
	report	saved_id of a saved report from reporting.saved_reports
	gadget	gadget_id of a dashboard gadget from plixer.dash_gadgets (e.g. ‘welcomeGadget’)
	thirdparty	ID of a third-party link from plixer.third_party
	plixer	Permission code corresponding to different functions/sections within Scrutinizer (see below)
seccode	3rdPartyIntegration	Create, edit, and delete third-party integration links
	ackBBEvent	Acknowledge alarms
	adminTab	Access the Admin tab/section
	alarmSettings	Configure alarm notifications
	alarmsTab	Access the Alarm Monitor tab/section
	allDevices	Access the status of all devices and their interfaces
	allGadgets	Access all gadgets created by any user
	allGroups	Access all mapping/device groups
	allInterfaces	Report on interfaces for any device
	allLogalotReports	All Logalot reports
	allReportFolders	Access all saved report folders
	allReports	Access all saved reports created by any user
	allThirdparty	Access all configured third-party links
	almDelete	Permanently delete alarms
	ApplicationGroups	Configure application groups
	asnames	Configure AS names
	auditing	Access auditing reports containing logs of Scrutinizer user actions
	auth	Manage external authentication tokens
	Authentication	Manage external authentication types
	authLdapServers	Manage LDAP server configuration for Scrutinizer authentication
	awsSettings	AWS configuration
	changeUserPasswords	Change passwords for other users without needing their credentials
	createDashTabs	Create new dashboards
	createUsers	Create new local Scrutinizer user accounts
	dashboardAdmin	Manage all dashboards created by any user
	DataHistory	Configure data history/retention settings
	deleteReport	Delete saved reports regardless of owner
	deleteUsers	Delete local Scrutinizer user accounts
	DeviceDetails	Edit device interface details
	EmailNotifications	Configure the mailserver for Scrutinizer reports and emails
	faExclusions	Configure flow analytics exclusions
	fa_mgmt_link	Configure flow analytics thresholds and settings
	feedbackForm	Access the link to send feedback to Plixer
	FlowAnalyticsSettings	Access global flow analytics settings
	helpTab	Access the Help tab/section
	HostNames	Edit hostname information
	IPGroups	Configure Scrutinizer IP groups
	language	Create and edit language localization settings
	licensing	Configure Scrutinizer product licensing and features
	LogalotPrefs	Configure global alarm settings
	MACAddresses	Configure device MAC address information
	ManageCollectors	Manage devices collecting flow data for Scrutinizer
	ManageExporters	Manage devices exporting flow data to Scrutinizer
	mappingGroupConfiguration	Create and edit mapping/device groups
	mappingObjectConfiguration	Create and edit mapping objects
	mapsTab	Access the Network Maps page
	myViewTab	Access the Dashboards page
	NotificationManager	Manage alarm notifications
	PolicyManager	Manage alarm policies
	protocolExclusions	Edit protocol exclusions for flow reports
	proxySettings	Configure proxy server settings in Scrutinizer
	radiusConf	Manage RADIUS server configuration for Scrutinizer authentication
	ReportDesigner	Design new custom report types
	reportFilters	Update the filters used in reports
	reportFolders	Manage saved report folders
	reportSettings	Reporting engine configuration options
	runReport	Run flow reports
	saveReport	Name and save flow reports
	scheduledReports	Create, edit, and delete scheduled email reports
	sf_asa_acls	Configure ASA ACL descriptions
	SNMPCredentials	Manage SNMP credentials for polling device information
	srCreate	Schedule saved reports to be emailed on a regular basis
	sso	Add, delete, and edit Identity Provider configurations for Single Sign-On integration
	statusTab	Access the Status tab
	syslogNotifications	Syslog server configuration
	SystemPreferences	Administrative access to global Scrutinizer preferences
	tacacsConf	Manage TACACS+ server configuration for Scrutinizer authentication
	tos	Edit TOS configuration
	userAccounts	Admin access to the user management page
	usergroups	Manage Scrutinizer user groups
	viewUserIdentity	View identity and access information relevant to GDPR restrictions
	viptelaSettings	Configure Viptela settings
	Vitals	View Scrutinizer server vitals reports
	wkp	Edit WKP configuration

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=permissions' \
--form 'json=
{
    "permissions":
    {
        "add": [
            {
                "usergroup_name": "Dashboarders",
                "permission_type": "device",
                "seccode": "0A010107"
            }
        ],
        "remove": [
            {
                "usergroup_name": "ReadOnlyReporters",
                "permission_type": "plixer",
                "seccode": "allGadgets"
            }
        ]
    }

}'

Returned JSON object

{
    "data":
    {
        "errors": []
        "updated": [
            "Added device permission 0A010107 to usergroup 26",
            "Removed plixer permission allGadgets from usergroup 27"
        ]
    }
}

changeUsername

The changeUsername action is used to edit the name of an existing user account and requires an additional json field specifying the account (by oldname or user_id) and the new name.

API request example

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--form 'authToken=<AUTH_TOKEN>' \
--form 'rm=user_api' \
--form 'action=changeUsername' \
--form 'json=
{
    "changeUsername":
    {
        "oldname": "MyUser",
        "newname": "OpSCT"
    }

}'

Returned JSON object

{
    "data":
    {
        "message": "User MyUser successfully renamed to OpSCT"
    }
}