Introduction

This is the documentation for the SIWECOS Core API.

The main purpose of the this project is to orchestrate all SIWECOS related scaners and aggregate their results via one very simple API.

Supported Scanners

At the moment the following scanners are offically supported by the Core API:

Name	Purpose
BLACKLIST	Check offical blacklists for a given URL (SPAM, Phishing, Malware)
DOMXSS	Check for DOMXSS-related sources and sinks
HEADER	Check for secure HTTP-Header configurations
INFOLEAK	Check for unintentional published information (phone numbers, mail addresses, ... )
PORT	Check for critical opened ports on the webserver
TLS	Check for a secure TLS implementation and configuration
VERSION	Check for up to date CMS version

Scanning

Starting a Scan

The Request must have the following structure:

curl -X POST \
  http://siwecos-core-api/api/v2/scan \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://siwecos.de",
    "dangerLevel": 0,
    "callbackurls": [
      "http://172.17.0.1:9000"
    ],
    "scanners": [
      "TLS", "HEADER", "INI_S"
    ]
  }'

POST /api/v2/scan HTTP/1.1
Host: siwecos-core-api
Content-Type: application/json

{
  "url": "https://siwecos.de",
  "dangerLevel": 0,
  "callbackurls": [
    "http://172.17.0.1:9000"
  ],
  "scanners" : [
    "TLS", "HEADER", "INI_S"
  ]
}

A Scan can be started.

HTTP Request

POST /api/v2/scan

Query Parameters

Parameter	Type	Description
url	url	The URL to the domain that should be scanned
dangerLevel	integer, min: 0, max: 10	Define how dangerous the scanner's tests are allowed to be
callbackurls	array	The callbackurls to which the results should be sent
callbackurls.*	url	The URL that should receive the scan result
scanners	array	A subset of available scanners that should be started
scanners.*	string	An available scanner name; valid entries are listed here

Response Status Codes

Code	Meaning
200	Scan started
422	Validation failed

Scan Result

The Response has the following structure:

{
    "url": "http:\/\/www.siwecos.de",
    "dangerLevel": 10,
    "startedAt": "2019-05-09T07:05:38Z",
    "finishedAt": "2019-05-09T07:05:55Z",
    "withMissingScannerResults": ["INI_S", "INFOLEAK"],
    "results": [
        {
          "startedAt": "2019-05-09T07:05:38Z",
          "finishedAt": "2019-05-09T07:05:40Z",
          // Scanner 1 results
        },
        {
          "startedAt": "2019-05-09T07:05:41Z",
          "finishedAt": "2019-05-09T07:05:52Z",
          // Scanner 2 results
        },
        ...
    ]
}

The result that will be send to the callbackurls has the following structure.

NB:
The withMissingScannerResults array will only be sent if there were conflicts in the Core-API so no result was delivered by the particular scanner.

For further information regarding the results please check the related scanner repo and the Scanner Interface Documentation.

Log Messages

The Core-API logs some events that might be useful for debugging and statistics.

Start Scanners

app/Jobs/StartScannerJob.php

Log Level	Message Format
debug	Sending scan start request ...
info	Scan successful started ...
critical	Failed to start scan ...
critical	The following Exception was thrown: ...

Notify Callback URLs

app/Jobs/NotifyCallbacksJob.php

Log Level	Message Format
info	Scan results for Scan ID {id} successfully sent to: {callbackurl}
info	Scan with ID {id} finished successfully
warning	Scan results for Scan ID {id} could not be sent to: {callbackurl}
critical	Scan with ID {id} could not be sent to any given callbackurls
critical	The following Exception was thrown: ...