Create

This method allows you to create a new node group group.

Method URL
POST /api/v2/node_groups.json

Parameters

Param Type Required Notes
name string Yes The name that will be used to identify the node_group group within UpGuard
description string No Describe what belongs in this group and how it is used

Example Submitted Payload

{
    "node_group": {
        "name": "IIS",
        "description": "All IIS servers",
        "node_rules": "^IIS"
    }
}

Example Response

Code Status
201 Created

Response JSON

{
    "organisation_id": 123,
    "name": "IIS",
    "description": "All IIS servers",
    "node_rules": "^IIS"
}

Show

This method returns details of the node group, specified by the ID given in the URL.

Method URL
GET /api/v2/node_groups/[node_group_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
  "created_at": "2015-08-18T13:53:59-11:00",
  "description": "Node group containing Windows nodes",
  "diff_notify": false,
  "external_id": null,
  "id": 5,
  "name": "Windows",
  "node_rules": null,
  "organisation_id": 3,
  "owner_id": 12,
  "scan_options": "{ ... }",
  "search_query": [
    {
      "type": "info",
      "typeQuery": "platform",
      "attr": "scanned_operating_system_family",
      "attrQuery": "Windows",
      "exact": true
    }
  ],
  "status": 1,
  "updated_at": "2016-05-25T03:53:28-11:00"
}

Index

This method returns a list of node groups registered to the organization.

Method URL
GET /api/v2/node_groups.json
GET /api/v2/node_groups.json?page=1&per_page=2

Parameters

Param Type Required Notes
page integer No Displays results based on specified page number (default 1, 1-indexed).
per_page integer No Number of results per page (defaults to 20 results).

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 311,
        "organisation_id": 123,
        "name": "IIS",
        "description": "All IIS servers",
        "node_rules": "^IIS"
        "url": "https://app.upguard.com/api/v2/node_groups/311"

    },
    {
        "id": 312,
        "organisation_id": 123,
        "name": "MySQL",
        "description": "All MySQL servers",
        "node_rules": "^SQL"
        "url": "https://app.upguard.com/api/v2/node_groups/312"
    }
]

New

This method returns a skeleton payload format that can subsequently be submitted to create a new node group.

Method URL
GET /api/v2/node_groups/new.json

Example Response

Code Status
200 OK

Example Response JSON

{
    "node_group": {
        "name": null,
        "description": null,
        "node_rules": null
    }
}

Lookup

This method allows you to lookup the Node Group ID by name.

Method URL
GET /api/v2/node_groups/lookup.json?name=[node_group_name]

Example Response

Code Status
200 OK

Example Response JSON

{
    "node_group_id": 123
}

Error Cases

Code Status Cause
404 Not Found There are no node groups in your account that match the search parameters.
422 Unprocessable Entity No supported search parameters were found in the request. You need to supply ‘name=’ as a method parameter.

Add Node

This method allows you to add a node to the node group.

Method URL
POST /api/v2/node_groups/[node_group_id]/add_node.json?node_id=[node_id]

Parameters

Param Type Required Notes
node_id integer Yes The id of the node you wish to attach

Example Response

Code Status
201 Created

Example Response JSON

{
    "created_at": "2013-12-18T14:48:31-08:00",
    "id": 87,
    "node_group_id": 199,
    "node_id": 101,
    "updated_at": "2013-12-18T14:48:31-08:00"
}

Add Nodes

This method allows you to add nodes to the node group.

Method URL
POST /api/v2/node_groups/[node_group_id]/add_nodes.json?node_ids[]=1&node_ids[]=2

Parameters

Param Type Required Notes
node_ids integers Yes The ids of the nodes you wish to attach

Example Response

Code Status
201 Created

Example Response JSON

[{
    "created_at": "2013-12-18T14:48:31-08:00",
    "id": 87,
    "node_group_id": 199,
    "node_id": 101,
    "updated_at": "2013-12-18T14:48:31-08:00"
},{
    "created_at": "2013-12-18T14:48:31-08:00",
    "id": 88,
    "node_group_id": 199,
    "node_id": 103,
    "updated_at": "2013-12-18T14:48:31-08:00"
}]

Compare Nodes

This method allows you to compare the nodes in the node group to each other.

