Skip to content

api-v1.rst

Latest commit

 

History

History
133 lines (92 loc) · 4.71 KB

api-v1.rst

File metadata and controls

133 lines (92 loc) · 4.71 KB
Raw

API v1

Blueprint dedicated to the main API. It is composed of three namespaces, client, stats and processed.

New namespaces are easily plugable via the file: api/v1/__init__.py.

Security model

First, an overview of the security model.

Clients needs to have an activated account and a token in order to submit new stats and to query the API. New clients can be created with the dedicated command.

The token must be submitted in the headers of the requests with the key X-API-KEY, as explained below. It is not needed to submit an additional id, tokens are unique.

OpenAPI Specification

Specification also available at https://dashboard.monarc.lu/api/v1.

.. literalinclude:: swagger.json
  :language: JSON

Detailed examples with the API

Getting stats for a client

$ curl -X GET "http://127.0.0.1:5000/api/v1/stats" -H  "accept: application/json" -H  "X-API-KEY: rddPRk9_t-Z4GOgmY2UL2blKB1DxWB_0yhDlqcsF9p63eXs-oLCdm2c9YgP7cOqGz71GK1tc8lrCenD8AvEr-g"
{
  "metadata": {
    "count": "0",
    "offset": "0",
    "limit": "0"
  },
  "data": []
}

Specify a type of stats:

$ curl --location --request GET \
-H 'X-API-KEY: rddPRk9_t-Z4GOgmY2UL2blKB1DxWB_0yhDlqcsF9p63eXs-oLCdm2c9YgP7cOqGz71GK1tc8lrCenD8AvEr-g' \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-d '{"type":"threat"}' \
'http://127.0.0.1:5000/api/v1/stats'

Invoking a processor

Processors are utilities to process stats data. Processors are currently defined in statsservice/lib/processors.py. They operate on different kind of stats:

  • risks;
  • threats;
  • vulnerabilities.

They can do a lot of things, like evaluate different averages based on user requirements. The result of the processor is sent in the response from the API.

You can get the list of available processors:

$ curl http://127.0.0.1:5000/api/v1/stats/processed/list
[
    {
        "name": "risk_averages",
        "description": "Evaluates the averages for the risks. Averages are evaluated per categories\n    (current/residual, informational/operational, low/medium/high)."
    },
    {
        "name": "risk_averages_on_date",
        "description": "Evaluates the averages for the risks per date. Averages are evaluated per categories\n    (current/residual, informational/operational, low/medium/high).\n    Supported parameters:\n    - risks_type: informational or operational\n    - risks_state: current or residual."
    },
    {
        "name": "threat_average_on_date",
        "description": "Aggregation and average of threats per date for each threat (accross all risk\n    analysis).\n    "
    },
    {
        "name": "vulnerability_average_on_date",
        "description": "Aggregation and average of vulnerabilities per date for each vulnerability\n    (accross all risk analysis).\n    "
    }
]

Some processors can use dedicated parameters. For this purpose the parameter processor_params can be used to transfer these parameters directly to the concerned processor. These parameters will affect the behaviour of the processor.

For example you might want to call the processor risk_averages_on_date but you want that this processor only evaluates the averages for residual risks that are also operational risks (and not informational risks). The request will look like:

curl -X GET "http://127.0.0.1:5000/api/v1/stats/processed/" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{  \"type\": \"risk\",  \"processor\": \"risk_averages_on_date\",  \"local_stats_only\": 0, \"date_from\":\"2020-06-12\",\"processor_params\": {\"risks_type\":\"operational\",\"risks_state\":\"residual\"}}"

Internally the processor processor_params will honor the value provided with the parameters risks_type and risks_state.

  • risks_type can be informational or operational;
  • risks_state can be current or residual.

Generally, you can get information about a processor:

$ echo -e `curl -s http://127.0.0.1:5000/api/v1/stats/processed/list | jq '.[] | select(.name=="risk_averages_on_date") | .description'`
"Evaluates the averages for the risks per date. Averages are evaluated per categories
 (current/residual, informational/operational, low/medium/high).
 Supported parameters:
 - risks_type: informational or operational
 - risks_state: current or residual."