Index

This method returns a list of user tasks for the organization.

Method URL
GET /api/v1/user_tasks.json
GET /api/v1/user_tasks.json?page=1&per_page=2

Example Response

Code Status
200 OK

Example Response JSON

[
    {
        "created_at": "2015-02-09T16:43:06-08:00",
        "description": "macbook-pro is offline",
        "grouping_key": null,
        "id": 4,
        "meta": null,
        "organisation_id": 2,
        "source_type": 4,
        "status": 1,
        "step_id": 13,
        "task_status": 10,
        "updated_at": "2015-02-11T16:48:36-08:00",
        "user_id": null
    },
    {
        "created_at": "2015-02-16T16:15:50-08:00",
        "description": "The file C:\\Windows\\explorer.exe should exist",
        "grouping_key": null,
        "id": 6,
        "meta": null,
        "organisation_id": 2,
        "source_type": 1,
        "status": 3,
        "step_id": 22,
        "task_status": 9,
        "updated_at": "2015-02-19T22:00:13-08:00",
        "user_id": 4
    }
]

Show

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

Method URL
GET /api/v1/user_tasks/[user_task_id].json

Example Response

Code Status
200 OK

Example Response JSON

{
    "comments":
    [
        {
            "content": "0",
            "created_at": "2015-03-25T16:53:11-07:00",
            "id": 23,
            "source_id": 20,
            "source_type": 1,
            "updated_at": "2015-03-25T16:53:11-07:00",
            "user_id": 4
        },
        {
            "content": "This is a comment",
            "created_at": "2015-03-25T16:53:51-07:00",
            "id": 24,
            "source_id": 20,
            "source_type": 1,
            "updated_at": "2015-03-25T16:53:51-07:00",
            "user_id": 4
        }
    ],
    "created_at": "2015-03-03T17:55:03-08:00",
    "description": "Drift detected - Files (1 modified) Sudoers (82    removed) ",
    "grouping_key": "c3041ddc1bb019bf4fcd88fdf2a2e976",
    "id": 20,
    "meta": "---\n:node_id: 2228\n:node_name: zacs-mac\n:date_previous: 2015-03-04 01:39:23.543726000 Z\n:date_latest: 2015-03-04 01:53:58.969978000 Z\n:previous_scan_id: 122\n:latest_scan_id: 123\n:diff_hash: c3041ddc1bb019bf4fcd88fdf2a2e976\n:stats:\n :summary:\n :total: 848\n :added: 0\n :deleted: 82\n :updated: 1\n :packages:\n :total: 283\n :added: 0\n :deleted: 0\n :updated: 0\n :files:\n :total: 227\n :added: 0\n :deleted: 0\n :updated: 1\n :users:\n :total: 82\n :added: 0\n :deleted: 0\n :updated: 0\n :groups:\n :total: 106\n :added: 0\n :deleted: 0\n :updated: 0\n :sudoers:\n :total: 82\n :added: 0\n :deleted: 82\n :updated: 0\n :EnvVars:\n :total: 68\n :added: 0\n :deleted: 0\n :updated: 0\n",
    "organisation_id": 2,
    "source_type": 3,
    "status": 2,
    "step_id": null,
    "task_status": 2,
    "updated_at": "2015-03-25T16:53:11-07:00",
    "user_id": null
}

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

Code Status Description
1 Unassigned The user task is open but has not been assigned to a user.
2 Closed The user task has been closed.
3 Assigned The user task is open and has been assigned to a user.

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

ID Type Description
1 Policy Task Failure The user task was created due to a failing policy.
2 Scan Task Failure The user task was created due to a failure during a scan.
3 Node Difference The user task was created due to a difference in the node (drift).
4 Offline The user task was created because the target node was offline.

Constructing a link to the scan

A link to the scan identified by drift user tasks can be constructed by parsing the YAML in the meta property of the scan and creating a URL with the following format:

https://app.upguard.com/nodes/[meta.node_id]?scan_id=[meta.latest_scan_id]&diff_id=[meta.previous_scan_id]

Closed Tasks

This method allows you to list closed user tasks. Pagination can be applied here in the same manner as on the Index endpoint.

Method URL
GET /api/v1/user_tasks/closed_tasks
GET /api/v1/user_tasks/closed_tasks?page=1&per_page=20

Example Response

Code Status
200 OK

Example Response JSON

[    
    {
        "created_at": "2015-02-16T16:03:59-08:00",
        "description": "The file C:\\Windows\\explorer.exe should exist",
        "grouping_key": null,
        "id": 5,
        "meta": null,
        "organisation_id": 2,
        "source_type": 1,
        "status": 2,
        "step_id": 22,
        "task_status": 9,
        "updated_at": "2015-02-16T16:15:05-08:00",
        "user_id": null
     },
     {
        "created_at": "2015-02-16T16:24:43-08:00",
        "description": "A TCP connection to banana on port 80, given data to send, should have a response containing the specified values",
        "grouping_key": null,
        "id": 7,
        "meta": null,
        "organisation_id": 2,
        "source_type": 1,
        "status": 2,
        "step_id": 25,
        "task_status": 88,
        "updated_at": "2015-03-19T17:11:55-07:00",
        "user_id": null
     }
]

Assign

This allows you to assign a user task to a user.

Method URL
POST /api/v1/user_tasks/1/assign

Parameters

Param Type Required Notes
user_id integer Yes The id of the user to be assigned the user task.

Example Response

Code Status
200 OK

Close

This allows you to close a user task. It optionally allows you to provide a comment when closing the user task.

Method URL
POST /api/v1/user_tasks/1/close

Parameters

Param Type Required Notes
comment_user_id integer No The id of the user making the closing comment.
comment string No The closing comment.

Example Response

Code Status
200 OK

To generate a link to the diff in the UpGuard website, use the following method:

  • Acquire the task in question from the API
  • Parse the meta attribute, which itself contains node_id, latest_scan_id and previous_scan_id attributes.
  • Create a link using those attributes as follows:

https://app.upguard.com/node_groups/nodes/[node_id]?scan_id=[latest_scan_id]&compare_to_scan_id=[previous_scan_id]

Generating Diff JSON

To acquire the diff as JSON from the API, use the same details at the Nodes/Diff endpoint:

https://app.upguard.com/api/v1/nodes/[node_id]diff?scan_id=[previous_scan_id]&compare_scan_id=[latest_scan_id]

Example Response JSON

[
    {
        "created_at": "2015-02-09T16:43:06-08:00",
        "description": "macbook-pro is offline",
        "grouping_key": null,
        "id": 4,
        "meta": null,
        "organisation_id": 2,
        "source_type": 4,
        "status": 1,
        "step_id": 13,
        "task_status": 10,
        "updated_at": "2015-02-11T16:48:36-08:00",
        "user_id": null
    },
    {
        "created_at": "2015-02-16T16:15:50-08:00",
        "description": "The file C:\\Windows\\explorer.exe should exist",
        "grouping_key": null,
        "id": 6,
        "meta": null,
        "organisation_id": 2,
        "source_type": 1,
        "status": 3,
        "step_id": 22,
        "task_status": 9,
        "updated_at": "2015-02-19T22:00:13-08:00",
        "user_id": 4
    }
]
Tags: user tasks