Source Types

The source_type key in the response is explained by the following values:

Code Type
1 TEST_STEP
2 TEST_SCRIPT
3 POLICY
4 NODE
5 ENVIRONMENT
6 POLICY_VERSION
7 NODE_GROUP
11 NODE_SCAN
12 ENVIRONMENT_NODE_SCAN
13 NODE_GROUP_NODE_SCAN
14 CONNECTIVITY
15 NODE_VULN_SCAN
16 NODE_GROUP_VULN_SCAN
17 FIND_NODES
18 CHANGE_REQUEST_SYNC
19 INCIDENT_SYNC
20 UNAUTH_CHANGE_CHECK
21 ENVIRONMENT_VULN_SCAN
22 AD_HOC_NODE_SCAN

Create

This method allows you to initiate and execute a new job.

Method URL
POST /api/v2/jobs.json

The types of jobs supported are shown in the table below, and can be specified by passing in the Code of the Type you want to run as the type field.

Code Type
3 POLICY
4 NODE
5 ENVIRONMENT
6 POLICY_VERSION
7 NODE_GROUP
11 NODE_SCAN
12 ENVIRONMENT_NODE_SCAN
13 NODE_GROUP_NODE_SCAN
15 NODE_VULN_SCAN
16 NODE_GROUP_VULN_SCAN
21 ENVIRONMENT_VULN_SCAN

Type NODE

This method kicks off a delayed job to check all cis policy versions that is currently linked to the specified node through its node group. If the specified node has no cis policies linked, the job will not be created, and will return a 400.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 4 in this case
type_id integer Yes ID of the node that you want to check against

Example Request

/api/v2/jobs.json?type=4&type_id=123

Example Response JSON

{
    "delayed_job": true
}

Type NODE_GROUP

This method kicks off a delayed job to check all cis policy versions that is currently linked to the specified node group. If the specified node group has no cis policies linked, the job will not be created, and will return a 400.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 7 in this case
type_id integer Yes ID of the node group that you want to check against

Example Request

/api/v2/jobs.json?type=7&type_id=123

Example Response JSON

{
    "delayed_job": true
}

Type ENVIRONMENT

This method kicks off a delayed job to check all cis policy versions that is currently linked to the specified environment. If the specified environment has no cis policies linked, the job will not be created, and will return a 400.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 5 in this case
type_id integer Yes ID of the environment that you want to check against

Example Request

/api/v2/jobs.json?type=5&type_id=123

Example Response JSON

{
    "delayed_job": true
}

Type NODE_SCAN

This method kicks off a job to scan the specified node. It also checks all custom policies that is currently linked to the specified node through its node group.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 11 in this case
type_id integer Yes ID of the node that you want to check against

Example Request

/api/v2/jobs.json?type=11&type_id=123

Example Response JSON

{
    "job_id": 123,
    "delayed_job": false
}

Type NODE_GROUP_NODE_SCAN

This method kicks off a job to scan the specified node group if there are less than 15 nodes in the node group, and a delayed job otherwise. It also checks all custom policies that are currently linked to the specified node group.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 13 in this case
type_id integer Yes ID of the node group that you want to check against

Example Request

/api/v2/jobs.json?type=13&type_id=123

Example Response JSON

{
    "job_id": 123,
    "delayed_job": false
}

{
    "delayed_job": true
}

Type ENVIRONMENT_NODE_SCAN

This method kicks off a job to scan the specified environment if there are less than 15 nodes in the environment, and a delayed job otherwise. It also checks all custom policies that are currently linked to the specified node group.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 12 in this case
type_id integer Yes ID of the environment that you want to check against

Example Request

/api/v2/jobs.json?type=12&type_id=123

Example Response JSON

{
    "job_id": 123,
    "delayed_job": false
}

{
    "delayed_job": true
}

Type NODE_VULN_SCAN

This method kicks off a job do a vuln scan for the specified node. If the node specified does not support vuln scan, the job will not be created, and a 400 will be returned.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 15 in this case
type_id integer Yes ID of the node that you want to check against

Example Request

/api/v2/jobs.json?type=15&type_id=123

Example Response JSON

{
    "job_id": 123,
    "delayed_job": false
}

Type NODE_GROUP_VULN_SCAN

This method kicks off a job to do a vuln scan on the specified node group if there are less than 15 nodes in the node group, and a delayed job otherwise. If the node group specified does not have a node that supports vuln scan, the job will not be created, and a 400 will be returned.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 16 in this case
type_id integer Yes ID of the node group that you want to check against

Example Request

/api/v2/jobs.json?type=16&type_id=123

Example Response JSON

{
    "job_id": 123,
    "delayed_job": false
}

{
    "delayed_job": true
}

Type ENVIRONMENT_VULN_SCAN

This method kicks off a job to do a vuln scan on the specified environment if there are less than 15 nodes in the environment, and a delayed job otherwise. If the environment specified does not have a node that supports vuln scan, the job will not be created, and a 400 will be returned.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 21 in this case
type_id integer Yes ID of the environment that you want to check against

Example Request

/api/v2/jobs.json?type=21&type_id=123

Example Response JSON

{
    "job_id": 123,
    "delayed_job": false
}

{
    "delayed_job": true
}

Type POLICY_VERSION

This method kicks off a delayed job to run a cis policy version against either a node or a node group. If the policy version specified is not a CIS policy version, the job will not be created, and will return a 400.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 6 in this case
type_id integer Yes ID of the cis policy version that you want to check
node_id integer Yes^ ID of the node that you want to check against
node_group_id integer Yes^ ID of the node group that you want to check against

