1. About

About SecHub

SecHub is an acronym for Security Hub and is first of all one API to scan for different security problems. Users of SecHub do not care about which exact product is doing the real scan on server side, but only configure their wanted aim.

SecHub does NOT provide a security infrastructure but does orchestrate different security products/tools.

So you still need an existing security infrastructure behind SecHub !

It was designed to be very easy to integrate into any existing build pipeline / contionus integration (CI) and helps to provide SecDevOps.

You can get more information about from SecHub web page .

The project is hosted at https://github.com/mercedes-benz/sechub

About documentation

This documentation is part of SecHub.

Key Value Information

LICENSE

MIT License

Please look at https://github.com/mercedes-benz/sechub/blob/master/LICENSE

Documentation version: Server 1.6.0 - Build date: 20240226101315

Target audience for this document are SecHub Operators/Administrators.


2. SecHub Server

2.1. Download

You can download the ready to use .jar binary of SecHub Server.

Download link to the latest SecHub Server release: https://mercedes-benz.github.io/sechub/latest/server-download.html For documentation, please look at SecHub web page .

2.2. Configuration

2.2.1. Database configuration

2.2.1.1. PostgreSQL

First of all, install a PostgreSQL database.

Then define following environment entries before you start the server with active postgres profile:

  • POSTGRES_DB_URL

  • POSTGRES_DB_USERNAME

  • POSTGRES_DB_PASSWORD

Examples:

POSTGRES_DB_URL=jdbc:postgresql://127.0.0.1:49152/sechub
POSTGRES_DB_USERNAME=sechub-pg-admin
POSTGRES_DB_PASSWORD=a-very-strong-password...

2.2.2. General configuration

SecHub can be configured by keys on server startup. Using the spring @Value annotation we are able to use these keys as Java system properties but also as environment entries.

E.g. a key like sechub.server.baseurl can be set with

java ... -Dsechub.server.baseurl=https://sechub.example.org

or with an environment entry SECHUB_SERVER_BASEURL which is e.g. more suitable for a kubernetes cluster deployment.

The next text blocks describe the keys available on SecHub:

Table 1. Scope 'administration'
Key Default Description

sechub.feature.showProductResultLink

false

Administrators can turn on this mode to allow product links in json and HTML output

sechub.notification.scheduler.startup.enabled

true

When enabled, administrators will be informed by notification when new scheduler instances are started. Those notifications will also contain information about potential zombie jobs.

When disabled, incoming events will be ignored and no notification sent.

Table 2. Scope 'anonymous'
Key Default Description

sechub.user.onetimetoken.outdated.millis

86400000

One time token time when outdating

Table 3. Scope 'checkmarx'
Key Default Description

sechub.adapter.checkmarx.resilience.badrequest.retry.max

3

Amount of retries done when a 400 bad request happened on Checkmarx server

sechub.adapter.checkmarx.resilience.badrequest.retry.wait

2000

Time to wait until retry is done when a 400 bad request happened on Checkmarx server

sechub.adapter.checkmarx.resilience.servererror.retry.max

1

Amount of retries done when a 500 server internal error happened on Checkmarx server

sechub.adapter.checkmarx.resilience.servererror.retry.wait

5000

Time to wait until retry is done when a 500 server internal error happened on Checkmarx server

sechub.adapter.checkmarx.scanresultcheck.period.minutes

-1

Time in minutes when adapter check operation is called next. When -1 value is 1 minutes

sechub.adapter.checkmarx.scanresultcheck.timeout.minutes

-1

Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes

sechub.adapter.checkmarx.trustall

false

Turns off certification checks for this product only. Should only be used in test or development environments!

Table 4. Scope 'initial'
Key Default Description

sechub.initialadmin.apitoken

An apitoken for initial admin, will only be used in DEV and INTEGRATIONTEST profiles and is optional!

sechub.initialadmin.email

Mail of initial administrator

sechub.initialadmin.userid

Userid of initial administrator

Table 5. Scope 'migration'
Key Default Description

sechub.migration.flyway.autorepair

true

When enabled, flyway migration problems will be automatically repaired

Table 6. Scope 'mock'
Key Default Description

sechub.notification.email.mock.cache.enabled

false

When email mock shall cache the mails this must be configured to true, per default disabled!

Table 7. Scope 'nessus'
Key Default Description

sechub.adapter.nessus.defaultpolicyid

deprecated

Default policy ID for nessus scans

sechub.adapter.nessus.internet.baseurl

deprecated

Base url of nessus used for internet scans

sechub.adapter.nessus.internet.password

deprecated

Password for nessus instance used for internet scans

sechub.adapter.nessus.internet.userid

deprecated

User id of nessus user (internet)

sechub.adapter.nessus.intranet.baseurl

deprecated

Base url of nessus used for intranet scans

sechub.adapter.nessus.intranet.password

deprecated

Password for nessus instance used for intranet scans

sechub.adapter.nessus.intranet.userid

deprecated

User id of nessus user (intranet)

sechub.adapter.nessus.proxy.hostname

Proxy hostname for nessus server connection, when empty no proxy is used. When not empty proxy port must be set too!

sechub.adapter.nessus.proxy.port

0

Proxy port for nessus server connection, default is 0. If you are setting a proxy hostname you have to configure this value correctly

sechub.adapter.nessus.scanresultcheck.period.minutes

-1

Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes

sechub.adapter.nessus.scanresultcheck.timeout.minutes

