Node Types

Node type can be one of the following values:

Code Type
SV Server
DT Desktop
SW Network Switch
FW Firewall
RT Router
PH Smart Phone
RB Robot
SS SAN Storage
WS Website

Medium Types

Medium type can be one of the following values:

Value Type
1 AGENT
3 SSH
6 HTTPS
7 WINRM
8 SERVICE
9 WEB

Status Codes

The status codes will be reflected in various methods through the attributes such as last_scan_status. The named string values of the status codes are also used for the status parameters under Index.

Code Status String
0 PENDING
1 PROCESSING
2 SUCCESS
3 ASSIGNED
5 ACTIONED
9 FAILURE
10 OFFLINE
20 CANCELLED
55 TIMEOUT
88 ERROR
99 EXCEPTION

Index

This method returns a list of nodes registered to the organization.

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

Parameters

Param Type Required Notes
status string No Permitted values: active, deleted
last_scan_status string No Permitted values: all_failures, and see Status Codes
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,
        "environment_id": 2,
        "node_type": "RB",
        "name": "ugv2laptop",
        "mac_address": null,
        "ip_address": "192.168.155.200",
        "short_description": "",
        "operating_system_family_id": 1,
        "operating_system_id": 111,
        "external_id": "CMDB001",
        "online": true,
        "url": "https://app.upguard.com/api/v2/nodes/311.json"
    },
    {
        "id": 439,
        "environment_id": null,
        "node_type": "SV",
        "name": "solarisbox",
        "mac_address": null,
        "ip_address": "192.168.155.200",
        "short_description": "",
        "operating_system_family_id": 3,
        "operating_system_id": 331,
        "external_id": "CMDB002",
        "online": false,
        "url": "https://app.upguard.com/api/v2/nodes/439.json"
    }
]

Show

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

Method URL
GET /api/v2/nodes/[node_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
  "alternate_password": null,
  "connect_mode": "f",
  "connection_manager_group_id": 1,
  "created_at": "2016-04-01T09:33:29-07:00",
  "created_by": 5,
  "description": null,
  "environment_id": 2,
  "external_id": null,
  "id": 1,
  "info": {
    "agent_version": null,
    "architecture": "x86_64",
    "hostname": "MacbookPro.local",
    "ipaddress": "192.168.140.144",
    "os_release_version": "15.3.0",
    "osfamily": "Darwin",
    "timezone": "PDT"
  },
  "ip_address": "192.168.150.140",
  "last_scan_id": 43,
  "last_scan_status": 2,
  "mac_address": null,
  "medium_connection_fail_count": 0,
  "medium_group": null,
  "medium_hostname": "192.168.102.120",
  "medium_password": null,
  "medium_port": 22,
  "medium_ssl_cert": null,
  "medium_ssl_privkey": null,
  "medium_type": 3,
  "medium_username": "user",
  "name": "MacbookPro",
  "node_type": "SV",
  "online": false,
  "operating_system_family_id": 5,
  "operating_system_id": 511,
  "organisation_id": 2,
  "primary_node_group_id": 0,
  "scan_options": null,
  "short_description": "",
  "status": 1,
  "updated_at": "2016-04-11T14:41:08-07:00",
  "updated_by": 5,
  "url": null,
  "uuid": "7c32a5a55-c57e-4c49-a84f-7f64asdfb404"
}

New

This method returns a skeleton payload format that can subsequently be submitted to create a new node (See Create).

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

Example Response

Code Status
200 OK

Example Response JSON

{
    "node": {
        "organisation_id": 123,
        "name": null,
        "mac_address": null,
        "node_type": null,
        "environment_id": null,
        "operating_system_family_id": null,
        "operating_system_id": null,
        "medium_type": 1,
        "medium_username": null,
        "medium_hostname": null,
        "medium_port": null,
        "external_id": null
    }
}

Create

This method allows you to register a new node.

Method URL
POST /api/v2/nodes.json

Parameters