Method URL
POST /api/v2/node_groups/[node_group_id]/compare_nodes.json?node_id=[node_id]

Parameters

Param Type Required Notes
node_id integers No The id of the node you wish to use as the base. If none given it will select the first in the group.

Example Response

Code Status
200 OK

Example Response JSON

{
    "node_group_id": 24,
    "nodes": [{"node_id":748,"node_name":"node_2", ... }],
    "totals": {
        "total":358,
        "added":0,
        "deleted":0,
        "updated":1,
        "type": {
            "packages": {
                "total": 358,
                "added": 0,
                "deleted": 0,
                "updated": 1
            }
        }
    }
}

Remove Node

This method allows you to remove a node from the node group.

Method URL
POST /api/v2/node_groups/[node_group_id]/remove_node.json?node_id=[node_id]

Parameters

Param Type Required Notes
node_id integer Yes The id of the node you wish to remove

Example Response

Code Status
204 No Content

Nodes

This method returns a list of nodes in the node group.

Method URL
GET /api/v2/node_groups/[node_group_id]/nodes.json
GET /api/v2/node_groups/[node_group_id]/nodes.json?page=1&per_page=2

Parameters

Param Type Required Notes
page integer No Displays results based on specified page number (default 1, 1-indexed).
per_page integer No Number of results per page (defaults to 20 results).

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 311,
        "name": "ugv2laptop",
        "description": "Unmanned Ground Vehicle 1 Laptop",
        "url": "https://upguard/api/v2/nodes/311"
    },
    {
        "id": 439,
        "name": "solarisbox",
        "description": "Solaris Intel Testing box 34",
        "url": "https://upguard/api/v2/nodes/439"
    }
]

Add Policy Version

This method allows you to add a policy version to the node group.

Method URL
POST /api/v2/node_groups/[node_group_id]/add_policy_version.json?policy_version_id=[policy_version_id]

Parameters

Param Type Required Notes
policy_version_id integer Yes The id of the policy version you wish to attach.

Example Response

Code Status
201 Created

Example Response JSON

{
    "created_at": "2013-12-18T14:48:31-08:00",
    "id": 87,
    "node_group_id": 199,
    "policy_version_id": 101,
    "updated_at": "2013-12-18T14:48:31-08:00"
}

Policy Versions

This method allows you to list all policy versions attached to this node group.

Method URL
GET /api/v2/node_groups/[node_group_id]/policy_versions.json

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 311,
        "name": "MySQL Config",
        "version": 2,
        "url": "https://app.upguard.com/api/v2/policy_versions/17.json",
        "organisation_id": 33
    }
]

Node Group Configuration

This method allows you to view the current configuration for the node group

Method URL
GET /api/v2/node_groups/[node_group_id]/node_group_configuration.json

Example Response

Code Status
200 OK

Example Response JSON

{
    "ignore_items": null,
    "scan_options": {
        "scan_directory_options": [{
            "path": "/var/logs",
            "contents": false
        },
        {
            "path": "/etc/ssh/",
            "contents": true
        }],
        "registry_keys": [
            "HKCU:\a\registry\key",
            "HKLM:\another\registry\key"
        ],
        "group_policy_objects": [
            "gpo1",
            "gpo2"
        ],
        "sql_queries": [{
            "db_label": "an sql query",
            "label": "the description",
            "query": "SELECT * FROM CUSTOMERS"
        },
        {
            "db_label": "another sql query",
            "label": "another description",
            "query": "SELECT * FROM CUSTOMERS WHERE ORDERS = 2"
        }],
        "powershell_queries": [{
            "description": "a query",
            "key_name": "",
            "query": "hostname"
        },
        {
            "description": "another query",
            "key_name": "red",
            "query": "Get-Childitem C:WindowsSystem32 | Sort"
        }],
        "scripts": [{
            "description": "a script",
            "script": "whoami"
        },
        {
            "description": "another script",
            "script": "find . -name '*conf'"
        }],
        "scan_ports": {
            "tcp": "",
            "udp": ""
        },
        "scan_diff_excluded_text": []
    },
    "policies": []
}

Set Scan Options

This method allows you to update the scan options for a specified node group by its id. This method accepts only one scan option key at a time for updating the scan options.