-1

Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes

sechub.adapter.nessus.trustall

true

Turns off certification checks for this product only. Should only be used in test or development environments!

Table 8. Scope 'netsparker'
Key Default Description

sechub.adapter.netsparker.agentname

deprecated

The name of the agent to be used by netsparker. If a agent group name is already defined the group will be superiour. If no group set and no agent name netsparker will use a agent but seems to be unpredictable which agent will be used.

sechub.adapter.netsparker.apitoken

deprecated

API token for netsparker user

sechub.adapter.netsparker.baseurl

deprecated

Base url for netsparker installation

sechub.adapter.netsparker.defaultpolicyid

deprecated

Default policy ID for netsparker scans

sechub.adapter.netsparker.internet.agentgroupname

deprecated

The name of the agent group to be used by netsparker for intranet scans. If not set no agent group will be used.

sechub.adapter.netsparker.intranet.agentgroupname

deprecated

The name of the agent group to be used by netsparker for intranet scans. If not set no agent group will be used.

sechub.adapter.netsparker.licenseid

deprecated

sechub.adapter.netsparker.scanresultcheck.period.minutes

-1

Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes

sechub.adapter.netsparker.scanresultcheck.timeout.minutes

-1

Time in minutes when adapter check operation is called next. When -1 value is 1 minutes

sechub.adapter.netsparker.trustall

true

Turns off certification checks for this product only. Should only be used in test or development environments!

sechub.adapter.netsparker.userid

deprecated

user id of netsparker user

Table 9. Scope 'new'
Key Default Description

sechub.user.onetimetoken.outdated.millis

86400000

Time until the one time token expires

Table 10. Scope 'notification'
Key Default Description

sechub.notification.email.administrators

Single email address used for emails to administrators. This should be a NPM (non personalized mailbox)

sechub.notification.email.from

Address used for emails sent by sechub system

sechub.notification.email.replyto

Address used for reply when email was sent by sechub system

Table 11. Scope 'p'
Key Default Description

sechub.adapter.checkmarx.resilience.badrequest.retry.max

3

Amount of retries done when a 400 bad request happened on Checkmarx server

sechub.adapter.checkmarx.resilience.badrequest.retry.wait

2000

Time to wait until retry is done when a 400 bad request happened on Checkmarx server

sechub.adapter.checkmarx.resilience.servererror.retry.max

1

Amount of retries done when a 500 server internal error happened on Checkmarx server

sechub.adapter.checkmarx.resilience.servererror.retry.wait

5000

Time to wait until retry is done when a 500 server internal error happened on Checkmarx server

sechub.adapter.pds.default.check.timetowait.milliseconds

30000

Time in milliseconds when adapter check operation is called next. When -1 value is 60000 minutes

sechub.adapter.pds.default.timeout.minutes

240

Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes

Table 12. Scope 's'
Key Default Description

sechub.notification.smtp.config

mail.smtp.auth=false,mail.transport.protocol=smtp

SMTP configuration map. You can setup all java mail smtp settings here in comma separate form with key=value. For Example: mail.smtp.auth=false,mail.smtp.timeout=4000. See https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html for configuration mapping

sechub.notification.smtp.credential.password

Password on SMPTP server, empty value means no password

sechub.notification.smtp.credential.username

Username on SMPTP server, empty value means no username

sechub.notification.smtp.hostname

Hostname of SMPTP server

sechub.notification.smtp.port

25

Port of SMPTP server, per default:25

Table 13. Scope 'scan'
Key Default Description

sechub.config.check.canceljob.delay

60000

Define delay in milliseconds, for before next job cancellation check will be executed.

sechub.config.scan.scanconfig.refresh.delay

5000

Define delay (in milliseconds) for next job execution trigger after last executed.

sechub.config.scan.scanconfig.refresh.initialdelay

0

Define initial delay (in milliseconds) for scan config refresh check operation.

Table 14. Scope 'scheduler'
Key Default Description

sechub.config.trigger.healthcheck.enabled

true

When enabled each trigger will do an healtching by monitoring service. If system has too much CPU load or uses too much memory, the trigger will not execute until memory and CPU load is at normal level!

sechub.config.trigger.nextjob.delay

10000

Define delay for next job execution trigger after last executed.

sechub.config.trigger.nextjob.initialdelay

5000

Define initial delay for next job execution trigger. Interesting inside a cluster - just define this value different inside your instances (e.g. random value). This avoids write operations at same time.

sechub.config.trigger.nextjob.maxwaitretry

300

When retry mechanism is enabled by sechub.config.trigger.nextjob.retries, and a retry is necessary, this value is used to define the maximum time period in millis which will be waited before retry. Why max value? Because cluster instances seems to be created often on exact same time by kubernetes. So having here a max value will result in a randomized wait time so cluster members will do fetch operations time shifted and automatically reduce collisions!

sechub.config.trigger.nextjob.retries

5

Inside a cluster the next job fetching can lead to concurrent access. When this happens a retry can be done for the 'looser'. This value defines the amount of *tries*If you do not want any retries set the value to a value lower than 2. 2 Means after one execution failed there is one retry. Values lower than 2 will lead to one try of execution only.

sechub.scheduler.strategy.id

Define the scheduler strategy by given identifier. This strategy determines the next job which shall be executed by job scheduler. Possible values are:first-come-first-serve,only-one-scan-per-project-at-a-time and only-one-scan-per-project-and-module-group

