secureCodeBox/docs/developer-guide/api-doc.md at master

SecureCodeBox API Documentation

Overview

This Document describes the public API of the SecureCodeBox. It's mostly used for scanners to retrieve scan jobs from the engine and send results to the engine.

Contact information

Contact : SecureCodeBox-Team

License information

License : Apache 2.0
License URL : https://github.com/secureCodeBox/engine/blob/master/LICENSE.txt
Terms of service : null

URI scheme

Host : localhost
BasePath : /

Consumes

application/json

Produces

application/json

Paths

Lock a scan job for the given topic

POST /box/jobs/lock/{topic}/{scannerId}

Description

Returns a scan job for the given topic / capability, if there is one.

Parameters

Type	Name	Description	Schema	Default
Path	scannerId required	UUID of the job.	string (uuid)	`"29bf7fd3-8512-4d73-a28f-608e493cd726"`
Path	topic required	Topic name for the Process, be shure only to use: [A-Za-z0-9-_]	string	`"nmap_portscan"`

Responses

HTTP Code	Description	Schema
200	Successful retrieval of the scan Job	ScanConfiguration
204	No scanjob available	ScanConfiguration
400	Incomplete or inconsistent Request	No Content
500	Unknown technical error occurred.	No Content

Example HTTP request

Request path

/box/jobs/lock/nmap_portscan/29bf7fd3-8512-4d73-a28f-608e493cd726

Example HTTP response

Response 200

json :
{
  "jobId" : "string",
  "targets" : [ {
    "attributes" : {
      "NMAP_START_PORT" : 34,
      "NMAP_IP" : "162.222.1.3",
      "NMAP_END_PORT" : 125
    },
    "location" : "162.222.1.3",
    "name" : "SecureCodeBox Demo Instance"
  } ]
}

Response 204

json :
{
  "jobId" : "string",
  "targets" : [ {
    "attributes" : {
      "NMAP_START_PORT" : 34,
      "NMAP_IP" : "162.222.1.3",
      "NMAP_END_PORT" : 125
    },
    "location" : "162.222.1.3",
    "name" : "SecureCodeBox Demo Instance"
  } ]
}

Send a scan failure for the previously locked job.

POST /box/jobs/{id}/failure

Parameters

Type	Name	Description	Schema	Default
Path	id required	UUID of the job.	string (uuid)	`"29bf7fd3-8512-4d73-a28f-608e493cd726"`
Body	result required	result	ScanFailure

Responses

HTTP Code	Description	Schema
200	Successful delivery of the failure.	ResponseEntity
400	Incomplete or inconsistent Request	No Content
500	Unknown technical error occurred.	No Content

Example HTTP request

Request path

/box/jobs/29bf7fd3-8512-4d73-a28f-608e493cd726/failure

Request body

json :
{
  "errorDetails" : "It was not possible to resolve a DNS entry!",
  "errorMessage" : "The host down.securecodebox.io is nor reachable!",
  "scannerId" : "5dd0840c-81ae-4fed-90b5-b3eea3d4c701"
}

Example HTTP response

Response 200

json :
{
  "body" : "object",
  "statusCode" : "string",
  "statusCodeValue" : 0
}

Send a scan result for the previously locked job.

POST /box/jobs/{id}/result

Parameters

Type	Name	Description	Schema	Default
Path	id required	UUID of the job.	string (uuid)	`"29bf7fd3-8512-4d73-a28f-608e493cd726"`
Body	result required	result	ScanResult

Responses

HTTP Code	Description	Schema
200	Successful delivery of the result.	ResponseEntity
400	Incomplete or inconsistent Request	No Content
500	Unknown technical error occurred.	No Content

Example HTTP request

Request path

/box/jobs/29bf7fd3-8512-4d73-a28f-608e493cd726/result

Request body

json :
{
  "findings" : [ {
    "attributes" : {
      "NMAP_PORT" : 34,
      "NMAP_IP" : "162.222.1.3"
    },
    "category" : "Infrastructure",
    "description" : "The DNS Port is open.",
    "hint" : "SQL-Injection: Please think about using prepared statements.",
    "id" : "3dd4840c-81ae-4fed-90b5-b3eea3d4c701",
    "location" : "tcp://162.222.1.3:53",
    "name" : "Open Port",
    "osi_layer" : "NETWORK",
    "reference" : {
      "id" : "CVE-2017-15707",
      "source" : "https://www.cvedetails.com/cve/CVE-2017-15707/"
    },
    "severity" : "HIGH"
  } ],
  "rawFindings" : "string",
  "scannerId" : "5dd0840c-81ae-4fed-90b5-b3eea3d4c701",
  "scannerType" : "nmap"
}

Example HTTP response

Response 200

json :
{
  "body" : "object",
  "statusCode" : "string",
  "statusCodeValue" : 0
}

Returns all possible processes.

Responses

HTTP Code	Description	Schema
200	Returns a list of all available processes.	< Process > array
400	Incomplete or inconsistent Request	No Content
500	Unknown technical error occurred.	No Content

Example HTTP request

Request path

Example HTTP response

Response 200

json :
[ {
  "id" : "string",
  "key" : "string",
  "name" : "string"
} ]

Creates a new scan process.

PUT /box/processes/{processKey}

Parameters

Type	Name	Description	Schema
Path	processKey required	The key of the process to be started. See GET /box/processes.	string
Body	targets required	targets	< Target > array