Param Type Required Notes
name string Yes The hostname of the node
mac_address string No The MAC address of the main network device
node_type string Yes See Node Type table above
environment_id int No Use environments index to list environment IDs
operating_system_family_id int No Use Operating System Families index to list IDs
operating_system_id int No Use Operating System index to list IDs
medium_type int No The connection type (see Medium Types table)
medium_username string No If using SSH or WinRM, the username
medium_password string No If using SSH or WinRM, the password
medium_hostname string No If using SSH or WinRM, the hostname
medium_port int No If omitted, defaults to 22 for SSH and 5985 for WinRM
external_id string No ID used in an external system such as a CMDB
connection_manager_group_id int No ID of the connection manager group to assign the node to
short_description string No Description of node

Example Response

Code Status
201 Created

Example Response JSON

{
  "id": 4,
  "organisation_id": 2,
  "environment_id": 2,
  "node_type": "SV",
  "name": "PROD_MACHINE_01",
  "short_description": null,
  "description": null,
  "operating_system_family_id": null,
  "operating_system_id": null,
  "connect_mode": "f",
  "online": false,
  "status": 1,
  "updated_by": 1,
  "created_by": 1,
  "created_at": "2016-04-13T10:15:51-07:00",
  "updated_at": "2016-04-13T10:15:51-07:00",
  "uuid": "4c218618-52b3-4360-9c8e-301713993b38",
  "mac_address": null,
  "info": null,
  "medium_hostname": null,
  "medium_username": null,
  "medium_port": 0,
  "ip_address": null,
  "medium_connection_fail_count": 0,
  "medium_password": null,
  "medium_type": 1,
  "scan_options": null,
  "external_id": null,
  "last_scan_status": null,
  "medium_group": null,
  "medium_ssl_privkey": null,
  "medium_ssl_cert": null,
  "url": null,
  "connection_manager_group_id": null,
  "alternate_password": null,
  "last_scan_id": null,
  "primary_node_group_id": null
}

Update

This method allows you to update properties of a node.

Method URL
PUT /api/v2/nodes/[node_id].json

Example Submitted Payload

{
    "node": {
        "node_type": "RB"
    }
}

Example Response

Code Status
204 No Content

Destroy

This method allows you to delete a node from your account.

Method URL
DELETE /api/v2/nodes/[node_id].json

Example Response

Code Status
204 No Content

Look Up

This method allows you to lookup the Node ID of a registered node in our account based on either the name of the node or the SSH username and hostname (and optionally the port) fields of the node. If no port is specified, defaults to 22 as the port search parameter.

Method URL
GET /api/v2/nodes/lookup.json?name=[node_name]
GET /api/v2/nodes/lookup.json?external_id=[external_id]
GET /api/v2/nodes/lookup.json?ssh_hostname=[hostname]&ssh_username=[username]
GET /api/v2/nodes/lookup.json?ssh_hostname=[hostname]&ssh_username=[username]&ssh_port=[port]

Example Response

Code Status
200 OK

Example Response JSON

{
  "node_id": 123
}

Error Cases

Code Status Cause
404 Not Found There are no nodes in your account that match the search parameters.
422 Unprocessable Entity No supported search parameters were found in the request. You need at least a name, an external_id, or both of ssh_hostname and ssh_username as method parameters.

Add To Node Group

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

Method URL
POST /api/v2/nodes/[node_id]/add_to_node_group.json?node_group_id=[node_group_id]

Parameters

Param Type Required Notes
node_group_id integer Yes The id of the node group to add the node to.

Example Response

Code Status
201 Created

Example Response JSON

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

Remove From Node Group

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

Method URL
POST /api/v2/nodes/[node_id]/remove_from_node_group.json?node_group_id=[node_group_id]

Parameters

Param Type Required Notes
node_group_id integer Yes The id of the node group to remove the node from.

Example Response

Code Status
204 No Content

Node Groups

This method returns a list of node groups the node belongs to.

Method URL
GET /api/v2/nodes/[node_id]/node_groups.json

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 311,
        "organisation_id": 123,
        "name": "IIS",
        "description": "All IIS servers",
        "node_rules": "^IIS"
    },
    {
        "id": 312,
        "organisation_id": 123,
        "name": "MySQL",
        "description": "All MySQL servers",
        "node_rules": "^SQL"
    }
]

