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