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" }

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" }   }

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

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" }      }