Add Policy Version

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

Method URL
POST /api/v2/nodes/[node_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_id": 199,
    "policy_version_id": 101,
    "updated_at": "2013-12-18T14:48:31-08:00"
}

Policy Versions

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

When invoked in its default form (without the inherited parameter) or with inherited=true, returns all policy versions that are assigned directly to the node and those assigned to the node via a node group the node is a member of. If you just want policy versions attached to this node only, specify inherited=false.

Method URL
GET /api/v2/nodes/[node_id]/policy_versions.json
GET /api/v2/nodes/[node_id]/policy_versions.json?inherited=false

Example Response

Code Status
200 OK

Example Response JSON

Here there are two policy versions attached to the node. The first (id=311) is directly attached to the node itself and therefore is not inherited (inherited=false). The second policy version (id=321) is attached to the node via the node’s node group and is therefore inherited (inherited=true).

[
    {
        "id": 311,
        "name": "MySQL Schema",
        "version": 1,
        "attached_to": "https://guardrail.scriptrock.com/api/v2/nodes/22.json",
        "inherited": false,
        "url": "https://guardrail.scriptrock.com/api/v2/policy_versions/3.json",
        "organisation_id": 33
    },
    {
        "id": 321,
        "name": "MySQL Config",
        "version: 1",
        "attached_to": "https://guardrail.scriptrock.com/api/v2/node_groups/24.json",
        "inherited": true,
        "url": "https://guardrail.scriptrock.com/api/v2/policy_versions/17.json",
        "organisation_id": 33
    }
]

If this same API method were to be called with inherited=false, the response body would contain the following JSON.

[
    {
        "id": 311,
        "name": "MySQL Schema",
        "version": 1,
        "attached_to": "https://guardrail.scriptrock.com/api/v2/nodes/22.json",
        "inherited": false,
        "url": "https://guardrail.scriptrock.com/api/v2/policy_versions/3.json",
        "organisation_id": 33
    }
]

Start Scan

This method allows you to kick off a Node Scan against this node.

Method URL
POST /api/v2/nodes/[node_id]/start_scan.json?label=[label]

Parameters

Param Type Required Notes
label string No The label you wish to tag a scan with (can include spaces).

Example Response

Code Status
201 Created

Example Response JSON

{
  "job_id": 1337
}

Here the job_id is the ID of a job that can be queried by an HTTP GET to the Job Show method.

Example PowerShell Script

Below is a PowerShell script that can be used to trigger scans for all nodes in a node group. This can be useful for integrating with deployment tools to provide configuration visibility pre- and post-deployment.

Scan Details

This method allows you to retrieve scan details from the latest Node Scan for the node.

Method URL
POST /api/v2/nodes/[node_id]/scan_details

Parameters

Param Type Required Notes
scan_id integer No The id of the scan you would like to retrieve
scan_label integer No The label of the scan you would like to retrieve (if there are multiple matches it will return the most recent).

Example Response

Code Status
200 OK

Example Response JSON

{
    "id": 1337,
    "label: "Change 2001",
    "status": 0,
    "data": {"packages": ... },
    "created_at": "2015-09-14T05:02:12Z",
    ...
}

Last Scan Status

This method allows you to look up the task status and task report of the last node scan run on this node.

Method URL
GET /api/v2/nodes/[node_id]/last_scan_status.json

Example Response

Code Status
200 OK

This example shows the response for a node that has been successfully scanned.

{
  "status": 2,
  "status string": "success",
  "report": "[{\"generate_node_scan\":{\"number_of_packages_found\":\"96\",\"number_of_files_found\":\"5\",\"number_of_services_found\":\"153\",\"number_of_users_found\":\"2\",\"number_of_groups_found\":\"25\",\"number_of_ports_found\":\"64\",\"number_of_environment_variables_found\":\"34\",\"result\":\"success\",\"messages\":[]}},{\"upload_node_scan\":{\"result\":\"success\",\"node_id\":\"174\",\"http_response_code\":\"201\",\"http_response_body\":\"\",\"messages\":[]}}]\"
}

