Operating System Family

Operating System Family can be one of the following values:

Operating System Value
WINDOWS 1
LINUX 2
UNIX 3
BSD 4
MAC_OS 5
ANDROID 6
CISCO 7
JUNIPER 8
IBM 9
HP 11
PALOALTO 12
SERVICE 14
WEBSITE 16
ARISTA 17
CUSTOM 18
DATABASE 19

Index

This method returns a list of policies for the organization.

Method URL
GET /api/v2/policies.json
GET /api/v2/policies.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, min. 1, max. 50).

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "id": 1,
        "name": "policy 1",
        "url": "https://app.upguard.com/api/v2/policies/1",
        "organisation_id": 2
    },
    {
        "id": 2,
        "name": "policy 2",
        "url": "https://app.upguard.com/api/v2/policies/2",
        "organisation_id": 2
    }
]

New

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

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

Example Response

Code Status
200 OK

Example Response JSON

{
  "policy": {
    "name": null,
    "description": null,
    "operating_system_family_id": null,
    "operating_system_id": null
  }
}

Create

This method allows you to create a new policy for the active organization.

Method URL
POST /api/v2/policies.json

Parameters

Param Type Required Notes
name string Yes The name of the policy
description string No The description of the policy
operating_system_family_id int No The id corresponding to the operating system family type
operating_system_id int No The id corresponding to the exact operating system under the family

Example Response

Code Status
201 Created

Example Response JSON

{
  "id": 2,
  "name": "Policy_Name_2",
  "description": "This is a short description",
  "created_by": 1,
  "updated_by": 1,
  "created_at": "2016-04-14T18:03:29-07:00",
  "updated_at": "2016-04-14T18:03:29-07:00",
  "operating_system_family_id": null,
  "operating_system_id": null
}

Show

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

Method URL
GET /api/v2/policies/[policy_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
  "id": 1,
  "name": "Policy Name 1",
  "description": "This is a policy description",
  "created_by": 5,
  "updated_by": 5,
  "created_at": "2016-04-04T14:14:36-07:00",
  "updated_at": "2016-04-04T14:14:36-07:00",
  "operating_system_family_id": null,
  "operating_system_id": null,
  "data": "{\"network\":{\"en0\":{\"ipv4 123.123.123.123\":{\"__policies\":{\"broadcast\":{\"1\":[{\"exp\":\"192.168.140.255\"}]},\"cidr-mask\":{\"1\":[{\"exp\":\"24\"}]},\"ipv4-addr\":{\"1\":[{\"exp\":\"123.123.123.123\"}]},\"present\":{\"1\":[{\"exp\":\"true\",\"check\":\"equals\"}]}}}}},\"users\":{\"macosx\":{\"useruser\":{\"__policies\":{\"gid\":{\"1\":[{\"exp\":\"20\"}]},\"groups\":{\"1\":[{\"exp\":\"[\"_appserveradm\",\"_appserverusr\",\"_lpadmin\",\"admin\"]\"}]},\"uid\":{\"1\":[{\"exp\":\"501\"}]},\"present\":{\"1\":[{\"exp\":\"true\"}]}}}}}}",
  "tag": null
}

Update

This method allows you to update the properties of a policy.

Method URL
PUT /api/v2/policies/[policy_id].json

Example Submitted Payload

The keys listed in the sample submitted payload below are the attributes that are permissible for updating.

{
    "policy": {
        "name": "Changed Name",
        "description": "New description lorem ipsum",
        "node_scan": "",
        "operating_system_family_id": "",
        "operating_system_id": "",
        "tag": ""
    }
}

Example Response

Code Status
204 No Content

Destroy

This method allows you to delete a policy from your organization account.

Method URL
DELETE /api/v2/policies/[policy_id].json

Example Response

Code Status
204 No Content

Example Ruby Script

The following example demonstrates how to use the API to delete policies from an account. This script can be used particularly for cleaning up policies that are unwanted or no longer needed en masse.

Lookup

This method allows you to lookup the Policy ID of a created policy in your account based on either the name of the policy or the description fields of the policy. This method will return the first result of the policy that matches the lookup parameters.

Method URL
GET /api/v2/policies/lookup.json?name=[policy_name]
GET /api/v2/policies/lookup.json?short_description=[policy_description]

Example Response

Code Status
200 OK

Example Response JSON

{
  "policy_id": 13
}

Target Nodes

This method returns you the list of Node IDs that is targeted by the Policy specified by the ID in the URL.

Method URL
GET /api/v2/policies/[policy_id]/target_nodes.json

Example Response

Code Status
200 OK

Example Response JSON

{
  [
    53,
    61,
    62
  ]
}

Versions

This method returns you the list of versions of the policy, each version different from the previous due to updates performed to the policy data.

Method URL
GET /api/v2/policies/[policy_id]/versions.json

Example Response

Code Status
200 OK

Example Response JSON

{
  [
    {
      "id": 5,
      "version": 1,
      "tag": null
    },
    {
      "id": 2,
      "version": 0,
      "tag": null
    }
  ]
}

Latest Results

This method returns the latest result details of the policy specified by the ID given in the URL.

Method URL
POST /api/v2/policies/[policy_id]/latest_results.json

Parameters

