CerberusAPI

Cerberus API

Overview

Cerberus provides an HTTP-based API in the spirit of the REST architecture style.

This guide assumes the reader is familiar with REST, HTTP/1.1 and JSON. URI templates use the same syntax as RFC 6570.

Note: Error responses are enumerated on a separate page [tbd]

Versioning

The CERBERUS API uses a URI versioning scheme. The first element of the path contains the target version identifier, e.g.:

 https://cerberus.example.com:port/v1

The URI version will only be incremented to accommodate major new features or API redesigns that can not be made backwards-compatible. When new API versions are released, older versions are deprecated. Cerberus maintainers will work with developers and partners to ensure there is adequate time to migrate to new versions before deprecated ones are discontinued.

Since the version is only incremented to accommodate major API revisions, sub-versioning of the API will be rare.

Resource media types

The API supports `application/json`, encoded as UTF-8.

Errors

If any request results in an error, the server will return an appropriate 4xx or 5xx HTTP status code, and optionally the following information in the body:

• Title
• Description

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
    {
       "title": "Task can not be created",
       "description": "Method named act_short is not callable by plugin Simple"
    }

Plugins

List plugins

Request:

GET /v1/plugins

Response:

Status Code: 200 OK

    {
       "plugins":
       [
           {
               "description": "first",
               "uuid": "e9de368f-553c-4675-829e-4a7d2f8a62d8",
               "id": 46,
               "methods":
               [
                   "some",
                   "method"
               ],
               "version": "whatever",
               "provider": "Who knows",
               "subscribed_events":
               [
                  event1
               ],
               "type": "scanner",
               "tool_name": "Tool",
               "name": "cerberus.plugins.first_plugin.FirstPlugin"
           },
           {
               "description": "second",
               "uuid": "13cde7b0-7be4-4103-8de8-c00a52e7a5a2",
               "id": 3,
               "methods":
               [
                   "some",
                   "method"
               ],
               "version": "whatever",
               "provider": "Who knows",
               "subscribed_events":
               [
               ],
               "type": "scanner",
               "tool_name": "Tool",
               "name": "cerberus.plugins.second_plugin.SecondPlugin"
           },
       ]
    }

Get plugin

Request:

GET /v1/plugins/{uuid}

Response:

Status Code: 200 OK

    {
       "plugin":
       {
           "name": "cerberus.plugins.first_plugin.FirstPlugin",
           "uuid": "e9de368f-553c-4675-829e-4a7d2f8a62d8",
           "id": 46,
           "methods":
           [
               "some",
               "method"
           ],
           "version": "whatever",
           "provider": "Who knows",
           "subscribed_events":
           [
           ],
           "type": "scanner",
           "tool_name": "Tool",
           "description": "first"
       }
    }

Tasks

List tasks

Request:

GET /v1/tasks

Response:

Status Code: 200 OK

    {
       "tasks":
       [
           {
               "name": "sample_task_first",
               "period": "10",
               "state": "running",
               "plugin_id": "e9de368f-553c-4675-829e-4a7d2f8a62d8",
               "type": "recurrent",
               "id": 3
           },
           {
               "plugin_id": "e9de368f-553c-4675-829e-4a7d2f8a62d8",
               "type": "unique",
               "state": "running",
               "name": "sample_task_second",
               "id": 4
           }
       ]
    }

Get task

Request:

GET /v1/tasks/{id}

Parameter: id: the identifier of the task to get

Response:

Status Code: 200 OK

    {
       "task":
       {
           "name": "sample_task_first",
           "period": "10",
           "state": "running",
           "plugin_id": "e9de368f-553c-4675-829e-4a7d2f8a62d8",
           "type": "recurrent",
           "id": 3
       }
    }

Create a task

POST /v1/tasks

Request body:

{
    "task": {
        "name": "sample_task_first",
        "method": "act_short",
        "type": "recurrent",
        "period": "10",
        "plugin_id": "e9de368f-553c-4675-829e-4a7d2f8a62d8"
    }
}

Response:

    {
       "task":
       {
           "name": "sample_task_first",
           "period": "10",
           "method": "act_short",
           "plugin_id": "e9de368f-553c-4675-829e-4a7d2f8a62d8",
           "type": "recurrent",
           "id": 3
       }
    }

Modify the state of a task

Request:

POST /v1/tasks/{id}/action

Parameters:

id: the identifier of the task the action has to be performed stop (mandatory): Specify the stop action in the request body. forceDelete (mandatory): Specify the forceDelete action in the request body. Force deleting a task stops its execution and deletes the task from the list of tasks. Only recurrent task can be deleted

Request body:

{"stop":null}

{"forceDelete":null}

This method does not return a response body

Delete a task

The task is stopped and is deleted from the list of tasks. However, if the task is already running, it waits for the end of its execution Only recurrent tasks can be deleted.

Request:

DELETE /v1/tasks/{id}

Parameter: id: the id of the task to delete

This method does not return a response body

Security reports

List security reports

Request:

GET /v1/security_reports

Response:

Status Code: 200 OK

{
   "security_reports":
   [
       {
           "component_id": "2ea15370-b70a-49e4-84fa-249f3bc01513",
           "vulnerabilities_number": 2,
           "description": "172.24.4.6",
           "component_type": "instance",
           "title": "security report",
           "deleted": 0,
           "vulnerabilities": "list of vulnerabilities",
           "created_at": "2015-02-04T08:52:26",
           "updated_at": "2015-02-06T10:24:11",
           "last_report_date": "2015-02-06T10:52:17",
           "project_id": "8e0d9622fb6e4d399743ec3068ecc72b",
           "security_rating": 7.4,
           "plugin_id": "a4412e35-93ec-43e4-b939-a5db8cd67901",
           "component_name": "test02",
           "id": 28,
           "report_id": "5531cdf87f3ede270ae1f828d40643d8"
       },
       {
           "component_id": "944a0e7b-c605-4834-9128-c9dc54dc0835",
           "vulnerabilities_number": 15,
           "description": "172.24.4.8",
           "component_type": "instance",
           "title": "security report",
           "deleted": 0,
           "vulnerabilities": "list of vulnerabilities",
           "created_at": "2015-02-04T08:52:26",
           "updated_at": "2015-02-06T10:24:11",
           "last_report_date": "2015-02-06T10:52:17",
           "project_id": "e6678ce9738f43d4b3f4d20eadc0ef75",
           "security_rating": 1.1,
           "plugin_id": "a4412e35-93ec-43e4-b939-a5db8cd67901",
           "component_name": "test01",
           "id": 41,
           "report_id": "e6c60b138345ba2a6baaec270ee12a70"
       }
    ]
}

Get security report

Request:

GET /v1/plugins/{id}

Parameter: id: the id of the report, not the report_id

Response:

Status Code: 200 OK

    {
       "security_report":
       {
           "component_id": "944a0e7b-c605-4834-9128-c9dc54dc0835",
           "vulnerabilities_number": 15,
           "description": "172.24.4.8",
           "component_type": "instance",
           "title": "security report",
           "deleted": 0,
           "vulnerabilities": "list of vulnerabilities",
           "created_at": "2015-02-04T08:52:26",
           "updated_at": "2015-02-06T10:24:11",
           "last_report_date": "2015-02-06T10:52:17",
           "project_id": "e6678ce9738f43d4b3f4d20eadc0ef75",
           "security_rating": 1.1,
           "plugin_id": "a4412e35-93ec-43e4-b939-a5db8cd67901",
           "component_name": "test01",
           "id": 41,
           "report_id": "e6c60b138345ba2a6baaec270ee12a70"
       }   
    }