This example shows the response for a node that has never been scanned.

{
    "status": null,
    "status string": "Has never been scanned",
    "report": "[]"
}

Last Successful Scan Job

This method allows you to look up the details of the last successful scan job that was run against the specified node.

Method URL
GET /api/v2/nodes/[node_id]/last_successful_scan.json

Example Response

Code Status
200 OK

This example shows the response for a node that has been successfully scanned.

{
    "status": 2,
    "status_string": "success",
    "report": "[{\"detect_os\":{\"messages\":[],\"result\":\"success\"}},{\"generate_blueprint\":{\"messages\":[],\"result\":\"success\"}},{\"upload_blueprint\":{\"messages\":[],\"result\":\"success\"}}]",
    "created_at": "2015-06-09T10:14:52-07:00",
    "updated_at": "2015-06-09T10:15:19-07:00"
}

This example shows the response for a node that has never been scanned.

{
    "status": null,
    "status string": "Has never been scanned",
    "report": "[]"
}

Last Node Scan Details

This method allows you to retrieve information about the last scan that was performed on the specified node.

Method URL
GET /api/v2/nodes/[node_id]/last_node_scan_details[?with_data=true]

Parameters

Param Type Required Notes
with_data boolean No If true, will retrieve verbose output from the last scan.

Headers

Header Values Notes
Accept application/json, text/csv Will return the scan details as either JSON or CSV respectively.

Example Responses

Code Status
200 OK
404 Not Found

This example shows the response generated from requesting basic scan information from a node.

{
    "associated_id": null,
    "category": 0,
    "created_at": "2015-02-27T11:29:04-08:00",
    "id": 115,
    "label": null,
    "node_id": 2228,
    "scan_options": "{\"scan_directories\":[\"/etc/**/*\"],\"scan_ports\":{\"tcp\":\"1-1024\",\"udp\":\"1-1024\"}}",
    "status": 1,
    "task_id": 910,
    "updated_at": "2015-02-27T11:29:04-08:00"
}

This example shows the response for a node that has never been scanned. It is accompanied be a response status of 404.

{
    "error": "No scans found"
}

Example Python Script

Diff

This method allows you to perform diff operations against nodes and specific node scans.

Method URL - Diff Last
GET /api/v2/nodes/diff.json?[parameters]

Example Response

Code Status
200 OK

Parameters

Param Type Required Notes
node_id integer No The id of the node to be used for diff (last scan will be used).
compare_node_id integer No The id of the node to be used for comparing to node_id (last scan will be used).
scan_id integer No The id of the scan to be used for diff.
compare_scan_id integer No The id of the scan to be used for comparing to scan indicated by scan_id.

There are 3 types of diffs you can perform using the parameters listed above:

  1. A “diff last” style diff where you simply supply a node_id and it will generate a diff based on the 2 previous scans for that node
  2. A “node to node” style diff where you supply 2 node id’s and the most recent scan for those two nodes will be compared
  3. A “scan to scan” style diff where you supply 2 scan id’s and they will be compared.

Example Paths

Method Diff Style URL
GET Diff Last /api/v2/nodes/diff.json?node_id=50
GET Node To Node /api/v2/nodes/diff.json?node_id=50&compare_node_id=60
GET Scan To Scan /api/v2/nodes/diff.json?scan_id=100&compare_scan_id=200

Group Diff

This method allows you to perform group diff operations against nodes, or node groups.

Method URL - Diff Last
GET /api/v2/nodes/group_diff.json[parameters]

Example Response

Code Status
200 OK

Sample JSON return body is omitted due to size of JSON data object.

Parameters

Param Type Required Notes
node_ids integer No The ids of the nodes to be used for diff (latest node scan will be used).
node_group_ids integer No The ids of the node groups to be used for diff (latest node group scan will be used).
show_ignored boolean No The boolean is set to true to show the ignored data in the diff nodes. (default: false)
show_difference boolean No The boolean is set to true to show the differences between the diff nodes. (default: false)

