Jump to: navigation, search

Difference between revisions of "CerberusAPI"

(Created page with "= 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...")
 
m
 
Line 14: Line 14:
 
The CERBERUS API uses a URI versioning scheme. The first element of the path contains the target version identifier, e.g.:
 
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/v1.0
+
   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.
 
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.
Line 48: Line 48:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
GET /v1.0/plugins
+
GET /v1/plugins
 
</pre>
 
</pre>
  
Line 109: Line 109:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
GET /v1.0/plugins/{uuid}
+
GET /v1/plugins/{uuid}
 
</pre>
 
</pre>
  
Line 148: Line 148:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
GET /v1.0/tasks
+
GET /v1/tasks
 
</pre>
 
</pre>
  
Line 183: Line 183:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
GET /v1.0/tasks/{id}
+
GET /v1/tasks/{id}
 
</pre>
 
</pre>
  
Line 210: Line 210:
 
=== Create a task ===
 
=== Create a task ===
  
−
POST /v1.0/tasks
+
POST /v1/tasks
  
 
Request body:
 
Request body:
Line 246: Line 246:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
POST /v1.0/tasks/{id}/action
+
POST /v1/tasks/{id}/action
 
</pre>
 
</pre>
  
Line 272: Line 272:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
DELETE /v1.0/tasks/{id}
+
DELETE /v1/tasks/{id}
 
</pre>
 
</pre>
  
Line 287: Line 287:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
GET /v1.0/security_reports
+
GET /v1/security_reports
−
or
 
−
GET /v1.0/{project_id}/security_reports
 
 
</pre>
 
</pre>
−
 
−
Parameter:
 
−
project_id: the Openstack identifier of the project the security report is linked to
 
  
 
Response:
 
Response:
Line 346: Line 341:
 
Request:
 
Request:
 
<pre>
 
<pre>
−
GET /v1.0/plugins/{id}
+
GET /v1/plugins/{id}
 
</pre>
 
</pre>
  

Latest revision as of 14:41, 3 April 2015

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"
       }   
    }
Retrieved from "https://wiki.openstack.org/w/index.php?title=CerberusAPI&oldid=76855"