sechub.server.upload.validate.checksum

true

With false source code checksum validation (sha256) on sechub server side is disabled. Sha256 validation must be done by the delegated security products! You should disable the validation only for testing security product behaviours!

sechub.server.upload.validate.zip

true

With false ZIP validation on sechub server side is disabled. ZIP validation must be done by the delegated security products! You should disable the validation only for testing security product behaviours!

sechub.upload.binaries.maximum.bytes

52428800

Define the maximum amount of bytes accepted for uploading binaries.tar. The default when not set is 52428800 (50 MiB)

Table 15. Scope 'sec'
Key Default Description

sechub.project.joblist.page.max

100

sechub.project.joblist.size.max

100

Maximum limit for job information list entries per page

sechub.server.baseurl

Base url of SecHub server - e.g. https://sechub.example.org

Table 16. Scope 'security'
Key Default Description

sechub.security.diffiehellman.length

Define diffie hellman key length, see https://github.com/mercedes-benz/sechub/issues/689 for details

Table 17. Scope 'server'
Key Default Description

sechub.server.debug

false

When debug flag is set, rest call reponse error messages do also contain stacktraces.

Table 18. Scope 'storage'
Key Default Description

sechub.storage.s3.accesskey

undefined

Defines the access key for used S3 bucket

sechub.storage.s3.bucketname

undefined

Defines the S3 bucket name

sechub.storage.s3.connection.idle.max.milliseconds

60000

S3 client maximum idle time (in milliseconds) for a connection in the connection pool.

sechub.storage.s3.connection.idle.validate.milliseconds

5000

S3 client time (in milliseconds) a connection can be idle in the connection pool before it must be validated that it’s still open.

sechub.storage.s3.connection.max.poolsize

50

S3 client max connection pool size.

sechub.storage.s3.connection.ttl.milliseconds

-1

S3 client expiration time (in milliseconds) for a connection in the connection pool. -1 means deactivated

sechub.storage.s3.endpoint

undefined

Defines the S3 endpoint - e.g. https://play.min.io

sechub.storage.s3.secretkey

undefined

Defines the secret key for used S3 bucket

sechub.storage.s3.signer.override

AWSS3V4SignerType

Can be used to override the default name of the signature algorithm used to sign requests.

sechub.storage.s3.timeout.connection.milliseconds

10000

S3 client timeout (in milliseconds) for creating new connections.

sechub.storage.s3.timeout.execution.milliseconds

0

S3 client timeout (in milliseconds) for execution. 0 means it is disabled.

sechub.storage.s3.timeout.request.milliseconds

0

S3 client timeout (in milliseconds) for a request. 0 means it is disabled.

sechub.storage.s3.timeout.socket.milliseconds

50000

S3 client timeout (in milliseconds) for reading from a connected socket.

sechub.storage.sharedvolume.upload.dir

undefined

Defines the root path for shared volume uploads - e.g. for sourcecode.zip etc. When using keyword temp as path, this will create a temporary directory (for testing).

Table 19. Scope 'system'
Key Default Description

sechub.monitoring.accepted.cpu.average.max

2.0

Maximum CPU load average accepted by sechub system. Value is calculated by measured system load average divided by available processors. A value above 1.0 usually means that a processor is very heavily loaded.

sechub.monitoring.accepted.memory.usage.max

90.0

Maximum memory usage percentage accepted by sechub system. Can be a value from 50 up to 100 for 100%

sechub.monitoring.cache.time.millis

2000

Time in milliseconds monitoring fetch results are cached before fetching again

Table 20. Scope 'target'
Key Default Description

sechub.target.resolve.strategy.ip

Strategy to decide target types by given IP.
Starts always with strategy-identifer, colon and value(s). Values are comma separated. Currently only 'intranet-ip-pattern' is supported as strategy. Inside this strategy,it is possible to define IPv4 or IPv6 adresses (wildcards are also possible). For example: intranet-ip-pattern:192.168.178.*,2001:db8:85a3:0:0:8a2e:370:*. Other IPs are interpreted as being inside INTERNET. But no matter if strategy is defined or not: loopback addresses are always illegal and so ignored

sechub.target.resolve.strategy.uri