There are 2 types of diffs you can perform using the parameters listed above:

  1. A “grouped nodes” style diff where you supply any number of node id’s and the most recent scan for those nodes will be compared
  2. A “node group to node group” style diff where you supply any number of node group id’s and the most recent scan for those node groups will be compared.

Example Paths

Method Diff Style URL
GET Diff Between Nodes /api/v2/nodes/group_diff.json?node_ids=1,2,3,4,5,6
GET Diff Between Node Groups /api/v2/nodes/group_diff.json?node_group_ids=2,4
GET Ignored Items /api/v2/nodes/group_diff.json?node_group_ids=2&show_ignored=true
GET Show differences only /api/v2/nodes/group_diff.json?node_group_ids=2&show_difference=true

Node Configuration

This method allows you to view the scan configuration of a node.

Method URL
GET /api/v2/nodes/[node_id]/node_configuration

Example Response

Code Status
200 OK

Example Response JSON

{
    "ignore_items": null,
    "scan_options": {
        "scan_directory_options": [{
            "path": "/etc/sysconfig/*",
            "exclude": false,
            "contents": false
        },
        {
            "path": "/etc/network/*",
            "exclude": false,
            "contents": false
        }],
        "sql_queries": [],
        "scan_ports": {
            "tcp": "1-1024",
            "udp": "1-1024"
        },
        "scan_diff_excluded_text": [
            ""
        ],
        "scripts": []
    },
    "policies": []
}

CI Data

This method allows you to retrieve a subsection of the latest node scan for the specified node.

Method URL
GET /api/v2/nodes/[node_id]/ci_data?ci_type=[ci_type]

Parameters

Param Type Required Notes
ci_type String Yes The CI type of the section to retrieve.

Example Response

Code Status
200 OK

Example Response JSON

{
    "windows": {
        "%windir%\\system.ini": {
            "name": "%windir%\\system.ini",
            "owner": "NT AUTHORITY\\SYSTEM",
            "content": "286a9edb379dc3423a528b0864a0f111"
        }
    }
}

Example Python Script

The following example demonstrates how to use the API to retrieve a text file from a node using a combination of CI name and node ID. This is not limited to files pulled via the scan directories portion of a scan; for instance, a file object returned by a PowerShell script called “App Pools” could be retrieved by using “App Pools” as the value for the file_path variable.

Raw Files

The raw file endpoints only apply to node types that are: Firewalls, Switches, or Routers.

This method allows you to retrieve a list of all raw files which correspond to a node scan of the specified node types above.

Method URL
GET /api/v2/nodes/[node_id]/raw_files

Example Response

Code Status
200 OK

**Example Response JSON

[
    {
        "id": 125,
        "node_scan_id": 3710,
        "url": "https://app.upguard.com/api/v2/nodes/38/raw_file?raw_file_id=125",
        "created_at": "2016-02-22T12:08:36-11:00",
        "updated_at": "2016-02-22T12:08:36-11:00"
    },
    {
        "id": 125,
        "node_scan_id": 3711,
        "url": "https://app.upguard.com/api/v2/nodes/38/raw_file?raw_file_id=125",
        "created_at": "2016-02-22T12:08:36-11:00",
        "updated_at": "2016-02-22T12:08:36-11:00"
    },
    {
        "id": 125,
        "node_scan_id": 3731,
        "url": "https://app.upguard.com/api/v2/nodes/38/raw_file?raw_file_id=125",
        "created_at": "2016-02-23T00:31:16-11:00",
        "updated_at": "2016-02-23T00:31:16-11:00"
    },
    ...
]

Raw File

This method allows you to retrieve the most recent raw file which corresponds to its equivalent node scan for the specified node types above Firewalls, Switches, or Routers.

If no parameters are supplied, this method will return the most recent raw file in the stored category by default.

Method URL
GET /api/v2/nodes/[node_id]/raw_file?raw_file_id=[raw_file_id]
GET /api/v2/nodes/[node_id]/raw_file?category=[category_id]

Parameters

