Getting Started with the cysmo® API

Welcome to the Getting Started guide of the cysmo® API. This guide helps you make your first API request in just a few minutes.

Prerequisites

Before you start, make sure you have:

• cysmo® API credentials for your account
• cURL or any API client application/framework

General Information

All API requests use the following base URL:

Entities and Relations

In cysmo we have the following entities and relations:

    erDiagram
    TENANT ||--o{ PORTFOLIO : has
    TENANT ||--o{ USER : has

    PORTFOLIO }o--o{ USER : assigned_to

    PORTFOLIO ||--o{ COMPANY : contains
    COMPANY ||--o{ RATING : has
  

More details about the attributes of each entity can be found in our OpenAPI specification .

Portfolio

In cysmo you can manage your companies inside portfolios. In its simplest form you can think of a portfolio as a list of companies.

Several configurations are shared among companies inside the same portfolio:

• User permissions: Users may have the permission to see, create, update, and/or delete companies within a portfolio.
• Default Radar
• Rule Sets / Underwriting Rules

Company

Companies are the central entity in cysmo®. They represent your customers or whoever’s cyber security you want to scan and monitor.

A company in cysmo is - at its core - defined by a list of at least one domain or IPv4 network. Additional company data can be added without influencing the technical rating result. This includes:

• Name and Address
• Annual Turnover
• Number of Employees
• Legal Form
• Industry (NACE code)

These data points can influence or are necessary for non-technical evaluations such as financial loss or rule evaluations.

Rating

A company can be rated and re-rated multiple times (but we recommend at most one re-rating per week). The Ratings hold the actual in-depth technical analysis of cysmo’s scan results.

Currently a cysmo® Rating consists of six different Partial Ratings:

• Attack Resilience
• DDoS Stability
• DNS Config
• Mail Config
• Privacy and Reputation
• Darknet

Each Partial Rating consists of a number of different Scores (e.g. Attack Resilience -> Application Management) and each score will present one or more Messages. Also each Message may contain Tables which show the detailed evidence that lead to this finding.

On all of these Levels (Rating, down to Table row) you receive Classifications: We classify our findings into:

• Good: No deviations from standards or best practices detected.
• Neutral: Purely informative, no impact on the result.
• Warning: Deviations from standards or best practices detected - no acute threat.
• Critical: Deviations from standards or best practices detected - acute threat!
• Catastrophic: An IT security incident could already have occurred.

On the upper three levels (Rating to Score) you additionally receive a score Value: A percentual numeric score (at the API [0..1]) of the company’s security.

Authentication

To authenticate an API user cysmo uses the client credential flow of the OAuth2 standard. The token url is https://login.cysmo.de/realms/cysmo/protocol/openid-connect/token.

Use your preferred, reputable OAuth2 library/client to achieve this.

For the following examples using cURL, you may use the following command to retrieve an API token:

curl --request POST \
  --url https://login.cysmo.de/realms/cysmo/protocol/openid-connect/token \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id=<YOUR_CLIENT_ID> \
  --data-urlencode client_secret=<YOUR_CLIENT_SECRET>

Your response should look similar to this one:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "cysmo:api"
}

Copy the access_token and use it in place of the ... in Authorization: Bearer ... for the following examples.

First Steps

Now we will take a look at the most common use-cases with the cysmo® API.

Determine your Portfolio

Before creating your first company you will need to know in which portfolio the company should be created. For this purpose use the following endpoint to determine to which portfolios your user has the permission CREATE_COMPANIES.

curl --request GET \
  --url https://api.cysmo.de/v3/portfolios \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...'

The endpoint returns an array of portfolio objects. The relevant value here is the id, which can be used later to dynamically control what portfolio a given company will be created in.

Creating Companies and Ratings

Now you know to which portfolios your API user has access. To create a company you use the following endpoint.

curl --request POST \
  --url https://api.cysmo.de/v3/companies \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...' \
  --header 'Content-Type: application/json' \
  --data '{
  "portfolioId": "2a9b0ad6-e5de-4239-a282-527c92c7c0f1",
  "data": {
    "name": "My first cysmo company",
    "legalForm": "GENERIC__STOCK_CORPORATION",
    "industry": "A1",
    "numberOfEmployees": 5000,
    "turnover": 72000000,
    "city": "Hamburg",
    "zipCode": "20459",
    "country": "DE",
    "customerStatus": "CUSTOMER"
  },
  "scanOptions": {
    "scanTargetDomains": [
      "ppi.de"
    ],
    "overridePriority": "NORMAL"
  }
}'

The return object includes the rating ID, which you will need to fetch its status and results later.

Rating Priorities

With the creation of a company, cysmo triggers the first rating automatically. Therefore, we have different rating priorities:

• NORMAL
• LOW

The default priority when creating a company is NORMAL. As the priority NORMAL is rate limited, you should only use it for single ratings (not more than 15 at the same time). For batch operations you should use the priority LOW.

Rating Progress and States

Gathering all information for a rating needs some time. Once your rating is picked from the queue, it takes about 1 minute on average until it’s finished, in some cases longer.

Use this request to query its current status, as well as the final results when finished:

curl --request GET \
  --url https://api.cysmo.de/v3/ratings/{ratingId} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...'

Your rating will report one of these different states:

• WAITING
• IN_PROGRESS
• FINISHED
• FINISHED_WITH_SCORE_TIMEOUT -> a timeout occurred in one (or some) of our scores (e.g. DNS DDos). Rating data is still available.
• INFRASTRUCTURE_TOO_LARGE
• TIMEOUT
• FAILED
• other less common ones (see OpenAPI Specification)

Re-Ratings

In cysmo you can re-rate companies. To do this you can trigger manual re-ratings with the request below.

Please note that for this operation the priority LOW is used as default. To get faster results you can set the priority to NORMAL but doing so is subject to rate limiting and thus discouraged for batch operations (see above).

curl --request POST \
  --url https://api.cysmo.de/v3/companies/{companyId}/ratings \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...' \
  --header 'Content-Type: application/json' \
  --data '{
  "priority": "NORMAL"
}'

cysmo® Radar (automatic re-ratings)

Alternatively you use can the cysmo® Radar functionality for a regular monitoring (company based or for the whole portfolio). The cysmo® Radar triggers recurring re-ratings in a specified interval (e.g. every month), starting at a specified point in time (e.g. tomorrow 6:30 pm).

curl --request PUT \
  --url https://api.cysmo.de/v3/companies/{companyId}/radar \
  --header 'Authorization: Bearer ...' \
  --header 'Content-Type: application/json' \
  --data '{
  "nextExecutionDate": "2019-08-24",
  "executionTime": "18:00",
  "endDate": "2022-12-31",
  "timezone": "Europe/Berlin",
  "interval": 1,
  "intervalUnit": "MONTHS"
}'

