NAV Navbar
http shell
  • Introduction
  • Scanning
  • Log Messages

    • 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:

    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: ...
    http shell