SecureCodeBox Engine – the Core

This is the main component of the secureCodeBox it's a Camunda BPMN engine, which allows the engineer to build the whole scan process as a BPMN model. This component also provides the main web UI: The secureCodeBox control center. In this UI you can see the available scan process definitions as BPMN diagrams, start them (Tasklist), and manually review the results. Furthermore, the core provides a possibility to listen on webhooks and integrate the exposed process API, allowing us to trigger the scan processes by a continuous integration component, such as Jenkins, in our example, or any other which can deal with webhooks.

Important note: The secureCodeBox is no simple one-button-click-solution! You must have a deep understanding of security and how to configure the scanners. Furthermore, an understanding ot the scan results and how to interpret them is also necessary.

Further Documentation:

• Project Description
• Developer Guide
• User Guide

Configuration Options

To configure the SCB engine specify the following environment variables:

| Environment Variable | Description | Example Value | | ------------------------------------- | ------------------------------------- | --------------------------- | | SECURECODEBOX_DEFAULT_TARGET_NAME | Default target identifier | BodgeIT Public Host | | SECURECODEBOX_DEFAULT_TARGET_LOCATION | Default target hostname/ip address | bodgeit | | SECURECODEBOX_DEFAULT_TARGET_URI | Default target URI/URL | http://bodgeit:8080/bodgeit | | SECURECODEBOX_DEFAULT_CONTEXT | Default business context | BodgeIT | | SECURECODEBOX_USER_SCANNER | Default user for scanner services | default-scanner | | SECURECODEBOX_USER_SCANNER_PW | Default password for scanner services | AStrongPassword-NotThisOne! |

Server Configuration

Additionally all properties defined in scb-engine/src/main/resources/application.yaml can be overwritten via environment variables. This allows you to e.g. enable https using:

| Environment Variable | Description | Example Value | | ------------------------------------- | ------------------------------------- | --------------------------- | | SERVER_PORT | Defines the server port | 8443 | | SERVER_SSL_ENABLED | Enables http over ssl | true | | SERVER_SSL_KEY_STORE_PASSWORD | Password to the java keystore | AStrongPassword-NotThisOne! |

Persistence Provider Configuration

A more detailed description of all persistence specific integration configuration options can be fund here: secureCodeBox Integration Documentation

Enabling Elasticsearch as Persistence Provider

All properties defined in scb-engine/src/main/resources/application.yaml can be overwritten via environment variables.

| Property | Example Value | | ---------------------------------------------------- | -------------------------- | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_ENABLED | true | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_HOST | elasticsearch.example.com | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_PORT | 9200 | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_INDEX_PREFIX | securecodebox |

Configure Elasticsearch Basic Authentication

If your elasticsearch service enforces authentication your can configure basic authentication:

| Property | Example Value | | ----------------------------------------------------------- | --------------------------- | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_AUTH | basic | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_AUTH_BASIC_USERNAME | elastic | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_AUTH_BASIC_PASSWORD | AStrongPassword-NotThisOne! |

Configure Elasticsearch API Token Authentication

If your elasticsearch service enforces authentication your can configure api token based authentication:

| Property | Example Value | | ----------------------------------------------------------- | --------------------------- | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_AUTH | token | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_AUTH_APIKEY_ID | yourToken | | SECURECODEBOX_PERSISTENCE_ELASTICSEARCH_AUTH_APIKEY_SECRET | 7fd7eac6fed567b19932492347 |

Enabling DefectDojo as Persistence Provider

All properties defined in scb-engine/src/main/resources/application.yaml can be overwritten via environment variables.

Properties / Environment Variables

| Property | Example Value | | ---------------------------------------------- | ---------------------------------------- | | SECURECODEBOX_PERSISTENCE_DEFECTDOJO_ENABLED | true | | SECURECODEBOX_PERSISTENCE_DEFECTDOJO_URL | http://localhost:8000 | | SECURECODEBOX_PERSISTENCE_DEFECTDOJO_AUTH_KEY | 7fd7eac6fed567b19928f7928a7ddb86f0497e4e | | SECURECODEBOX_PERSISTENCE_DEFECTDOJO_AUTH_NAME | admin |

Alternatively the corresponding environment variables, e.g. SECURECODEBOX_PERSISTENCE_DEFECTDOJO_URL can be used.

Development

Local setup

1. Clone the repository
2. You might need to install some dependencies java, maven
3. Run locally mvn spring-boot:run -Pdev

Test

To run the testsuite run:

mvn test

Build

To build the docker image run:

docker build -t IMAGE_NAME .

Generating the API Docs

1. Run the Test Suite using the docs maven profile: mvn test -P docs. This should generate a swagger.json file in the target folder of the scb-engine module.
2. Run the swagger2markup:convertSwagger2markup plugin: mvn -P docs swagger2markup:convertSwagger2markup. This should generate a file located docs/api-doc.md in the target folder of the scb-engine module.
3. Copy the api-doc.md file to the user guide of the secureCodeBox repository.
4. Re Add the first disclaimer paragraph pointing the users to the dynamic swagger docs of their engine. This has to be added by hand as it is not included in the export.
5. (Optional) Reformat the generated markdown file with prettier to improve the generated markdown output.

Guidelines & Standards

Well boring yes - but please read our guidelines and naming standards.