Retrieving Rating Data and Reports

Rating Data

We already explained the structure of cysmo® ratings above.

You can see a brief summary of all ratings of a company by querying this endpoint:

curl --request GET \
  --url https://api.cysmo.de/v3/companies/{companyId}/ratings \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...'

As you will see, the summary includes the total result values (in percent and as a school grade from A - F). To retrieve the detailed rating data you may extract the rating ID of one of these ratings and use the following endpoint:

curl --request GET \
  --url https://api.cysmo.de/v3/ratings/{ratingId} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...'

Here you will receive the complete detail, down to Score Messages and Tables.

Reports

For human reading without the cysmo® UI or for sending to correspondents, we enable you to download a cysmo® Rating as a PDF Report.

In order to start generation of a PDF you need to request the following POST endpoint with a request body specifying the corresponding view mode and language.

curl --request POST \
  --url https://api.cysmo.de/v3/ratings/{ratingId}/reports/pdf \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ...' \
  --header 'Content-Type: application/json' \
  --data '{
  "viewMode": "TECH",
  "language": "en"
}'

The return object links you to a status monitoring endpoint, which will also tell you the final download link once the PDF is ready.

Please feel free to repeatedly poll this endpoint via the provided link from your generation request until the download link is filled in. This is expected to take a couple of seconds, but not more than a minute.