Param Type Required Values Notes
failed_only boolean No true or false If true, only failed policy results will be returned.
include_policy* boolean No true or false Display policy meta data.
include_policy_versions boolean No true or false Display previous policy versions.
include_type_stats boolean No true or false Display the overall result of a policy across all nodes.
include_policy_results boolean No true or false Display detailed policy results. The data element allows you retrieve expected and actual node scan results.
all_data boolean No true or false Display results for all parameters.

Example Response JSON: failed_only=true

{
    "policy_stats": [
        {
            "stats": "{\"EnvVars\":{\"__pass\":1,\"__fail\":2,\"windows\":{\"Path\":{\"__pass\":1,\"__fail\":2}}}}",
            "passed": "f",
            "pass_count": "1",
            "fail_count": "2",
            "name": "IIS-PROD01",
            "node_id": "2458",
            "environment_id": "2814",
            "environment_name": "IIS Servers",
            "created_at": "2016-03-23 20:58:04.956449",
            "nspr_id": "51839",
            "policy_result_id": "2221"
        },
        {
            "stats": "{\"EnvVars\":{\"__pass\":2,\"__fail\":1,\"windows\":{\"Path\":{\"__pass\":2,\"__fail\":1}}}}",
            "passed": "f",
            "pass_count": "2",
            "fail_count": "1",
            "name": "IIS-PROD02",
            "node_id": "2486",
            "environment_id": "2814",
            "environment_name": "IIS Servers",
            "created_at": "2015-11-26 09:01:39.32032",
            "nspr_id": "10923",
            "policy_result_id": "1464"
        }
    ]
}

Example Response JSON: include_policy=true

{
    "policy": {
        "created_at": "2015-11-23T13:22:57-08:00",
        "created_by": 5143,
        "description": "",
        "id": 2116,
        "name": "________iis_path_name_scan__20151123T220016Z__20151125T170017Z__20151125T180016Z__20160104T230849Z",
        "operating_system_family_id": 1,
        "operating_system_id": null,
        "settings": {
            "tests": {
                "output_format": null
            }
        },
        "short_description": "IIS Path Name Scan",
        "status": 1,
        "updated_at": "2016-03-07T15:17:57-08:00",
        "updated_by": 5143
    }
}

Example Response JSON: include_policy_versions=true

{
    "policy_versions": [
        {
            "created_at": "2015-12-18T11:16:17-08:00",
            "created_by": 5143,
            "description": null,
            "id": 4612,
            "image_url": null,
            "name": null,
            "organisation_id": 1574,
            "policy_id": 2116,
            "scan_options": "{\"connectivity\":[],\"scan_directory_options\":[],\"scan_diff_excluded_text\":[],\"registry_keys\":[],\"group_policy_objects\":[],\"sql_queries\":[],\"powershell_queries\":[],\"scripts\":[],\"scan_ports\":[],\"web\":[]}",
            "short_description": null,
            "status": 1,
            "updated_at": "2016-03-07T15:17:57-08:00",
            "updated_by": 5143,
            "version": 5
        },
        {
            "created_at": "2015-12-18T11:14:01-08:00",
            "created_by": 5143,
            "description": null,
            "id": 4611,
            "image_url": null,
            "name": null,
            "organisation_id": 1574,
            "policy_id": 2116,
            "scan_options": "{\"connectivity\":[],\"scan_directory_options\":[],\"scan_diff_excluded_text\":[],\"registry_keys\":[],\"group_policy_objects\":[],\"sql_queries\":[],\"powershell_queries\":[],\"scripts\":[],\"scan_ports\":[],\"web\":[]}",
            "short_description": null,
            "status": 1,
            "updated_at": "2016-03-07T15:17:57-08:00",
            "updated_by": 5143,
            "version": 4
        }
    ]
}

Example Response JSON: include_type_stats=true

{
    "type_stats": {
        "EnvVars": {
            "pass": 5,
            "fail": 4
        }
    }
}

Example Response JSON: include_policy_results=true

{
    "policy_results": [
        {
            "checksum": "f4fdd5f3d2206e48eaa2c807ae0a12b6",
            "created_at": "2015-12-19T01:04:49-08:00",
            "data": "{\"EnvVars\":{\"windows\":{\"Path\":{\"__results\":{\"Name\":{\"2116\":[{\"result\":2,\"expected\":\"Path\",\"check\":\"equals\",\"actual\":\"Path\"}]},\"Value\":{\"2116\":[{\"result\":9,\"expected\":\"C:\\\\Windows\\\\system32;C:\\\\Windows;C:\\\\Windows\\\\System32\\\\Wbem;C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\;C:\\\\Program Files\\\\Amazon\\\\cfn-bootstrap\\\\;C:\\\\Program Files (x86)\\\\ScriptRock\\\\bin\",\"check\":\"equals\",\"actual\":\"C:\\\\Windows\\\\system32;C:\\\\Windows;C:\\\\Windows\\\\System32\\\\Wbem;C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\;C:\\\\Program Files\\\\Amazon\\\\cfn-bootstrap\\\\\"}]},\"present\":{\"2116\":[{\"result\":9,\"expected\":\"false\",\"actual\":\"true\"}]}}}}}}",
            "fail_count": 2,
            "id": 2221,
            "pass_count": 1,
            "passed": false,
            "policy_id": 2116,
            "policy_version_id": 4012,
            "stats": "{\"EnvVars\":{\"__pass\":1,\"__fail\":2,\"windows\":{\"Path\":{\"__pass\":1,\"__fail\":2}}}}",
            "updated_at": "2015-12-19T01:04:49-08:00"
        }
    ]
}
Tags: policies