Method URL
PUT /api/v2/node_groups/[node_group_id]/set_scan_options.json
Keys Corresponding Options
connectivity Tests for a defined host and port to determine connectivity
scan_directory_options Directories that will be scanned for files
scan_diff_excluded_text Text to be excluded during differencing (accepts Regex)
registry_keys Registry keys that will be scanned (Windows Only)
group_policy_objects Group Policy objects that will be scanned (Windows Only)
sql_queries SQL queries to run and scan for the node group (Windows Only)
powershell_queries SQL queries that will be run and scanned (Windows Only)
scripts Custom Scripts that will be run and scanned (Linux Only)
scan_ports Ports to be scanned
web Web Scan Options
cis_bl CIS Benchmark Blacklist

Example Request Body

The format to forming the request body is made up of two keys:

  1. option_name defines the scan option key that you will be setting,
  2. Followed by the key name from the table above, which contains an array list of objects with their respective settings for each of the keys.

We have provided examples for forming the request body below. Should you need more information on what the scan options should look like, the Node Group Configuration method will be helpful in showing you what the scan options look like in JSON format.

Example: Connectivity

{
    "option_name": "connectivity",
    "connectivity": [
          {
            "protocol": "TCP",
            "host": "8.8.8.8",
            "port": "22"
          }
        ]
}

Example: Scan Directory Options

{
    "option_name": "scan_directory_options",
    "scan_directory_options": [
            {
              "path": "/var/usr"
              "contents": false
            },
            {
              "path": "/var/usr/test.txt",
              "contents": true
            }
        ]
}

Example: Scan Difference Excluded Text

{
    "option_name": "scan_diff_excluded_text",
    "scan_diff_excluded_text": [
          "verison\\s\\d+",
          "some more text",
          "other text"
        ]
}

Example: Registry Keys

{
    "option_name": "registry_keys",
    "registry_keys": [
          "HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\services\\Tcpip\\Parameters\\DataBasePath"
        ]
}

Example: Powershell Queries

{
    "option_name": "powershell_queries",
    "powershell_queries": [
          {
              "description": "Script Description",
              "key_name": "name",
              "query": "Get-Content C:\\..."
          }
        ]
}

Example: SQL Queries

{
    "option_name": "sql_queries",
    "sql_queries": [
          {
            "label": "Query Description",
            "db_alias": "db_alias",
            "query": "SELECT * from table;"
          }
        ]
}

Example: Custom Scripts

{
    "option_name": "scripts",
    "scripts": [
          {
            "description": "Script description",
            "script": "ps -ef"
          }
        ]
}

Example: Scan Ports

{
    "option_name": "scan_ports",
    "scan_ports": [
          {
            "protocol": "TCP",
            "port": "1-1024"
          },
          {
            "protocol": "UDP",
            "port": "1-1024"
          }
        ]
}

Example: Web

{
    "option_name": "web",
    "web": [
        {
          "url": "upguard.com",
          "label": "UpGuard Website",
          "verb": "GET",
          "contents": true
        }
      ]
}

Example: CIS Benchmark BlackList

{
    "option_name": "cis_bl",
    "cis_bl": [
        "xccdf_org.cisecurity.benchmarks_rule_1.1.1_L1_Set_Enforce_password_history_to_24_or_more_passwords",
        "xccdf_org.cisecurity.benchmarks_rule_1.1.1_Create_Separate_Partition_for_tmp",
    ]
}

Example Response

Code Status
200 OK

Example Response JSON

The response will echo the request body you send to the server. Examples have already provided above in the various sample request bodies.

Scan

This method allows you to trigger a scan of a node group by specifying the node group’s ID.

Method URL
POST /api/v2/node_groups/[node_group_id]/scan

Example Response

Code Status
200 OK

Example Response JSON

{
  "id": 39899,
  "organisation_id": 4,
  "status": 0,
  "created_by": 5,
  "updated_by": 5,
  "source_id": 44,
  "source_name": "CISCO Devices",
  "source_type": 13,
  "upload_node_id": 0,
  "created_at": "2017-07-24T10:29:59.735-07:00",
  "updated_at": "2017-07-24T10:29:59.735-07:00",
  "scheduled_job_id": null,
  "stats": null,
  "diff_stats": null
}
Tags: node groups