One ore more strategies to decide target types by given URI.
Starts always with strategy-identifer, colon and value(s). Values are comma separated. Currently only 'intranet-hostname-ends-with' and 'intranet-hostname-starts-with' are supported as strategies. For example: intranet-hostname-ends-with:intranet.example.org,intx.example.com. Other hostnames are interpreted as being inside INTERNET. But no matter if strategy is defined or not: loopback addresses are always illegal and so ignored. You can define multiple strategies at same time by using a pipe symbol to separate them. As an example: `intranet-hostname-ends-with:intranet.example.org,intx.example.com

2.2.3. Scheduling definitions

Table 22. Scope 'scan'
Type Definition Description

Fixed

initial delay:${sechub.config.trigger.autoclean.initialdelay:5000} fixed delay:${sechub.config.trigger.autoclean.delay:86400000}

Auto cleanup is triggered by a cron job operation - default is one day to delay after last execution. As initial delay 5000 milliseconds are defined. It can be configured differently. This is useful when you need to startup a cluster. Simply change the initial delay values in to allow the cluster to startup.

Table 23. Scope 'schedule'
Type Definition Description

Fixed

initial delay:${sechub.config.trigger.autoclean.initialdelay:5000} fixed delay:${sechub.config.trigger.autoclean.delay:86400000}

Auto cleanup is triggered by a cron job operation - default is one day to delay after last execution. As initial delay 5000 milliseconds are defined. It can be configured differently. This is useful when you need to startup a cluster. Simply change the initial delay values in to allow the cluster to startup.

Fixed

initial delay:${sechub.config.trigger.nextjob.initialdelay:5000} fixed delay:${sechub.config.trigger.nextjob.delay:10000}

Job scheduling is triggered by a cron job operation - default is 10 seconds to delay after last execution. For initial delay 5000 milliseconds are defined. It can be configured differently. This is useful when you need to startup a cluster. Simply change the initial delay values in to allow the cluster to startup.

2.3. Deployment

2.3.1. Database

SecHub requires a PostgreSQL DB, Version > 10.x

2.3.1.1. Plain server

In this scenario you would configure a database server available from SecHub.

For example: Just install PostgreSQL DB server on same machine as your server.

2.3.1.2. Kubernetes

Here you must provide a PostgreSQL DB server deployment (one POD only), define a network policy, services, endpoints etc. etc.

Be aware to mount only ONE pod - the database is shared by all SecHub server PODs (means this is a shared kernel / bottle neck but necessary)

Think about an automated database backup - no matter which is your choosen installation variant…​

2.3.2. File upload storage

SecHub requires a file system folder where source scan uploads can be transferred to.

In a clustered environment like kubernetes the storage must be accessible by every cluster member!

2.3.2.1. Plain server

In this scenario you would just either reuse SecHub server file system or define a network share available form server.

2.3.2.2. Kubernetes

Here you must provide a PostgreSQL DB server deployment (one POD only), define a network policy, services, endpoints etc.

Be aware to mount only ONE pod - the database is shared by all SecHub server PODs (means this is a shared kernel / bottle neck but necessary)

2.3.3. Server Application

SecHub server is a written in Java and needs at least JDK 17.

You can configure SecHub server by system properties or also by environment variables.

Next blocks describe necessary system properties and their ENV pendants.

2.3.3.1. Mandatory configuration
Next lines will show java launcher properties which MUST be set because there are no defaults defined. You have to define those values when not starting in mock mode! The example her is generated and will always show the current necessary parts.
-Dspring.profiles.active=dev,postgres,real_products
-Dsechub.initialadmin.email=value
-Dsechub.initialadmin.userid=value
-Dsechub.notification.email.administrators=value
-Dsechub.notification.email.from=value
-Dsechub.notification.smtp.hostname=value
-Dsechub.server.baseurl=value
-Dsechub.security.diffiehellman.length=value
Instead of java system properties you can also define environment entries at your launch configuration or your shell and reduce parameter hell:
export SPRING_PROFILES_ACTIVE=dev,postgres,real_products
export SECHUB_INITIALADMIN_EMAIL=value
export SECHUB_INITIALADMIN_USERID=value
export SECHUB_NOTIFICATION_EMAIL_ADMINISTRATORS=value
export SECHUB_NOTIFICATION_EMAIL_FROM=value
export SECHUB_NOTIFICATION_SMTP_HOSTNAME=value
export SECHUB_SERVER_BASEURL=value
export SECHUB_SECURITY_DIFFIEHELLMAN_LENGTH=value

Please don’t forget to have at least one server running with active profile admin_access!

Servers without having this profile activated, will provide only standard API access. Reason for this behavior: Administrators can reduce access to administrative API by IP and port firewall settings.

This is only necessary for production! Development and Integrationtest profiles do automatically include the admin_access profile.

An example for production:
In a Kubernetes environment you could start 5 instances of SecHub without this profile at port 443 and 2 additional ones with admin_access profile enabled on port 8443 (all other settings are same). In your firewall configuration you allow public access to this server by port 443, but access to port 8443 is restricted to some dedicated IPs.

2.3.3.1.1. Storage configuration

In SecHub we need to store job data (e.g. zipped source code).

At least one storage setup must be defined- otherwise SecHub server will not start! You can either define a shared volume (normally a NFS) or a S3 storage.

Look at Storage configuration for configuration details.

2.3.3.2. Plain server

To start the server by executing

java ${systemProperties} -jar sechub-server-x.y.z.jar

Where ${systemProperties} is a place holder for Java system properties or you use environment entries (configuration is explained in common chapter before)

2.3.3.2.1. Logging

SecHub uses per default logging to stdout. So you have to change this behaviour for your server when you want to change log output format, location etc.

2.3.3.3. Docker

The SecHub server can be simply run like this

docker run ghcr.io/mercedes-benz/sechub/sechub-server
2.3.3.4. Kubernetes

Same as before described for plain server, but you should use a copy of the values.yaml and adapt it to your needs.

helm pull oci://ghcr.io/mercedes-benz/sechub/helm-charts/sechub-server
tar zxf sechub-server-*.tgz
cp sechub-server/values.yaml sechub-server.yaml
# edit "sechub-server.yaml" file and adapt settings

# Deploy SecHub server to your Kubernetes:
helm install sechub-server sechub-server/ -f ./sechub-server.yaml

2.4. Mapping

Mapping is used for simple key value configuration, but also for more sophisticated behaviour like done in scan configuration.

The mapping concept can be either used in a global persisted way, or in a dynmaic way like done for parameter mappings in product executor configuration .

2.4.1. REST API for global mapping

A global configuration can be done by REST API. The data is defined in JSON.

2.4.2. JSON structure

Given JSON has following structure:

{
  "entries" : [ {
    "pattern" : "pattern_1",
    "replacement" : "replacement_1",
    "comment" : "comment_1"
  },
  { 
  "pattern" : "pattern_2",
    "replacement" : "replacement_2",
    "comment" : "comment_2"
  },
  //..
  {
    "pattern" : "pattern_n",
    "replacement" : "replacement_n",
    "comment" : "comment_n"
  } ]
}

here an example for a suitable checkmarx mapping (checkmarx.newproject.teamid)

{
  "entries" : [ {
    "pattern" : "testproject_*",
    "replacement" : "1",
    "comment" : "Maps all projects starting with name testproject_ to dedicated checkmarx team ID"
  }, {
    "pattern" : ".*",
    "replacement" : "2",
    "comment" : "Default checkmarx team id for all other projects"
  } ]
}

2.5. Execution profiles

An execution profile can contain multiple executor configurations. The configurations can be shared between multiple profiles.

As an example: a config with name "pds-gosec-1" can be used in profiles "profileA" and also "profileB" at the same time.

When a profile is assigned to a project and the profile is enabled, all of its enabled executor configurations are executed for the project when suitable for code scan type.

To have a scan job running, at least one executor configuration must match - otherwise you will have always a "green" scan result.

2.6. Executor configuration

SecHub uses product executors to call security products by dedicated product adapters. Each used security product has at least one executor configuration.

Inside such a configuration, we can define properties and parameters which are used when it comes to SecHub job execution. The data is evaluated and used by product executors at runtime and no server restart is necessary.

So for example you can easily change a base URL of a product location and it will automatically be used by next job execution.

At the moment NESSUS and NETSPARKER product executors do not use all executor configuration data.

They ignore

  • Base URL

  • Credentials

  • Parameter content

You still have to configure the ignored parts by system environment variables (or system properties) in a global way and you can’t change these settings at runtime.

2.6.1. Data structure

2.6.1.1. Name

Just the name of the executor configuration. Can be changed.

2.6.1.2. Enabled

Only when the executor configuration is enabled, it will be used (of course it has also be added to an enabled profile and this to a project).

2.6.1.3. UUID

Unmodifiaable unique ID of an executor configuration. Cannot be changed.

2.6.1.4. Product identifier

The product identifier for the product executor to use. Examples are:

  • PDS_CODESCAN

  • PDS_WEBSCAN

  • PDS_INFRASCAN

  • PDS_LICENSESCAN

2.6.1.5. Executor version

At the moment all product executors exists only in version 1 and as long as there is no breaking change the exisitng product executor will be extended and the existing version will be kept.

When there are breaking changes - e.g. the communication between SecHub and a new version of the security product becomes completely different, or parameters have a complete other meaning, an additional product executor with another version will be available.

2.6.1.6. Product base URL

Here we define the base URL to the security product including port number.

2.6.1.7. Product credentials

To use a security product, we always need login credentials. These credentials must be defined inside the configuration.

2.6.1.7.1. Environment variable references

To store no real credentials in SecHub database, you can reference SecHub server environment variables instead - just use the pattern env:${variableName}.

SecHub server will store the given pattern in database, but the content of the environment variable will be used at runtime when it comes to authentication.

Example for an environment variable reference:

Let’s assume a have a running PDS server which accepts "exampleToken" as API token for technical user.

You would add

export PDS_CODESCAN1_APITOKEN=exampleToken

at the beginning of your start script for SecHub server.

In your executor configuration you would set the API token field to env:PDS_CODESCAN1_APITOKEN. When a SecHub job has beend started, SecHub server will use exampleToken as API token for communication with this PDS server.

2.6.1.7.2. User

The user name used by SecHub to authenticate at security product.

2.6.1.7.3. Password or API token

The password or API token used by SecHub to authenticate at security product.

It is strongly recommended to use environment variable references environment variable references here instead of plain text.
2.6.1.8. Parameters

Parameters are used at job execution runtime to setup product adapters and to change security product behaviours.

2.6.1.8.1. Mappings

Some product executors do need special mappings - e.g for new project creations. Please look at mapping for more details about the concept and the format.

2.6.1.8.2. Key values

It is also possible to provide just dedicated key value parameters.

2.6.2. Product specific details

2.6.2.1. PDS

For PDS we have a set of predefined configuration parameters (see next table) and the possibility to define custom parameters.

Some of the predefined parameters are generated. In this case the user cannot define them in the executor configuration, but they are listed here for the sake of completeness.

Table 24. PDS executor configuration parameters
Key Description Additional info

sechub.productexecutor.pds.forbidden.targettype.internet

When this key is set to true, then this PDS instance does not scan INTERNET!

  • Optional

sechub.productexecutor.pds.forbidden.targettype.intranet

When this key is set to true, then this PDS instance does not scan INTRANET!

  • Optional

sechub.productexecutor.pds.timetowait.nextcheck.milliseconds

When this is set, the value will be used to wait for next check on PDS server. If not, the default from PDS install set up is used instead.

  • Optional

sechub.productexecutor.pds.timeout.minutes

When this is set, the value will be used to wait before timeout happens when no communication with PDS server is possible. If not, the default from PDS install set up is used instead.

  • Optional

sechub.productexecutor.pds.trustall.certificates

When 'true' then all certificates are accepted. Do not use this in production!

  • Optional

sechub.productexecutor.pds.adapter.resilience.retry.max

Maximum amount of retries to handle resilience. When not defined or smaller than 0 the default will be: 3

  • Optional

sechub.productexecutor.pds.adapter.resilience.retry.wait.milliseconds

Amount of milliseconds the PDS adapter shall wait before doing a next retry to handle resilience. When not defined or smaller than 1 the default will be: 10000

  • Optional

pds.config.productidentifier

Contains the product identifier, so PDS knows which part is to call on it's side.

  • Available as ENV variable PDS_CONFIG_PRODUCTIDENTIFIER inside launcher script.

  • Mandatory

pds.scan.target.type

Contains the target type (depending on scan type) and will be just an additional information for PDS from SecHub.

  • Available as ENV variable PDS_SCAN_TARGET_TYPE inside launcher script.

  • Generated

  • Optional

pds.config.use.sechub.storage

When 'true' the SecHub storage will be reused by the PDS server. In this case SecHub will not upload job data to PDS. But it's crucial to have the same root storage setup on the PDS server side (e.g. same s3 bucket for S3 storage, or same NFS base for shared volumes). When not 'true' or not defined, PDS will use its own storage locations

  • Optional

  • Default is "true"

pds.config.use.sechub.mappings

Contains a comma separated list of mappping ids. Each defined mapping will be fetched from SecHub DB as JSON and sent as job parameter with the mapping id as name to the PDS.

  • Optional

  • Default is "true"

pds.config.sechub.storage.path

This contains the sechub storage location when sechub storage shall be used. So PDS knows location - in combination with sechub job UUID reuse is possible

  • Generated

  • Optional

pds.config.filefilter.includes

This contains a comma separated list of path patterns for file includes. These patterns can contain wildcards. Matching will be done case insensitive! Every file which is matched by one of the patterns will be included - except those which are explicitly excluded. When nothing is defined, then every content is accepted for include.

For example: '*.go,*.html, test1.txt' would include every Go file, every HTML file and files named 'test1.txt'.

  • Optional

pds.config.script.trustall.certificates.enabled

When 'true' the PDS adapter script used by the job will have the information and can use this information when it comes to remote operations.

  • Available as ENV variable PDS_CONFIG_SCRIPT_TRUSTALL_CERTIFICATES_ENABLED inside launcher script.

  • Optional

  • Default is "false"

pds.config.supported.datatypes

Can be SOURCE, BINARY, NONE or a combination as a comma separated list. This data should normally not be defined via a default value of an optional PDS configuration parameter.

  • Optional

pds.config.jobstorage.read.resilience.retries.max

Defines the maximum amount of retries done when a job storage read access is failing

  • Optional

pds.config.jobstorage.read.resilience.retry.wait.seconds

Defines the time to wait in seconds before the next retry is done (when it comes to storage READ problems)

  • Optional

pds.config.product.timeout.minutes

Maximum allowed time in minutes, before a product will time out - this means that the launcher script is automatically canceled by PDS

  • Optional

pds.config.filefilter.excludes

This contains a comma separated list of path patterns for file excludes. These patterns can contain wildcards. Matching will be done case insensitive! When empty, then nothing will be excluded. The exclude operation will be done AFTER the include file filtering.

For example: '*.go,*.html, test1.txt' would exclude every Go file, every HTML file and files named 'test1.txt'.

  • Optional

pds.scan.target.url

This contains the target URL for the current scan (i.e. webscan). Will not be set in all scan types. E.g. for a code scan this environment variable will not be available

  • Available as ENV variable PDS_SCAN_TARGET_URL inside launcher script.

  • Generated

  • Optional

pds.debug.enabled

When 'true', the PDS instance will show up some debug information on scan time. The output level of debugging information differs on PDS solutions/launcher scripts.

  • Available as ENV variable PDS_DEBUG_ENABLED inside launcher script.

  • Optional

  • Default is "false"

pds.scan.configuration

This contains the SecHub configuration as JSON object (but reduced to current scan type, so e.g. a web scan will have no code scan configuration data available

  • Available as ENV variable PDS_SCAN_CONFIGURATION inside launcher script.

  • Generated

  • Optional

pds.config.cancel.event.checkinterval.milliseconds

This is the maximum time the launcher script process will be kept alive after a cancellation event is sent. This gives the launcher script process a chance to recognize the cancel event and do some final cancel parts and exit gracefully.

  • Optional

pds.config.cancel.maximum.waittime.seconds

The time in seconds PDS will check again if the launcher script process is alive or not when the process shall be canceled. When nothing defined, the default value is:0. If the value is 0 the process will be terminated without waiting.

  • Optional

pds.mocking.disabled

When 'true' any PDS adapter call will use real PDS adapter and not a mocked variant.

  • Optional

  • Default is "true"

  • Only for testing

2.6.2.2. Checkmarx
2.6.2.2.1. Mapping teams and presets for new projects

When a user starts a scan and a checkmarx project does not already exist, it will be created.

In some cases, however, it should not be created with the default Checkmarx "preset" but a dedicated one. And when creating many projects we do not want to assign all other presetIds manually to the project (a preset is something like a profile in Checkmarx where scope of scan can be defined at project level).

Also there should be an automated assignment to dedicated teams when the project is newly created.

This can be done by name pattern providers checkmarx.newproject.presetid.mapping and checkmarx.newproject.teamid.mapping as shown in following example:

An example parameter configuration:

Define mapping for key checkmarx.newproject.presetid.mapping

{
        "entries": [
            {
                "pattern": "my-java-project-.*",
                "replacement": "100021", 
                "comment":"java projects"
            },
            {
                "pattern": "a-go-project-.*",
                "replacement": "100031",
                "comment":"go projects"
            },
            {
                "pattern": ".*",
                "replacement": "100001", 
                "comment":"others"
            }
        ]
    }
}

Define mapping for key checkmarx.newproject.teamid.mapping

{
    "entries": [
            {
                "pattern": "my-java-project-.*",
                "replacement": "1", 
                "comment":"team id for java projects"
            },
            {
                "pattern": "a-go-project-.*",
                "replacement": "2", 
                "comment":"team id for go projects"
            },
            {
                "pattern": ".*",
                "replacement": "3", 
                "comment":"team id for other projects"
            }
        ]
}

On lazy project creation time, depending on project name in sechub, after checkmarx project creation the project will automatically be assigned to the pattern specific presetId.

For example:

  • project named in SecHub with my-java-project-marvelous1 will have preset id 100021 and teamId 1.

  • project named in SecHub with a-go-project-super-cli will have preset id 100031 and teamId 2.

  • project named in SecHub with something-else`will have preset id `100001 and teamId 3

First matching part will be used! So ordering is important!

2.6.2.2.2. How to obtain preset id

Unfortunately the preset ID is necessary for REST calls, but not visible at Checkmarx UI.

You can either directly access the DB or inspect the web page by web tools in you browser (e.g. enable network monitoring and change preset id at UI…​)

2.6.2.2.3. How to obtain team id

Unfortunately the team ID is necessary for REST calls, but not visible at Checkmarx UI.

You can either directly access the DB or inspect the web page by web tools in you browser (e.g. enable network monitoring and change team at UI…​)

2.6.3. Examples

As long as there is no dedicated Web UI for administration we use the Developer Admin UI for example screenshots:

For every example you have either to create a new executor configuration or edit an an existing one.

To edit an existing one, select main menu entry "Edit executor configuration" as shown in next figure:

sechub daui config edit executor config menuentry

This will result in a selection dialog.

sechub daui select executor config to edit
2.6.3.1. Checkmarx configuration

At the configuration editor dialog you can change the data structure. Parameters are inside a simple text field. But there exists also a button "Edit parameters".

sechub daui checkmarx executor config example

If you edit directly inside the Parameters text area be aware that only one line per key is allowed.

When you press the "Edit parameters" button, a dedicated parameter editor will appear:

sechub daui checkmarx executor parameter editor mappings example

On last figure the type, the necessarity and a short description of the parameters are shown above the text component. This makes it easier to configure values.

At the mapping tab pane you can edit the JSON data. With "Test mapping" button you can also check if the naming pattern are correct and the expected values are resulting.

For the "normal" key value pairs we got the "key/values" tab pane. Here the content is normally only simple text. For example checkmarx.fullscan.always could contain like "true" or "false" or simply nothing.

sechub daui checkmarx executor parameter editor key values example

After pressing the Apply button the changed data is set inside executor configuration in correct format.

2.6.3.2. PDS code scan configuration

Here we got an example for a configuration with selected product identifier PDS_CODESCAN:

sechub daui pds executor parameter editor key values example

The pds.config.productidentifier which is an mandatory value is marked red because it must be sent to PDS server to identify which product shall be used on the other side.

Optional, but wellknown PDS key value pairs are shown in black - the parameters example.key1 and example.key2 are marked yellow. Reason: Those keys are unknown by SecHub and so normally custom parameters.

2.6.3.3. Sereco configuration

Sereco is the only product which needs no configuration at all, because it is an embedded "product".

It also needs no profile setup or something else - as long as there is no other reporting product available/configured for a SecHub job, an automated fallback will always call Sereco at the end to ensure a report result is created.

But Sereco is the one and only exception!

2.7. Scan configuration

Sometimes it is necessary to provide special scan configuration setup, e.g. when initializing scan operations at server side.

This can be done by a special scan configuration which is defined as JSON.

Please don’t be confused this configuration with SecHub configuration which is always on client side.

The scan configuration feature was established before the runtime configuration by profiles and executor configurations was introduced. It is a global configuration for scanning.

2.7.1. General

2.7.1.1. Name pattern ID providers

Currently only namePatternIdProviders are provided, which contain an id and mappings from name patterns to identifiers. By this very generic approach dedicated adapters can fetch identifiers for specific name setups.

2.7.2. Mapping

Scan configuration can be changed by SecHub mapping - look at mapping for more information.

Just use the provider ID as mapping ID.

3. Security Products

You must only setup those products you have listed inside your profiles. See execution profiles and executor configurations

3.1. PDS

3.1.1. General

The PDS adapters can communicate with the PDS instances which delegates to the underlying security products.

Via PDS every security product, even simple CLI tools, can be easily integrated into SecHub.

Please look into Product delegation server documentation for more information about the PDS in common.

3.1.2. PDS solutions

There are already ready to use PDS implementations available - we call them "PDS solutions".

Every PDS solution does work out of the box and provide the possibility to start in following three flavors:

  • docker (single instance)

  • docker compose (cluster)

  • helm charts (k8s cluster)

The next sub chapters list the current implementations:

3.1.2.1. GoSec
3.1.2.2. Multi

This solution does integrate multiple SAST tools:

3.1.2.3. OWASP ZAP

This solution does integrate the https://www.zaproxy.org/ (web application scanner) - please look at https://github.com/mercedes-benz/sechub/blob/develop/sechub-pds-solutions/owaspzap/

3.1.2.4. PMD

https://pmd.github.io/ stand normally for quality checks, but it does also provide some security check mechanism. The integration can be found at https://github.com/mercedes-benz/sechub/tree/develop/sechub-pds-solutions/pmd

3.2. Checkmarx

3.2.1. What does the adapter do?

  1. All communication is done by REST API

  2. Login

  3. Ensure project exists (reuses existing project or creates new one)

    1. projectname is SecHub project name

    2. teamId Is shared and always CHECKMARX installsetup team id for new projects…​

  4. Upload source code from SecHub upload folder per REST to Checkmarx server

  5. Start scan

    1. When possible incremental scan is used

  6. Fetch report as XML

3.2.1.1. What must be done on Checkmarx UI
  1. At the moment you have create initial a Checkmarx team which will be used for SecHub scans

  2. If users shall have access to Checkmarx UI you must add them to used Checkmarx team (manual)

3.2.1.2. What can be configured for SecHub ?
3.2.1.2.1. Environment

Please look at checkmarx config section.

3.2.1.2.2. Runtime
Standard properties (like base URL, user id etc.) are currently NOT used from existing product executor configurations but only the environment configuration is used at the moment.
Parameter Type Description

checkmarx.fullscan.always

boolean

When 'true' every scan will be done as a full scan and delta scan is not used.

Use this only where a delta scan is not possible/ always rejected by checkmarx. When 'false' or any other value, delta scan feature is used.

If a scan fails because checkmarx has detected too many changes there will be a retry with fullscan. If you have permanent problems with delta scanning for a project you should set this option to 'true' in your checkmarx executor configuration.

3.2.2. Summary

  1. Projects are initially created and reused automatically

  2. Old scans are NOT automatically deleted

  3. Multi tenancy is currently problematic: Same Team ID is always used (will be changed with Issue 58)

Fix team ID will change in future to provide grouping of results in product(for multi tenancy).

3.3. Netsparker

3.3.1. What does the adapter do?

  1. All communication is done by REST API

  2. Login

    1. To differ between intranet and internet scans adapter will use agent name or given agent group. If a group is defined the group will be used.

  3. Check website already defined in Netsparker

    1. Website identifier is defined by pattern (see info box below)

    2. If not defined, create new Netsparker website by given identifier otherwise reuse existing one

  4. Start scan

    1. Create new scan for web page identifier and fetch scan ID

    2. Wait for scan being done

  5. Fetch report as XML

Website identifier is created by url root part and port number.
When no port is defined instead of port number the protocol default will be used.

For example: https://test.example.com/myapp:8080 will be identified by test.example.com_8080, but https://test.example.com/myapp leads to test.example.com_default as identifier.

Using default to identify standard ports for https (443) and http (80) combines results - this can reduce amount of webscan identifiers. Also it handles situation that Netsparker does internally not differ between http and https scans, but differs between ports when not default.

3.3.2. What must be done on Netsparker UI

3.3.2.1. Users

3.3.3. Summary

  1. Websites are initially created and reused automatically

  2. Old scans are NOT automatically deleted

Currently Netsparker adapter will always use ONE team user (admin) to create scans. The current logical structure of Netsparker permissions gives all assigned users access to all scans! Keep this in mind.

3.4. Nessus

3.4.1. What does the adapter do?

  1. All communication is done by REST API

  2. Login by username and password

  3. Fetch Nessus session token by first REST call

  4. Resolve Nessus policy UUID

  5. Start Scan

    1. Add new scan and resolve Nessus scan id.
      As scan name sechub job UUID in cobination with target type (INTRANET, INTERNET) will be used

    2. wait for scan done

  6. Fetch report as XML by doing a Nessus scan export

  7. Logout

3.4.2. What must be done on Nessus UI

  • define the Nessus policy UUID

3.4.3. Summary

  1. At the moment only one Nessus policy UUID is used

  2. Every scan has got its own name which starts with SecHub job UUID

  3. Old scans are NOT automatically deleted

4. Onboarding

Registration process of new users is done by rest API call, for details about URL etc. please refer to REST API documentation described at User self registration

4.1. What must be done when a new user has registered ?

  1. Check user is wellknown and should have access

  2. Check user name is valid for your purpose / company.
    SecHub will automatically check for uniqueness of user name and email address.

  3. Accept signup by REST API (or tool)

  4. If necessary create accounts in your installed security products.

4.2. What must be done when a new project shall be created ?

  1. Create a new project inside SecHub by REST API (or tool)+

    1. At least the project owner must be set

    2. If you do not define any white list URLs there, no web scans or infrastructure scans can be executed!
      Check if requested white list entries are really valid for the project and do not belong to another project or organization.

  2. Assign users to project
    Currently its only possible by administrators to add / remove project members. This will change in future, see https://github.com/mercedes-benz/sechub/issues/60

4.3. What must be done when a user wants to have access to a SecHub project ?

  1. As long as https://github.com/mercedes-benz/sechub/issues/60 is not solved, the project owner must request the assignment to a super administrator. Only with permission of project owner the assignment should be done!