^ Either the node or node group id has to be provided, but not both

Example Request

/api/v2/jobs.json?type=6&type_id=123&node_group_id=456
/api/v2/jobs.json?type=6&type_id=123&node_id=456

Example Response JSON

{
    "delayed_job": true
}

Type POLICY

This method kicks off a delayed job to run the latest policy version of the specified cis policy against either a node or a node group. If the policy specified is not a CIS policy, the job will not be created, and will return a 400.

Parameters

Param Type Required Notes
type integer Yes Code of the type you want to run, 3 in this case
type_id integer Yes ID of the cis policy that you want to check
node_id integer Yes^ ID of the node that you want to check against
node_group_id integer Yes^ ID of the node group that you want to check against

^ Either the node or node group id has to be provided, but not both

Example Request

/api/v2/jobs.json?type=3&type_id=123&node_group_id=456
/api/v2/jobs.json?type=3&type_id=123&node_id=456

Example Response JSON

{
    "delayed_job": true
}

Index

This method returns a list of jobs for the organization.

Method URL
GET /api/v2/jobs.json
GET /api/v2/jobs.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": 256,
        "organisation_id": 33,
        "source_id": 22,
        "source_name": "Cluster Node 1",
        "source_type": 11,
        "status": 2,
        "url": "/api/v2/jobs/256.json"
    },
    {
        "id": 258,
        "organisation_id": 33,
        "source_id": 23,
        "source_name": "Cluster Node 2",
        "source_type": 11,
        "status": 2,
        "url": "/api/v2/jobs/258.json"
    }
]

Show

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

Method URL
GET /api/v2/jobs/[job_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
    "created_at": "2012-10-30T16:16:52-07:00",
    "created_by": 178,
    "diff_stats": null,
    "id": 294,
    "organisation_id": 185,
    "scheduled_job_id": null,
    "source_id": 1130,
    "source_name": "sandbox",
    "source_type": 2,
    "stats": null,
    "status": 2,
    "updated_at": "2012-10-30T16:16:57-07:00",
    "updated_by": 178,
    "upload_node_id": 251
}

A job’s status can be one of the following values:

Code Status Description
0 Pending A job is yet to be picked up for execution
1 Processing A job has been started and is currently being processed
2 Success A job has finished running and all tests passed
3 Cancelled A job is no longer running as it was cancelled early
-1 Failure A job has finished running and not all tests passed

A job’s source_type shows which type of object a job is based on. The source_type field can be one of the following values:

ID Type Description
1 Step The job was kicked off to run the single UpGuard test step given by source_id
2 Script The job was kicked off to run the script given by source_id
3 Policy The job was kicked off to run the policy given by source_id
4 Node The job was kicked off to run all policy versions assigned to the node given by source_id
5 Environment The job was kicked off to run all policy versions assigned to all nodes in the environment given by source_id
6 Policy Version The job was kicked off to run the policy version with id given by source_id
7 Node Group The job was kicked off to run all policy versions assigned to the node group given by source_id
11 Node Scan The job was kicked off to run a node scan on the node given by source_id
12 Environment Scan The job was kicked off to run a node scan across all nodes in the environment given by source_id

Tasks

This methods allows you to list tasks under a given job. An optional ‘status’ parameter can be supplied to filter for tasks with a given status.

Method URL
GET /api/v2/jobs/[job_id]/tasks.json
GET /api/v2/jobs/[job_id]/tasks.json?status=success
GET /api/v2/jobs/[job_id]/tasks.json?status=error,exception,timeout

Example Response

Code Status
200 OK

Example Response JSON

[
  {
    "agent_name": "prod1-core.internal",
    "connection_manager_id": null,
    "created_at": "2015-08-18T13:31:56-11:00",
    "id": 2,
    "job_id": 4,
    "label": null,
    "log": null,
    "node_id": 1,
    "node_session_id": 1,
    "payload": {
      "process_definition": "generate_and_upload_blueprint",
      "fields": {
        "os": null,
        "os_family": null,
        "node_id": 1,
        "scan_options": {
          "scan_ports": {
            "tcp": "1-1024",
            "udp": "1-1024"
          },
          "template_vars": {
            "node_name": "Cluster Node1",
            "node_environment": "Default"
          }
        }
      }
    },
    "report": "[ ... ]",
    "sequence": 1,
    "status": 99,
    "step_description": "Node Scan",
    "step_id": null,
    "updated_at": "2015-08-18T13:32:34-11:00",
    "user_task_id": null,
    "uuid": "53a1239d-845d-4b14-b434-1e3fg712bb15c"
  }
]

A task’s status can be one of the following values:

Code Status Description
0 Pending The task has been created and is yet to be picked up for processing.
1 Processing The task is currently being executed.
2 Success The task has completed with a successful result.
3 Assigned The task has been assigned to a specific agent in a multi-agent setup, but is yet to be picked up for processing.
9 Failure The task has completed with an unsuccessful result.
10 Offline The task tried to run, but the target node was offline.
20 Cancelled The task was cancelled before it finished executing.
55 Timeout The task took too long to execute and hit a timeout before it could complete.
88 Error The task failed to complete in either a success or failure state due to either a user error, a lack of information or other known way a test cannot definitively say if a test is true or false.
99 Exception Similar to the Error status, but usually not one of the common types of errors that can occur.
Tags: jobs