Responses

HTTP Code	Description	Schema
200	OK	string (uuid)
201	Successful created a new process returns the process id.	string (uuid)
300	For some reason multiple processes could be adressed by the given processKey.	No Content
400	Incomplete or inconsistent Request	No Content
500	Unknown technical error occurred.	No Content

Example HTTP request

Request path

/box/processes/nmap-process

Request body

json :
[ {
  "attributes" : {
    "NMAP_START_PORT" : 34,
    "NMAP_IP" : "162.222.1.3",
    "NMAP_END_PORT" : 125
  },
  "location" : "162.222.1.3",
  "name" : "SecureCodeBox Demo Instance"
} ]

Example HTTP response

Response 200

Response 201

Definitions

Finding

This type represents findings found by a scanner.

Name	Description	Schema
attributes optional	Key value pairs of scanner specific values. Example : `{<br> "NMAP_PORT" : 34,<br> "NMAP_IP" : "162.222.1.3"<br>}`	object
category required	The category of this finding. Example : `"Infrastructure"`	string
description optional	The name of the finding. Example : `"The DNS Port is open."`	string
hint optional	An additional solution hint for a finding found. Example : `"SQL-Injection: Please think about using prepared statements."`	string
id required	The id of the finding. Example : `"3dd4840c-81ae-4fed-90b5-b3eea3d4c701"`	string (uuid)
location required	The location of this finding. Example : `"tcp://162.222.1.3:53"`	string
name required	The name of the finding. Example : `"Open Port"`	string
osi_layer optional	The osi layer of this finding. Example : `"NETWORK"`	enum (APPLICATION, PRESENTATION, SESSION, TRANSPORT, NETWORK, DATA_LINK, PHYSICAL, NOT_APPLICABLE)
reference optional	An additional external Reference. Example : `"[reference](#reference)"`	Reference
severity optional	The severity of this finding. Example : `"HIGH"`	enum (INFORMATIONAL, LOW, MEDIUM, HIGH)

Process

The representation of a camunda process.

Name	Description	Schema
id optional	Example : `"string"`	string
key optional	Example : `"string"`	string
name optional	Example : `"string"`	string

Reference

Reference to further details. This can be a reference to Common Vulnerabilities and Exposures, node security, owasp or other...

Name	Description	Schema
id required	The id of this reverence. Example : `"CVE-2017-15707"`	string
source required	The source of this reverence. Example : `"https://www.cvedetails.com/cve/CVE-2017-15707/"`	string

ResponseEntity

Name	Description	Schema
body optional	Example : `"object"`	object
statusCode optional	Example : `"string"`	enum (100, 101, 102, 103, 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 509, 510, 511)
statusCodeValue optional	Example : `0`	integer (int32)

ScanConfiguration

Name	Description	Schema
jobId required	Example : `"string"`	string (uuid)
targets optional	Example : `[ "[target](#target)" ]`	< Target > array

ScanFailure

The failure result of an external scan.

Name	Description	Schema
errorDetails optional	Provide more details, if there are any, why this failure happened. Example : `"It was not possible to resolve a DNS entry!"`	string
errorMessage optional	Short error message why this failure happened. Example : `"The host down.securecodebox.io is nor reachable!"`	string
scannerId required	The id of the external scanner, which provides this failure. Example : `"5dd0840c-81ae-4fed-90b5-b3eea3d4c701"`	string (uuid)

ScanResult

The result of an external scan.

Name	Description	Schema
findings optional	The prepared findings of an external scan result. Example : `[ "[finding](#finding)" ]`	< Finding > array
rawFindings optional	The raw findings provided by the scanner. This can be nearly everything. Example : `"string"`	string
scannerId required	The id of the external scanner, which provides this result. Example : `"5dd0840c-81ae-4fed-90b5-b3eea3d4c701"`	string (uuid)
scannerType required	The type of the external scanner, which provides this result. Example : `"nmap"`	string

Target

This type represents targets to scan by a scanner.

Name	Description	Schema
attributes optional	Key value pairs of target / scanner specific values. Example : `{<br> "NMAP_START_PORT" : 34,<br> "NMAP_IP" : "162.222.1.3",<br> "NMAP_END_PORT" : 125<br>}`	object
location required	The location of this target. Example : `"162.222.1.3"`	string
name required	The name of this target. Example : `"SecureCodeBox Demo Instance"`	string

SecureCodeBox API Documentation

Overview

Contact information

License information

URI scheme

Tags

Consumes

Produces

Paths

Lock a scan job for the given topic

Description

Parameters

Responses

Tags

Example HTTP request

Request path

Example HTTP response

Response 200

Response 204

Send a scan failure for the previously locked job.

Parameters

Responses

Tags

Example HTTP request

Request path

Request body

Example HTTP response

Response 200

Send a scan result for the previously locked job.

Parameters

Responses

Tags

Example HTTP request

Request path

Request body

Example HTTP response

Response 200

Returns all possible processes.

Responses

Tags

Example HTTP request

Request path

Example HTTP response

Response 200

Creates a new scan process.

Parameters

Responses

Tags

Example HTTP request

Request path

Request body

Example HTTP response

Response 200

Response 201

Definitions

Finding

Process

Reference

ResponseEntity

ScanConfiguration

ScanFailure

ScanResult

Target