diff --git a/.travis.yml b/.travis.yml index 7de726ab7d..8b073afabb 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,7 +4,7 @@ node_js: services: - docker env: - # - DEFAULT_TAG=latest + - DEFAULT_TAG=latest - DEFAULT_TAG=develop script: - cp test/.env.test .env diff --git a/README.md b/README.md index 094a2a8219..8edf1a81fa 100644 --- a/README.md +++ b/README.md @@ -125,11 +125,14 @@ The following scanners are currently available out of the box: - [Nmap][nmap] for IP and port scans - [Nikto][nikto] for web server scans - [SSLyze][sslyze] for SSL/TLS scans -- [SQLMap][sqlmap] for SQL Injection scans - [Arachni][arachni] web vulnerability scans -- [WPScan][wpscan] black box [WordPress][wordpress] vulnerability scans - [Amass][amass] for subdomain scans +In the works (coming soon) +- [SQLMap][sqlmap] for SQL Injection scans +- [WPScan][wpscan] black box [WordPress][wordpress] vulnerability scans +- [SSH Scan][sshscan] checking ssh servers for known vulnarabilities + Enabled by the architecture you can also add your own non-free or commercial tools, like - [Burp Suite][burp] web vulnerability scanner. @@ -195,6 +198,7 @@ Sponsored by [iteratec GmbH](https://www.iteratec.de/) - [arcachni]: http://www.arachni-scanner.com/ [sslyze]: https://github.com/nabla-c0d3/sslyze [sqlmap]: http://sqlmap.org/ +[sshscan]: https://github.com/mozilla/ssh_scan_api [burp]: https://portswigger.net/burp [arachni]: http://www.arachni-scanner.com/ [wpscan]: https://wpscan.org/ diff --git a/docs/developer-guide/api-doc.md b/docs/developer-guide/api-doc.md index 7273b2794f..28b2e18683 100644 --- a/docs/developer-guide/api-doc.md +++ b/docs/developer-guide/api-doc.md @@ -1,482 +1,698 @@ # SecureCodeBox API Documentation +> NOTE: This is just a static exported version of the swagger docs. If you got a running instance of the secureCodeBox engine we'd recommend to access the docs there. You can find them by under: `<>/swagger-ui.html` + ## 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. +### Version information + +_Version_ : 1.0 ### Contact information -*Contact* : SecureCodeBox-Team +_Contact_ : SecureCodeBox-Team ### License information -*License* : Apache 2.0 -*License URL* : https://github.com/secureCodeBox/engine/blob/master/LICENSE.txt -*Terms of service* : null +_License_ : Apache 2.0 +_License URL_ : https://github.com/secureCodeBox/engine/blob/master/LICENSE.txt +_Terms of service_ : null ### URI scheme -*Host* : localhost -*BasePath* : / +_Host_ : localhost +_BasePath_ : / ### Tags -* scan-job-resource : Scan Jobs Resource -* scan-process-resource : Scan Process Resource - +- scan-job-resource : For scanner-wrappers to engine communication +- security-test-definition-resource : Lists available definitions of securityTests. +- security-test-resource : Manage securityTests. ### Consumes -* `application/json` - +- `application/json` ### Produces -* `application/json` - - - +- `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. +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"`| - +| Type | Name | Description | Schema | Default | +| -------- | ---------------------------- | -------------------------------------------------------------- | ------------- | ---------------------------------------- | +| **Path** | **scannerId**
_required_ | UUID identifying the scanner instance. | string (uuid) | `"29bf7fd3-8512-4d73-a28f-608e493cd726"` | +| **Path** | **topic**
_required_ | Topic name for the Process, be sure only to use: [A-Za-z0-9-_] | string | `"nmap_portscan"` | #### Responses -|HTTP Code|Description|Schema| -|---|---|---| -|**200**|Successful retrieval of the scan Job|[ScanConfiguration](#scanconfiguration)| -|**204**|No scanjob available|[ScanConfiguration](#scanconfiguration)| -|**400**|Incomplete or inconsistent Request|No Content| -|**500**|Unknown technical error occurred.|No Content| - +| HTTP Code | Description | Schema | +| --------- | ----------------------------------------------------------------------------- | --------------------------------------- | +| **200** | Successful retrieval of the scan job | [ScanConfiguration](#scanconfiguration) | +| **204** | No scan job available | [ScanConfiguration](#scanconfiguration) | +| **400** | Incomplete or inconsistent Request | No Content | +| **401** | Unauthenticated | No Content | +| **403** | Unauthorized, the user is missing the required rights to perform this action. | No Content | +| **500** | Unknown technical error occurred. | No Content | #### Tags -* scan-job-resource +- scan-job-resource + +#### Security +| Type | Name | +| --------- | --------------------------- | +| **basic** | **[basicAuth](#basicauth)** | #### Example HTTP request ##### Request path + ``` /box/jobs/lock/nmap_portscan/29bf7fd3-8512-4d73-a28f-608e493cd726 ``` - #### Example HTTP response ##### Response 200 -``` -json : + +```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" - } ] + "jobId": "string", + "targets": [ + { + "attributes": { + "NMAP_PARAMETER": "-Pn" + }, + "location": "127.0.0.1", + "name": "SecureCodeBox Demo Website" + } + ] } ``` - ##### Response 204 -``` -json : + +```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" - } ] + "jobId": "string", + "targets": [ + { + "attributes": { + "NMAP_PARAMETER": "-Pn" + }, + "location": "127.0.0.1", + "name": "SecureCodeBox Demo Website" + } + ] } ``` - + ### 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](#scanfailure)|| - +| Type | Name | Description | Schema | Default | +| -------- | ------------------------- | ---------------- | --------------------------- | ---------------------------------------- | +| **Path** | **id**
_required_ | UUID of the job. | string (uuid) | `"29bf7fd3-8512-4d73-a28f-608e493cd726"` | +| **Body** | **result**
_required_ | result | [ScanFailure](#scanfailure) | | #### Responses -|HTTP Code|Description|Schema| -|---|---|---| -|**200**|Successful delivery of the failure.|[ResponseEntity](#responseentity)| -|**400**|Incomplete or inconsistent Request|No Content| -|**500**|Unknown technical error occurred.|No Content| - +| HTTP Code | Description | Schema | +| --------- | ----------------------------------------------------------------------------- | --------------------------------- | +| **200** | Successful delivery of the failure. | [ResponseEntity](#responseentity) | +| **400** | Incomplete or inconsistent Request | No Content | +| **401** | Unauthenticated | No Content | +| **403** | Unauthorized, the user is missing the required rights to perform this action. | No Content | +| **404** | Unable to find jobId | No Content | +| **500** | Unknown technical error occurred. | No Content | #### Tags -* scan-job-resource +- scan-job-resource +#### Security + +| Type | Name | +| --------- | --------------------------- | +| **basic** | **[basicAuth](#basicauth)** | #### Example HTTP request ##### Request path + ``` /box/jobs/29bf7fd3-8512-4d73-a28f-608e493cd726/failure ``` - ##### Request body -``` -json : + +```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" + "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 : + +```json { - "body" : "object", - "statusCode" : "string", - "statusCodeValue" : 0 + "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](#scanresult)|| - +| Type | Name | Description | Schema | Default | +| -------- | ------------------------- | ---------------- | ------------------------- | ---------------------------------------- | +| **Path** | **id**
_required_ | UUID of the job. | string (uuid) | `"29bf7fd3-8512-4d73-a28f-608e493cd726"` | +| **Body** | **result**
_required_ | result | [ScanResult](#scanresult) | | #### Responses -|HTTP Code|Description|Schema| -|---|---|---| -|**200**|Successful delivery of the result.|[ResponseEntity](#responseentity)| -|**400**|Incomplete or inconsistent Request|No Content| -|**500**|Unknown technical error occurred.|No Content| - +| HTTP Code | Description | Schema | +| --------- | ----------------------------------------------------------------------------- | --------------------------------- | +| **200** | Successful delivery of the result. | [ResponseEntity](#responseentity) | +| **400** | Incomplete or inconsistent Request | No Content | +| **401** | Unauthenticated | No Content | +| **403** | Unauthorized, the user is missing the required rights to perform this action. | No Content | +| **404** | Unable to find jobId | No Content | +| **500** | Unknown technical error occurred. | No Content | #### Tags -* scan-job-resource +- scan-job-resource +#### Security + +| Type | Name | +| --------- | --------------------------- | +| **basic** | **[basicAuth](#basicauth)** | #### Example HTTP request ##### Request path + ``` /box/jobs/29bf7fd3-8512-4d73-a28f-608e493cd726/result ``` - ##### Request body -``` -json : + +```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" + "findings": [ + { + "attributes": { + "NMAP_PORT": 34, + "NMAP_IP": "162.222.1.3" + }, + "category": "Infrastructure", + "description": "The DNS Port is open.", + "false_positive": false, + "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 : + +```json { - "body" : "object", - "statusCode" : "string", - "statusCodeValue" : 0 + "body": "object", + "statusCode": "string", + "statusCodeValue": 0 } ``` + + +### Starts new securityTests. - -### Returns all possible processes. ``` -GET /box/processes/ +PUT /box/securityTests ``` +#### Description -#### Responses +Starts new securityTests, based on a given list of securityTest configurations. + +#### Parameters + +| Type | Name | Description | Schema | +| -------- | -------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- | +| **Body** | **securityTests**
_required_ | A list with all securityTest which should be performed. | < [SecurityTestConfiguration](#securitytestconfiguration) > array | -|HTTP Code|Description|Schema| -|---|---|---| -|**200**|Returns a list of all available processes.|< [Process](#process) > array| -|**400**|Incomplete or inconsistent Request|No Content| -|**500**|Unknown technical error occurred.|No Content| +#### Responses +| HTTP Code | Description | Schema | +| --------- | ---------------------------------------------------------------------------------------------------- | ----------------------- | +| **200** | OK | < string (uuid) > array | +| **201** | Successful created a new securityTest returns the process id. | < string (uuid) > array | +| **300** | For some reason multiple securityTest definitions could be addressed by the given securityTest name. | No Content | +| **400** | Incomplete or inconsistent Request. | No Content | +| **401** | Unauthenticated | No Content | +| **403** | Unauthorized, the user is missing the required rights to perform this action. | No Content | +| **404** | Could not find definition for specified securityTest. | No Content | +| **500** | Unknown technical error occurred. | No Content | #### Tags -* scan-process-resource +- security-test-resource + +#### Security +| Type | Name | +| --------- | --------------------------- | +| **basic** | **[basicAuth](#basicauth)** | #### Example HTTP request ##### Request path + ``` -/box/processes/ +/box/securityTests ``` +##### Request body + +```json +[ + { + "context": "Feature Team 1", + "metaData": { + "string": "string" + }, + "name": "nmap", + "target": { + "attributes": { + "NMAP_PARAMETER": "-Pn" + }, + "location": "127.0.0.1", + "name": "SecureCodeBox Demo Website" + } + } +] +``` #### Example HTTP response ##### Response 200 -``` -json : -[ { - "id" : "string", - "key" : "string", - "name" : "string" -} ] + +```json +["string"] ``` +##### Response 201 - -### Creates a new scan process. +```json +["string"] ``` -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](#target) > array| +### Lists all available securityTest definitions. +``` +GET /box/securityTests/definitions +``` #### 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| - +| HTTP Code | Description | Schema | +| --------- | ----------------------------------------------------------------------------- | ----------------------- | +| **200** | Successfully listed all available securityTest definitions. | < string (uuid) > array | +| **401** | Unauthenticated | No Content | +| **403** | Unauthorized, the user is missing the required rights to perform this action. | No Content | +| **500** | Unknown technical error occurred. | No Content | #### Tags -* scan-process-resource +- security-test-definition-resource + +#### Security +| Type | Name | +| --------- | --------------------------- | +| **basic** | **[basicAuth](#basicauth)** | #### Example HTTP request ##### Request path + ``` -/box/processes/nmap-process +/box/securityTests/definitions ``` +#### Example HTTP response + +##### Response 200 -##### 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" -} ] +```json +["string"] ``` + -#### Example HTTP response +### Returns the state of a securityTests. -##### Response 200 ``` -json : -"string" +GET /box/securityTests/{id} ``` +#### Description + +Currently only supports finished securityTests. + +#### Parameters + +| Type | Name | Description | Schema | +| -------- | --------------------- | ----------------------------------------------------------------- | ------------- | +| **Path** | **id**
_required_ | UUID of the security-test for which the report should be fetched. | string (uuid) | + +#### Responses + +| HTTP Code | Description | Schema | +| --------- | ----------------------------------------------------------------------------- | ----------------------------- | +| **200** | Successful fetched the complete securityTest. | [SecurityTest](#securitytest) | +| **206** | Partial result as the SecurityTest hasn't finished yet. | [SecurityTest](#securitytest) | +| **400** | Incomplete or inconsistent Request. | No Content | +| **401** | Unauthenticated | No Content | +| **403** | Unauthorized, the user is missing the required rights to perform this action. | No Content | +| **404** | Could not find definition for specified securityTest. | No Content | +| **500** | Unknown technical error occurred. | No Content | + +#### Tags + +- security-test-resource + +#### Security + +| Type | Name | +| --------- | --------------------------- | +| **basic** | **[basicAuth](#basicauth)** | + +#### Example HTTP request + +##### Request path -##### Response 201 ``` -json : -"string" +/box/securityTests/string ``` +#### Example HTTP response +##### Response 200 +```json +{ + "context": "Feature Team 1", + "finished": true, + "id": "string", + "metaData": { + "string": "string" + }, + "name": "nmap", + "report": { + "findings": [ + { + "attributes": { + "NMAP_PORT": 34, + "NMAP_IP": "162.222.1.3" + }, + "category": "Infrastructure", + "description": "The DNS Port is open.", + "false_positive": false, + "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" + } + ], + "raw_findings": "string", + "report_id": "4e598d7c-5872-4aa0-8e01-770312a00847", + "severity_highest": "HIGH", + "severity_overview": { + "INFORMATIONAL": 13 + } + }, + "target": { + "attributes": { + "NMAP_PARAMETER": "-Pn" + }, + "location": "127.0.0.1", + "name": "SecureCodeBox Demo Website" + } +} +``` - -## Definitions - - -### Finding -This type represents findings found by a scanner. +##### Response 206 +```json +{ + "context": "Feature Team 1", + "finished": true, + "id": "string", + "metaData": { + "string": "string" + }, + "name": "nmap", + "report": { + "findings": [ + { + "attributes": { + "NMAP_PORT": 34, + "NMAP_IP": "162.222.1.3" + }, + "category": "Infrastructure", + "description": "The DNS Port is open.", + "false_positive": false, + "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" + } + ], + "raw_findings": "string", + "report_id": "4e598d7c-5872-4aa0-8e01-770312a00847", + "severity_highest": "HIGH", + "severity_overview": { + "INFORMATIONAL": 13 + } + }, + "target": { + "attributes": { + "NMAP_PARAMETER": "-Pn" + }, + "location": "127.0.0.1", + "name": "SecureCodeBox Demo Website" + } +} +``` -|Name|Description|Schema| -|---|---|---| -|**attributes**
*optional*|Key value pairs of scanner specific values.
**Example** : `{
"NMAP_PORT" : 34,
"NMAP_IP" : "162.222.1.3"
}`|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](#reference)| -|**severity**
*optional*|The severity of this finding.
**Example** : `"HIGH"`|enum (INFORMATIONAL, LOW, MEDIUM, HIGH)| + +## Definitions - -### Process -The representation of a camunda process. + +### Finding -|Name|Description|Schema| -|---|---|---| -|**id**
*optional*|**Example** : `"string"`|string| -|**key**
*optional*|**Example** : `"string"`|string| -|**name**
*optional*|**Example** : `"string"`|string| +This type represents findings found by a scanner. +| Name | Description | Schema | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| **attributes**
_optional_ | Key value pairs of scanner specific values.
**Example** : `{
"NMAP_PORT" : 34,
"NMAP_IP" : "162.222.1.3"
}` | 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 | +| **false_positive**
_optional_ | If the finding is a false positive.
**Example** : `false` | boolean | +| **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](#reference) | +| **severity**
_optional_ | The severity of this finding.
**Example** : `"HIGH"` | enum (INFORMATIONAL, LOW, MEDIUM, HIGH) | + ### 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 | -|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| + +### Report + +| Name | Description | Schema | +| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| **findings**
_optional_ | **Example** : `[ "[finding](#finding)" ]` | < [Finding](#finding) > array | +| **raw_findings**
_optional_ | **Example** : `"string"` | string | +| **report_id**
_optional_ | Id for the report.
**Example** : `"4e598d7c-5872-4aa0-8e01-770312a00847"` | string (uuid) | +| **severity_highest**
_optional_ | The most severe severity in the findings.
**Example** : `"HIGH"` | enum (INFORMATIONAL, LOW, MEDIUM, HIGH) | +| **severity_overview**
_optional_ | Gives an overview of the occurrences of different severities in the findings.
**Example** : `{
"INFORMATIONAL" : 13
}` | < string, integer (int64) > map | -### 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)| +### ResponseEntity +| Name | Description | Schema | +| ---------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **body**
_optional_ | **Example** : `"object"` | object | +| **statusCode**
_optional_ | **Example** : `"string"` | enum (100 CONTINUE, 101 SWITCHING_PROTOCOLS, 102 PROCESSING, 103 CHECKPOINT, 200 OK, 201 CREATED, 202 ACCEPTED, 203 NON_AUTHORITATIVE_INFORMATION, 204 NO_CONTENT, 205 RESET_CONTENT, 206 PARTIAL_CONTENT, 207 MULTI_STATUS, 208 ALREADY_REPORTED, 226 IM_USED, 300 MULTIPLE_CHOICES, 301 MOVED_PERMANENTLY, 302 FOUND, 302 MOVED_TEMPORARILY, 303 SEE_OTHER, 304 NOT_MODIFIED, 305 USE_PROXY, 307 TEMPORARY_REDIRECT, 308 PERMANENT_REDIRECT, 400 BAD_REQUEST, 401 UNAUTHORIZED, 402 PAYMENT_REQUIRED, 403 FORBIDDEN, 404 NOT_FOUND, 405 METHOD_NOT_ALLOWED, 406 NOT_ACCEPTABLE, 407 PROXY_AUTHENTICATION_REQUIRED, 408 REQUEST_TIMEOUT, 409 CONFLICT, 410 GONE, 411 LENGTH_REQUIRED, 412 PRECONDITION_FAILED, 413 PAYLOAD_TOO_LARGE, 413 REQUEST_ENTITY_TOO_LARGE, 414 URI_TOO_LONG, 414 REQUEST_URI_TOO_LONG, 415 UNSUPPORTED_MEDIA_TYPE, 416 REQUESTED_RANGE_NOT_SATISFIABLE, 417 EXPECTATION_FAILED, 418 I_AM_A_TEAPOT, 419 INSUFFICIENT_SPACE_ON_RESOURCE, 420 METHOD_FAILURE, 421 DESTINATION_LOCKED, 422 UNPROCESSABLE_ENTITY, 423 LOCKED, 424 FAILED_DEPENDENCY, 426 UPGRADE_REQUIRED, 428 PRECONDITION_REQUIRED, 429 TOO_MANY_REQUESTS, 431 REQUEST_HEADER_FIELDS_TOO_LARGE, 451 UNAVAILABLE_FOR_LEGAL_REASONS, 500 INTERNAL_SERVER_ERROR, 501 NOT_IMPLEMENTED, 502 BAD_GATEWAY, 503 SERVICE_UNAVAILABLE, 504 GATEWAY_TIMEOUT, 505 HTTP_VERSION_NOT_SUPPORTED, 506 VARIANT_ALSO_NEGOTIATES, 507 INSUFFICIENT_STORAGE, 508 LOOP_DETECTED, 509 BANDWIDTH_LIMIT_EXCEEDED, 510 NOT_EXTENDED, 511 NETWORK_AUTHENTICATION_REQUIRED) | +| **statusCodeValue**
_optional_ | **Example** : `0` | integer (int32) | -### ScanConfiguration -|Name|Description|Schema| -|---|---|---| -|**jobId**
*required*|**Example** : `"string"`|string (uuid)| -|**targets**
*optional*|**Example** : `[ "[target](#target)" ]`|< [Target](#target) > array| +### ScanConfiguration +| Name | Description | Schema | +| -------------------------- | --------------------------------------- | --------------------------- | +| **jobId**
_required_ | **Example** : `"string"` | string (uuid) | +| **targets**
_optional_ | **Example** : `[ "[target](#target)" ]` | < [Target](#target) > array | -### ScanFailure -The failure result of an external scan. +### ScanFailure -|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)| +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](#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 | + + + +### SecurityTest + +| Name | Description | Schema | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| **context**
_optional_ | Context references the larger scope the security test. In most cases this is equal to the name of the project, team name or a domain.
**Example** : `"Feature Team 1"` | string | +| **finished**
_optional_ | Indicates weather the process was completed.
**Example** : `true` | boolean | +| **id**
_optional_ | **Example** : `"string"` | string (uuid) | +| **metaData**
_optional_ | **Example** : `{
"string" : "string"
}` | < string, string > map | +| **name**
_optional_ | The Name of the security test to perform on the target.
**Example** : `"nmap"` | string | +| **report**
_optional_ | **Example** : `"[report](#report)"` | [Report](#report) | +| **target**
_optional_ | The target configuration of the security test.
**Example** : `"[target](#target)"` | [Target](#target) | -|Name|Description|Schema| -|---|---|---| -|**findings**
*optional*|The prepared findings of an external scan result.
**Example** : `[ "[finding](#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| + +### SecurityTestConfiguration + +| Name | Description | Schema | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| **context**
_optional_ | Context references the larger scope the security test. In most cases this is equal to the name of the project, team name or a domain.
**Example** : `"Feature Team 1"` | string | +| **metaData**
_optional_ | **Example** : `{
"string" : "string"
}` | < string, string > map | +| **name**
_optional_ | The Name of the security test to perform on the target.
**Example** : `"nmap"` | string | +| **target**
_optional_ | The target configuration of the security test.
**Example** : `"[target](#target)"` | [Target](#target) | + ### Target -This type represents targets to scan by a scanner. +This type represents targets to scan by a scanner. -|Name|Description|Schema| -|---|---|---| -|**attributes**
*optional*|Key value pairs of target / scanner specific values.
**Example** : `{
"NMAP_START_PORT" : 34,
"NMAP_IP" : "162.222.1.3",
"NMAP_END_PORT" : 125
}`|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| +| Name | Description | Schema | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| **attributes**
_optional_ | Key (in upper case) / value pairs of target / scanner specific configuration options.
**Example** : `{
"NMAP_PARAMETER" : "-Pn"
}` | object | +| **location**
_required_ | The location of this target, this could be a URL, Hostname or IP-Address.
**Example** : `"127.0.0.1"` | string | +| **name**
_required_ | The name of this target.
**Example** : `"SecureCodeBox Demo Website"` | string | + +## Security + +### basicAuth +_Type_ : basic diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md index 2d30ab4111..e4ece70ae2 100644 --- a/docs/user-guide/README.md +++ b/docs/user-guide/README.md @@ -66,26 +66,30 @@ The secureCodeBox can save the security tests results into different data stores MetaFields can be used to tag security tests with custom data relevant for you. We have encountered some data values which we found paticulary usefull and standardized their format to be used in multiple places. The list and formats can be found [here](./metafields/README.md). -## Starting Scan-Processes using the REST-API +## Starting securityTests using the REST-API In order to start a scan via the REST-API, send a PUT-Request to the following URL: -`/box/processes/$PROCESS_KEY` with `$PROCESS_KEY` being the id defined in the respective BPMN file. As an example, the URL for starting an Nmap scan with SecureCodeBox running on localhost would be `http://localhost:8080/box/processes/nmap-process`. +`<>/box/securityTests`. -The scanning target is set within the payload: +The scanning target is set within the payload. A securityTest running a nmap port scan woud look like this: ```json [ { - "name": "Local Test", - "location": "localhost", - "attributes": { - "NMAP_PARAMETER": "-O" + "name": "nmap", + "context": "Feature Team 1", + "target": { + "name": "example.com website", + "location": "example.com", + "attributes": { + "NMAP_PARAMETER": "-Pn" + } } } ] ``` -You can check out a more detailed API documentation in the Swagger Docs of the secureCodeBox Engine. The Swagger Docs come together with the secureCodeBox Engine. You can access it at `http://localhost:8080/swagger-ui.html#/scan-process-resource` (you need to have the engine running on localhost). +You can check out a more detailed API documentation in the Swagger Docs of the secureCodeBox Engine. The Swagger Docs come together with the secureCodeBox Engine. You can access it at `<>/swagger-ui.html`. If you dont have one running yet you can look at the staticly exported version of it here: [Static API Docs](../developer-guide/api-doc.md) ### In Depth Scan Examples