Param Type Required Notes
raw_file_id Int No The id of the raw file that you wish to retrieve.
category Int No The category from which the node scan ids will be retrieved from, defaulted to 0 (Stored)
Category Code
Stored 0
Running 1
Merged 2

Example Response

Code Status
200 OK

**Example Response JSON

{
    "id": 703,
    "data": "...",
    "node_scan_id": 12194
}

Automation Snippets

This method allows you to generate automation snippets for the various services such as Ansible, or Docker through our API. Most commonly generated snippets are of CI type packages, files, features, or services.

The output snippets are templates for your use with the various services (Ansible Playbooks, Dockerfiles, etc.) You may add the automation logic or service specific code where appropriate (marked as TODO, or where it is blank).

Method URL
GET /nodes/1/automation_snippet?type=[dsc]
GET /nodes/1/automation_snippet?type=[dsc]&ci_type=[files]
GET /nodes/1/automation_snippet?type=[dsc]&ci_type=[packages]&ci_name=[openssl]

Parameters

Param Type Required Notes
type String Yes The type of automation snippet to output
ci_type String No The CI type of the section to retrieve
ci_name String No The name of the configuration item that exists for the node scan

Example Response

Code Status
200 OK

Example Response: Recipe Snippet Output for ci_type=services

service "Active Directory Domain Service" do
    action        [:enable]
    path
end

service "Active Directory Web Services" do
    action        [:enable]
    path
end

service "App Readiness" do
    action        [:enable]
    path
end

services "EC2ConfigService" do
    action        [:enable]
    path
end

Example Response: DSC Snippet Output for ci_type=groups

Group "Access Control Assistance Operators"
{
    Ensure        = "Present"
    GroupName     =
}

Group "Account Operators"
{
    Ensure        = "Present"
    GroupName     =
}

Group "Administrators"
{
    Ensure        = "Present"
    GroupName     =
    Members       = "Administrator, Domain Admins, Enterprise Admins"
}

Example Response: Manifest Snippet Output for ci_type=services

service { "Active Directory Domain Services":
    enable        => ,
    path          =>
}

service { "Active Directory Web Services":
    enable        => ,
    path          =>
}

service { "App Readiness":
    enable        => ,
    path          =>
}

service { "Application Experience":
    enable        => ,
    path          =>
}

service { "Application Identity":
    enable        => ,
    path          =>
}

Example Response: Playbook Snippet Output for ci_type=packages

- name:
    package: "AWS PV Drivers" state=present
- name:
    package: "AWS Tools for Windows" state=present
- name:
    package: "aws-cfn-bootstrap" state=present
- name:
    package: "EC2ConfigService" state=present
- name:
    package: "Microsoft ODBC Driver 11 for SQL Server" state=present

Example Response: Salt State Snippet Output for ci_type=packages

Microsoft SQL Server 2008 Setup Support Files :
pkg.installed

Microsoft SQL Server 2012 Native Client :
pkg.installed

Microsoft SQL Server 2014 (64-bit):
pkg.installed

Microsoft SQL Server 2014 RsFx Driver:
pkg.installed

Microsoft SQL Server 2014 Setup (English):
pkg.installed

Microsoft SQL Server 2014 Transact-SQL ScriptDom :
pkg.installed

Example Response: Dockerfile Snippet Output for ci_type=packages

#
RUN apt-get install accountsservice -y

#
RUN apt-get install acl -y

#
RUN apt-get install acpid -y

#
RUN apt-get install adduser -y

#
RUN apt-get install apparmor -y

#
RUN apt-get install apport -y

#
RUN apt-get install apport-symptoms -y

Output Types

The URL parameter, type, determines the type of snippet that will be returned in the output. It can be one of the following values:

Param Value
Chef Recipe
DSC
Puppet Manifest
Ansible Playbook
Salt State
Dockerfile

CI Types

The URL parameter, ci_type corresponds to the given section shown on the Nodes visualization. An example list of configuration item types are shown below:

Param Value
envvars
features
files
grouppolicy
groups
inventory
mounts
network
packages
powershell
ports
routes
services
users
hotfixes
Tags: nodes