SecHub TechDoc

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

Key

Value

Information

LICENSE

MIT License

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

Documentation version: Server 1.9.0 - Build date: 20240430152944

Target audience for this document are SecHub Developers only!

2. Development Setup

2.1. Preparation

2.1.1. Tool installation

You need

JAVA 17 JDK
Go Lang (min. 1.21.6)
GIT

A Go installation is only necessary for client development. All tools must be accessible from PATH variable.

2.1.2. GIT setup

2.1.2.1. Clone

git clone https://github.com/mercedes-benz/sechub.git

2.1.2.2. GIT Configuration

After Git clone is done, please go into the repository’s root folder and define

2.1.2.2.1. User name and email

Only necessary when not like your global configuration:

git config user.email $yourEmailAddress
git config user.name "$firstName $lastName"

2.1.2.2.2. SecHub wanted setup

git config branch.autosetuprebase always
git config branch.master.rebase true
git config push.default current
git config core.autocrlf input
git config color.ui auto
git config --add remote.origin.fetch +refs/tags/*:refs/tags/*

2.1.3. IDE setup

2.1.3.1. Eclipse

2.1.3.1.1. Import projects

Open a console in SecHub’s repository root folder and type:

./gradlew cleanEclipse eclipse assemble

This will setup all your eclipse settings and you are able to import the now existing projects into a workspace of your choice.

2.1.3.1.2. Create localhost server certificate

This is automatically done by former gradle call, so not necessary here.

2.1.3.2. Others

2.1.3.2.1. Import projects

Import as you would normally do in your IDE.

2.1.3.2.2. Create localhost server certificate

To get the localhost server certificate created, open a console just call ./gradlew ensureLocalhostCertificate

This will generate a self signed server certificate for localhost.

2.1.4. Special developer files

2.1.4.1. Developer property file

Inside ~/.sechub/sechub-developer.properties you can define some special default behaviours

Key Possible values/types Description

Key	Possible values/types	Description
sechub.integrationtest.running	boolean	When `true`, every integration test is run, no matter if system property is set for launch config or not

sechub.integrationtest.running

boolean

When true, every integration test is run, no matter if system property is set for launch config or not

See LocalDeveloperFileSetupSupport.java for details.

2.2. First steps

Here are some first steps to get SecHub running and being able to start developing.

2.2.1. Integration test scenario

With this setup we will start a SecHub server instance ready for executing integration tests. It does use only security product mocks, so we got no long running sessions. We need no running security suite… but of course we have no real products and can not make real scans.

2.2.1.1. Start integration test server

2.2.1.1.1. IDE

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=integrationtest,mocked_products,h2 (1)
-Dsechub.server.debug=true (2)
-Dsechub.storage.sharedvolume.upload.dir=temp (3)

1	Starts server with localhost certificate uses mocked products uses h2 database always mocked notification debug logging activated provides special behaviour for integration tests (e.g. get mails, easy to generate test data etc.)
2	When debug flag is set, rest call response error messages do also contains stacktraces.
3	We use `temp` which is a marker to create a temp folder for shared volume (necessary for source upload)

2.2.1.1.2. Console

./gradlew startIntegrationTestServer

2.2.1.2. Start integration tests

Integration tests do completely execute commands like done on real system - except there is no real communication with security products but only with mocked variants.

Integration tests do need always a running integration test server instance.

2.2.1.2.1. IDE

When you have running integration test server instance, just execute JUnit at complete project sechub-integrationtest with

-Dsechub.integrationtest.running=true

Some integration tests are long running. These tests are only run when you set

-Dsechub.integrationtest.longrunning=true

So you can easily switch or enable all by enabling dedicated system property.

2.2.1.2.2. Console

Next line starts integration test server, execute tests and automatically stops server after done or failed.

./gradlew integrationtest

The gradle task integrationtest does not depend on build. This was explicit not done, because build server can create server, then client and then start integration tests (different stages …) without building again.

But be aware:

If you have executed a clean task before, you are forced to call gradlew build buildGo integrationtest to get all things working again.

2.2.1.3. Stop integration test server

To stop your running server:

2.2.1.3.1. Console

./gradlew stopIntegrationTestServer

2.3. Developer administration UI

There exists a very simple user interface for developers to test out the behaviour of the SecHub server. There will be all functions of server available, but in a very reduced way.

The developer administration UI is only a tool for developers and should be handled with care.
It’s an extreme simple client for administrative parts. For real administration a frontend for admins will be developed in future! It’s not purposed to be in a deployment, but only for development.

2.3.1. General launch setup

To start simple swing application DeveloperAdministrationUI create a new launch configuration with following arguments:

class: com.mercedesbenz.sechub.developertools.admin.ui.DeveloperAdministrationUI

-Dsechub.developertools.admin.server=${yourServerAddress}

Environment entries:

SECHUB_ADMIN_USERID=${yourAdminAccount}
SECHUB_ADMIN_APITOKEN=${yourAdminAPIToken}
SECHUB_ADMIN_ENVIRONMENT=PROD|INT|Specific[TEST](1)

1 Optional: Your environment. This will be shown inside Application as Title. Also the variable content will provide some color effects: PROD will have red, INT yellow and any content having TEST (case insensitive) inside will have cyan credential page inside. When not set UNKNOWN will be used in title and no special color is used for credential panel.

2.3.2. Integration test variant

To start simple swing application DeveloperAdministrationUI create a new launch configuration with following arguments:

class: com.mercedesbenz.sechub.developertools.admin.ui.DeveloperAdministrationUI

-Dsechub.developertools.admin.server=localhost (1)
-Dsechub.developertools.admin.serverport=8443(2)
-Dsechub.developertools.admin.integrationtestserver=true (3)
-Dsechub.developertools.admin.serverprotocol=https(4)

Environment entries:

SECHUB_ADMIN_USERID=int-test_superadmin(5)
SECHUB_ADMIN_APITOKEN=int-test_superadmin-pwd(5)

We use environment variables for credentials because otherwise everybody able to list running processes can see the user id and API token…

1	Please replace this with your server location. For development `localhost`
2	Optional: This is the server port - default is `443`. For development servers at your local machine you should normally set to `8443`.
3	Optional: Enable special integration test actions - e.g. create test data, start jobs etc.
4	Optional: Per default `https` will be used. If you have started (not recommended) SecHub with `SSL` disabled and spring security disabled
5	These are the credentials used for administrative access. For integration tests we got fix credentials - so never use in production!

2.4. Branching model

Overview of branch types:

Name-Pattern Parent branch Details

Name-Pattern	Parent branch	Details
`master`	none	This is the leading branch. Versions, Tags etc. are done here! Direct commits to master have to be avoided. Version build is done here.
`hotfix`	master	Hotfix branch. This is the branch we use for hot fixes. So we ensure changes from `develop` are not in a hotfix. After a hotfix has been merged to master the changes must be applied to `develop` branch as well.
`develop`	master	Development branch. This branch will be part of the next release. Do not commit into this branch. Instead create a dedicated feature-branch.
`feature-${issue}`	develop	For each feature we create a `feature-1234-xyz` branch. It will be merged into the `develop` branch when finished. A git push to remote will trigger a full CI/CD build for SecHub client, server and PDS but not for SecHub github actions.
`gha_feature-${issue}`	develop	For each github action feature we create a `gha_feature-1234-xyz` branch. It will be merged into the `develop` branch when finished. A git push to remote will trigger CI/CD build for SecHub github actions, but NOT a full CI/CD build for SecHub client, server and PDS.

master

none

This is the leading branch. Versions, Tags etc. are done here! Direct commits to master have to be avoided. Version build is done here.

hotfix

master

Hotfix branch. This is the branch we use for hot fixes. So we ensure changes from develop are not in a hotfix.

After a hotfix has been merged to master the changes must be applied to develop branch as well.

develop

master

Development branch. This branch will be part of the next release. Do not commit into this branch. Instead create a dedicated feature-branch.

feature-${issue}

develop

For each feature we create a feature-1234-xyz branch. It will be merged into the develop branch when finished. A git push to remote will trigger a full CI/CD build for SecHub client, server and PDS but not for SecHub github actions.

gha_feature-${issue}

develop

For each github action feature we create a gha_feature-1234-xyz branch. It will be merged into the develop branch when finished. A git push to remote will trigger CI/CD build for SecHub github actions, but NOT a full CI/CD build for SecHub client, server and PDS.

3. SecHub infrastructure setup

3.1. Spring boot

3.1.1. SecHub Spring Profiles

SecHub provides multiple Spring profiles

3.1.1.1. Server

3.1.1.1.1. Overview

Figure 1. Spring profiles and their explicit/implicit included parts

3.1.1.1.2. PROD

As name offers, this profile is designed for production.

For production the profile admin_access is NOT included automatically for security reasons. You should provide an additional server instance where only administrators have network access - only activate the profile on this machine. So you prevent illegal administrative access attempts.

Figure 2. Spring profile prod and its explicit/implicit included parts

3.1.1.1.3. DEV

Figure 3. Spring profile dev and its explicit/implicit included parts

For development this profile must be combinated with others to get server starting - but its extreme flexible and has only a dependency to localserver

3.1.1.1.4. Integration-Test

Figure 4. Spring profile integrationtest and its explicit/implicit included parts

SecHub itself

We use integrationtest profile for server integration tests. You must add some additional profiles. We use h2 and mocked_products for unit testing of sechub server itself.

Test your security tool suite installation

You can use this profile also for testing your security product suite in combination with sechub server - e.g. when you have done an update at your product suite and you are not sure if its compatible or the products have bugs.

But (at least currently) you have to write your own tests then. Following could be done:

Write some simple bash scripts which are using SecHub client
Use sechub-integrationtest project as dependency and write some junit tests using TestAPI.

if you want to test your installed environment is working you can also use real_products.

We got dedicated profile constants.

For adapters the constants can be found at AdapterProfiles, for all other in Profiles (shared kernel).

3.1.2. Database configuration

3.1.2.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...

3.1.3. 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:

The system properties described here are automatically generated into this document by build server when developers are using spring annotation @Value in conjunction with the SecHub annotation @MustBeDocumented annotation inside code!

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.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.
sechub.report.sensitivedata.max.nonobfuscated.characters	0	Define the amount of visible characters which are NOT obfuscated.

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 triesIf 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.adapter.checkmarx.resilience.badrequest.retry.max	3	Maximum amount of possible retries for situations 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.networkerror.retry.max	100	Maximum amount of possible retries for situations when a network error happened on communication to Checkmarx server
sechub.adapter.checkmarx.resilience.networkerror.retry.wait	5000	Time to wait until retry is done when a network server happened on communication to Checkmarx server
sechub.adapter.checkmarx.resilience.servererror.retry.max	1	Maximum amount of possible retries for situations 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.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

3.1.4. Scheduling definitions

The schedule setup described here is generated into this document by build server when developers are using spring annotation @Scheduled in conjunction with the sechub annotation @MustBeDocumented annotation inside code!

Table 21. Scope 'administration'
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 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.

3.1.5. Configuration properties for mocked adapters

The system properties described here are automatically generated into this document by build server when developers are using spring annotation @Value inside instances implementing MockedAdapter. If you want details about the mock behavior you have to read the comments inside the java class being named in description column.

Table 24. Scope 'abstract'
Key	Default	Description
sechub.adapter.mock.sanitycheck.enabled	false	See AbstractMockedAdapter.java

Table 25. Scope 'mocked'
Key	Default	Description
sechub.adapter.checkmarx.clientsecret	014DF517-39D1-4453-B7B3-9930C563627C	See MockedCheckmarxAdapter.java
sechub.adapter.mock.setup.filepath	./../sechub-other/mockdata/mockdata_setup.json	See MockedAdapterSetupService.java

3.2. Local development

This section describes the start on local machine (development/presentation).

Only SecHub itself is described. The products must be either running and well configured, or profile mocked_products must be active.

See product infrastructure sections for details.

3.2.1. Java launch configuration setup

Because it takes too much time - even when security products are configured with test profiles (for testing persistence, transaction rollback etc.) a mocked_products profile was introduced which can be used. See Spring Profiles.

It does use normal product executors but injects mocked adapters (e.g. MockedNessusAdapter, MockedNetsparkerAdapter, ..) which do not really communicate with the real security products but return instead preconfigured values (which where recorded from real communications).

Startup is done by using active spring profile mocked_products. Some mocks have special options to change their behaviour at runtime.

Please refer to Mock options for details.

3.2.1.1. Launch in demo mode

Here an example for calling in demomode:

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=demomode

3.2.1.2. Launch in DEV mode

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=dev,h2,real_products (1)
-Dsechub.server.debug=true (2)
...
-Dsechub.adapter.name.something.specific=${necessaryData} (3)
...
-Dsechub.storage.sharedvolume.upload.dir=temp (4)
-Dsechub.initialadmin.userid=sechubadm (5)
-Dsechub.initialadmin.email=sechubadm@example.org(5)
-Dsechub.initialadmin.apitoken=pseudo-token-development-only(5)

1	Enables debug logging, localserver certificates, uses real products and starts server with h2 database. Instead of `h2` profile you could also use profile `postgres` when you have a running postgres instance available+ Also you could use `mocked_products` profile instead of `real_products` and you will not have to define the adapter specifications.
2	When debug flag is set, rest call reponse error messages do also contains stacktraces.
3	This is just an example for a adapter specific setting. Please look into system property definitions and look for adapter parts.
4	We use `temp` which is a marker to create a temp folder for shared volume (necessary for source upload)
5	(Optional) If nothing is defined per default user with id: `sechubadm`, mail address `sechubadm@example.org` and API token `pseudo-token-development-only` will be created (see `InitialAdminInitializer.java`). This is for developer convenience to reuse existing launch configurations and have not always generated new initial apitokens, like done for profile `prod`. Developers are able to define their own to fix security token for started develop servers. If so done, the started developer admin UI must use this inside its launch configuration…

Your server will not start if you forget any adapter key! TIP: (see InitialAdminInitializer.java).

3.2.1.3. Launch in INTEGRATION TEST mode

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=integrationtest,mocked_products,h2 (1)
-Dsechub.server.debug=true (2)
-Dsechub.storage.sharedvolume.upload.dir=temp (3)

1	Starts server with localhost certificate uses mocked products uses h2 database always mocked notification debug logging activated provides special behaviour for integration tests (e.g. get mails, easy to generate test data etc.)
2	When debug flag is set, rest call response error messages do also contains stacktraces.
3	We use `temp` which is a marker to create a temp folder for shared volume (necessary for source upload)

3.2.1.4. Launch in PROD mode

To run a local server like in production please refer How to start localserver like in production

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=prod (1)
...
-Dsechub.adapter.name.something.specific=${necessaryData} (2)
...
-Dsechub.storage.sharedvolume.upload.dir=/srv/storage/persistent-volume1 (3)
-Dsechub.initialadmin.userid=real-superadmin(4)
-Dsechub.initialadmin.email=real-superadmin@example.org(4)
-Dserver.ssl.key-store=path/to/keystore.p12 (5)
-Dserver.ssl.key-store-type=PKCS12 (5)
-Dserver.ssl.key-alias=yourKeyAlias (5)
-Dserver.ssl.key-store-password=yourKeyStorePassword (5)
-Dsechub.notification.smtp.hostname=intranet.example.org (6)
-Dsechub.notification.smtp.port=50(6)
-Dsechub.notification.smtp.config=mail.smtp.auth=false(6)

1	Starts server with production certificate uses real products uses always postgres database real notification
2	This is just an example for a adapter specific setting. Please look into system property definitions and look for adapter parts.
3	Define here the absolute path used for shared volume storage (necessary for source upload)
4	When there is no existing admin inside SecHub database on startup, the given user credentials will be automatically created. Look at the log output to get the initial, generated API token for admin. Be aware that you must regenerate a new api token for this user, or delete the initial admin account after creating another admin, because credentials are inside logs…
5	This is PROD environment SSL configuration. The example shows setup for p12 certificate storage - see spring boot documentation for exact syntax.
6	Setup for smtp server for mail sending. Port and config are optional. See system property definitions for details.

Your server will not start if you forget an adapter key ! (this will change in future when SecHub becomes more modular)

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.

3.3. Security product integrations

3.3.1. PDS solutions

SecHub provides multiple security products via the PDS (product delegation server) containerized and also K8s ready (helm charts). These solutions are always cluster ready and work "out of the box".

Please visit https://github.com/mercedes-benz/sechub/tree/develop/sechub-pds-solutions for details and a complete list of supported products.

3.3.2. Sereco

Sereco is not a product to buy but a own developed sechub report collector.

Why an own report collector? We formerly did try to use an commercial tool, but we were stuck with many problems, e.g.

crucial problems with installation
no clustering
missing REST API for imports
not supporting some product results
… more…

3.3.2.1. Install

The software comes currently up with SecHub server installation. So nothing more is to do.

Scaling etc. is done with SecHub scaling.

3.3.2.1.1. Future

Currently Sereco is an embedded component of SecHub. Maybe there comes a time where Sereco will become a seperate server component which will be deployed standalone. If so there are some changes to do (e.g. creating a rest API) etc. But as long as there is no need for a separate installation it makes no sense to change this.

3.3.3. Checkmarx

Currently we provide Checkmarx as direct product inside SecHub and also as a PDS solution. The aim is to provide Checkmarx only as pds} solution in future. So the direct product integration will vanish.

Static code analyzer see http://www.checkmarx.com/

3.3.4. Netsparker

Netsparker support inside SecHub is deprecated and will vanish. As a replacement we have: https://github.com/mercedes-benz/sechub/tree/develop/sechub-pds-solutions/owaspzap

Netsparker is a web scanner.

see https://www.netsparker.com

3.3.5. Nessus

Nessus support inside SecHub is deprecated and will vanish when there is another infrastructure scan product integration available as an replacement.

see https://www.tenable.com

3.4. Docker-Compose

Change into the product’s folder and issue:

docker-compose up

Please also see the README file in the respective folder.

3.5. Kubernetes

We provide container images and Helm charts: https://github.com/mercedes-benz/sechub/packages

4. Test / Use real products

4.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!

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

4.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.

4.2. Start server in DEV mode

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=dev,h2,real_products (1)
-Dsechub.server.debug=true (2)
...
-Dsechub.adapter.name.something.specific=${necessaryData} (3)
...
-Dsechub.storage.sharedvolume.upload.dir=temp (4)
-Dsechub.initialadmin.userid=sechubadm (5)
-Dsechub.initialadmin.email=sechubadm@example.org(5)
-Dsechub.initialadmin.apitoken=pseudo-token-development-only(5)

1	Enables debug logging, localserver certificates, uses real products and starts server with h2 database. Instead of `h2` profile you could also use profile `postgres` when you have a running postgres instance available+ Also you could use `mocked_products` profile instead of `real_products` and you will not have to define the adapter specifications.
2	When debug flag is set, rest call reponse error messages do also contains stacktraces.
3	This is just an example for a adapter specific setting. Please look into system property definitions and look for adapter parts.
4	We use `temp` which is a marker to create a temp folder for shared volume (necessary for source upload)
5	(Optional) If nothing is defined per default user with id: `sechubadm`, mail address `sechubadm@example.org` and API token `pseudo-token-development-only` will be created (see `InitialAdminInitializer.java`). This is for developer convenience to reuse existing launch configurations and have not always generated new initial apitokens, like done for profile `prod`. Developers are able to define their own to fix security token for started develop servers. If so done, the started developer admin UI must use this inside its launch configuration…

Your server will not start if you forget any adapter key! TIP: (see InitialAdminInitializer.java).

Please refer also Howto integrate new products

4.3. Start server in PROD mode

To start spring boot application SecHubServerApplication create a new launch configuration with following arguments:

-Dspring.profiles.active=prod (1)
...
-Dsechub.adapter.name.something.specific=${necessaryData} (2)
...
-Dsechub.storage.sharedvolume.upload.dir=/srv/storage/persistent-volume1 (3)
-Dsechub.initialadmin.userid=real-superadmin(4)
-Dsechub.initialadmin.email=real-superadmin@example.org(4)
-Dserver.ssl.key-store=path/to/keystore.p12 (5)
-Dserver.ssl.key-store-type=PKCS12 (5)
-Dserver.ssl.key-alias=yourKeyAlias (5)
-Dserver.ssl.key-store-password=yourKeyStorePassword (5)
-Dsechub.notification.smtp.hostname=intranet.example.org (6)
-Dsechub.notification.smtp.port=50(6)
-Dsechub.notification.smtp.config=mail.smtp.auth=false(6)

1	Starts server with production certificate uses real products uses always postgres database real notification
2	This is just an example for a adapter specific setting. Please look into system property definitions and look for adapter parts.
3	Define here the absolute path used for shared volume storage (necessary for source upload)
4	When there is no existing admin inside SecHub database on startup, the given user credentials will be automatically created. Look at the log output to get the initial, generated API token for admin. Be aware that you must regenerate a new api token for this user, or delete the initial admin account after creating another admin, because credentials are inside logs…
5	This is PROD environment SSL configuration. The example shows setup for p12 certificate storage - see spring boot documentation for exact syntax.
6	Setup for smtp server for mail sending. Port and config are optional. See system property definitions for details.

Your server will not start if you forget an adapter key ! (this will change in future when SecHub becomes more modular)

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

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

5. Special setup

5.1. Terminate SSL and use HTTP only

Per default SecHub will always use HTTPS for communication.

Its not recommended, but if somebody wants to use SecHub with HTTP only (e.g. when running behind a SSL proxy) this can be done in this way:

Start your server as described before but add following additional system properties:

-Dserver.ssl.enabled=false
-Dsecurity.require-ssl=false

This will disable ssl encryption and also Spring security which requires ssl.

If you want to administrate this by developer admin ui, you should also switch to the HTTP protocol as described in section developer admin UI setup

6. Security in development

We enable security even in early stage of development! There is no test, no integration test or anything else which would use http only!

6.1. CLI client

There are some options for CLI client which were not supposed to be used in production. So instead of exposing such options by help we use those by explicit ENV entries

ENV-NAME Value Description

SECHUB_DEBUG

"true"

Activates debug logging

SECHUB_DEBUG_HTTP

"true"

Shows HTTP request+response contents including headers

SECHUB_TRUSTALL

"true"

Trust all certificates (only for development). The SecHub client shows a warning when trustall option is enabled

6.2. Server

6.2.1. Spring Boot Security

Spring boot security is always turned on, no matter if development or in production.

6.2.2. Certificates

For development gradle task ensureLocalhostCertificate in sechub-server will automatically generate a localhost server certificate. For details look into task and called bash script.

7. Coding conventions

7.1. Commit messages

We always commit with an issue id inside the headline message means e.g. on command line:

commit -m "Some short summary #${issueNr}"

When having details we always add an empty new line after summary and list details, maybe using "-" at the beginning to have a pretty output in GitHub

7.2. Database

Currently, we use H2 and PostgreSQL in parallel (dev/testing + production).
Please make sure that the SQL statements work with both of them.

7.2.1. Naming in DB

We are using PostgreSQL which does automatically use lower_case names
Numbering starts at 01; maximum is 99
Naming scheme for constraints: c<number>_<table name>_<constraint title>
Example: c01_adm_user_emailaddress
Naming scheme for indices: i<number>_<table name>_<index title>
Example: i01_statistic_job_run_data_filter

7.2.2. Naming in JPA

We are using upper cased names

7.3. YAML

Currently we still have a lot of unconventional YAML files. But there is a GitHub issue to adopt them.

If you are writing new YAML files or adding new content to existing files, please follow always the instructions below.

7.3.1. General

YAML files have the file ending .yaml or .yml
(but .yaml should be preferred when possible)
Define SPDX header with MIT license as first line comment
Use always same indention inside a YAML document
(2 spaces should be preferred)
Define strings with single apostrophes or double apostrophes
(to make it clear that the value is a string)
If possible, define integers, long numbers etc. as numbers
Prefer hierarchical key structure to long key variants
Use comments to explain details (when really necessary)
Use one space between key and value definitions (e.g. key-alias: 'tomcat')

Example

# SPDX-License-Identifier: MIT

# This configuration setup is only for local development and needs
# a generated certificate which is never shared. Because of this
# it is valid to define the credentials inside this file.

server:
  ssl:
    keyStoreType: 'PKCS12'
    # we use a keystore location which is never tracked by git.
    # see dev-create_localhost_certificate.sh and dev-ensure_localhost_certificate.sh
    key-store: 'classpath:certificates-untracked/generated-dev-localhost-keystore.p12'
    key-store-password: '123456'
    key-alias: 'tomcat'
  port: 8444

pds:
  server:
    baseurl: "https://localhost:${server.port}"
  config:
    trigger:
      nextjob:
        initialdelay: 100
        delay: 500

7.3.2. Templates

When defining YAML templates - e.g. for HELM charts

a template statement (e.g. - if or - end) shall start at the first column without indention
nested template statements shall be indented (see example below)
place inserted values indented like normal YAML. (Use | trim if appropriate)

Example

# SPDX-License-Identifier: MIT

{{- if .Values.networkPolicy.enabled }}
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: {{ .Chart.Name }}-policy
spec:
  podSelector:
    matchLabels:
      name: {{ .Chart.Name }}

  {{- if .Values.networkPolicy.ingress }}
  ingress:
    {{ .Values.networkPolicy.ingress | toYaml | indent 4 | trim }}
  {{- end }}

{{- end }}

7.4. Java

7.4.1. Classes

Defined class names

Rest controller will be called ${name}RestController.java
A service is something that will be called by controllers and will be named ${name}Service.java
A factory creating a target will be called ${target}Factory.java
Something implementing an interface will be called ${nameWithAtLeastInterfacePartAtEnd}Impl.java

7.4.1.1. Subclassing/ Inheritance

Normally sub classes shall add their custom part in front of the name as a prefix:

E.g. Interface JobRepository extends Repository

7.4.1.2. Adding additional parts without inheritance

An exception are Custom parts

E.g. Interface JobRepositoryCustom is a special addon to JobRepository without inheritance

7.5. Logging

7.5.1. General

We try to avoid massive logging but we want to log relevant parts!

7.5.2. Audit Logging

We use a service from shared kernel: AuditLogService

7.5.3. Security Logging

We use a service from shared kernel: SecurityLogService

7.5.4. Functional Logging

We use a dedicated static log field for functional logging. Normal logging contains INFO level. Problems which are just annoying will come up to WARN level. Bigger problems are logged in level ERROR.

Technology used is slf4j. We always use logging with parameters - to avoid log injections (should be handled by logging framework automatically) and also to speed up.

For example:

LOG.info("This is user:{} which is from department:{}",userId,department);

7.5.5. Debug Logging

As described in functional logging, but with log level DEBUG.

7.6. Services

We try to create small spring services, in most cases a service with annotation @Service should have only one public method

So pretty simple and easy to maintain.

The name should provide information what the service does and has to end with Service.

Some examples:

MailService
CreateUserService
InformAdminsThatSchedulerJobProcessingHasBeenDisabledService

7.6.1. Special service variants

7.6.1.1. Transaction services

Sometimes it is necessary to divide transactions. E.g. When a service triggers a message into event bus and we need to ensure that data is stored in transaction before the message has been sent.

In this case we insist service ends with TransactionService. For an example look into ProjectTransactionService.

Only add the special transactional parts to the "transactional" service and put all other parts inside "normal" services!

7.7. RestController

Rest controller should not do any business logic by themselves, but delegate only to a dedicated service which contains the logic and does the execution.

7.8. Code2Doc

7.8.1. Spring values

All spring @Value annotations which are necessary for documentation (except adapters. They have no access to SecHub internal parts and are pretty dumb) have to be tagged with @MustBeDocumented annotation. See documentation in code

7.8.2. Messaging

The messaging flow must be documented by annotations as well. There are diagramms automatically generated. See documentation messaging overview for further information.

7.8.3. Use cases

The usecases and their steps have to be documented inside code by using a dedicated annotation which itself is tagged with an @UseCaseDefinition annotation. See existing examples in SecHub code.

Tag relevant entrypoints as dedicated usecase step so other developers can easily find them by their IDE (in eclipse for example you can use CTRL + g to find all references of the selected usecase annotation class

The UseCaseModelAsciiDocGenerator will automatically generate asciidoc file gen_usecases.adoc which will contain all the data from the code and linked adoc files. Also all REST API documentation for usecases having a @UseCaseRestDoc association will be automatically generated.

7.8.4. Tests

In genereal unit tests which are testing a dedicated class MUST have same package as tested classes. So it’s easier to find and also possible to use package private fields for mocking etc.

7.8.4.1. Unit tests

7.8.4.1.1. Fields

We prefer fields to local variables, fields have to be rebuild by an @Before method.

7.8.4.1.2. Junit versions

Our integration tests and most of the "normal" existing unit tests do currently use Junit4 as testframework and not Junit5. Because having some special Junit4 Rules for integration testing, those tests will be still written in Junit 4, but for new "normal" unit tests you should prefer to use Junit5.

It is planned to migrate existing tests to Junit5 in future, because of some benefits. But unfortunately some method signatures have changed (e.g. "Assert.assertEquals(…) - especially for the message string) so this will take some time.

7.8.4.1.3. Maintainable tests

Structure For a better maintenance and reading of tests, we insist on comments dividing a

prepare
setup of mocks, creation of objects etc.
check preconditions (optional)
if necessary check that precondition is fulfilled before test is started
execute
Execute the part / method which shall be tested
test

Except when test code is just a one liner this would be ridiculous..

Naming and creation of fields

We do

use a before method to create the instance to test, so "fresh" on every test.
setup mocks general behaviour in before method, special parts inside test methods
the part to test shall be named like ${name}toTest - e.g. analyzerToTest
create mocks inside before method - so no side effects
provide mocks to services by package private methods (easy to inject + test)
use simple names for normal mockito mocks, use mocked${name} inside MockMVC tests where we have injected spring mockito objects.
test methods do normally not start with test because with Junit4 this become absolete and we try to avoid duplication (it’s clear this is a test method when @Test annotation is at method…)

Just refer to existing tests when you start a new one.

Test structure example1

@Rule
public void ExpectedException expected = ExpectedException.none();

@Before
public void before(){
    /* mocks */
    validator = mock(SimpleUIserIdValidator.class);
    mailService  = mock(SimpleMailService.class);

    /* setup */
    serviceToTest = new MyServiceToTest();
    serviceToTest.valdiator = validator;
    serviceToTest.mailService = mailService;

}

@Test
public void mailservice_is_called(){

  /* execute */
  boolean mailSent = serviceToTest.informUser("user1");

  /* test */
  verify(mailService).sendMail("user1");
  assertTrue(mailSent);

}

@Test
public void inform_user_calls_validator_and_throws_validator_exception(){

  /* test */
  expected.expect(IllegalArgumentException.class);
  expected.expectMessage("wrong user");

  /* prepare */
  doThrow(new IllegalArgumentException("wrong user")).when(validator.validate(eq("user1"));

  /* execute */
  serviceToTest.informUser("user1");


}

When a precondition check is really necessary we add also /* check preconditions */ segment:

Test structure example2

public void testMe(){
  /* prepare */
  .....
  /* check preconditions */
  ...
  /* execute */
  ...
  /* test */
  ...

}

7.8.4.1.4. Naming of mocks and test targets

Creating a mock field for e.g. a service UserService will be named as userService. We do NOT add something like a mock post or prefix!
The test target field - e.g. MailService will be called something like ….ToTest. For example serviceToTest

7.8.4.1.5. Naming of unit tests

"Normal" Junit tests will simply called ${nameOfClassToTest}Test.java They have no dependency to spring

7.8.4.1.6. Using json in unit tests versus production code

org.json.JSONxxyz will make problems because test implementation is using a lightweight variant with other api.

There were some obscure problems with this situation. So inside the adapter framework the context has got a dedicated json support which is using only jackson parts and has a fluent api.

Use only those for communication. It also has an automated support for deep tracing with product identification

7.8.4.2. Unit tests (with spring context)

Junit needing a running spring boot container will be called ${nameOfClassToTest}SpringBootTest.java They use @SpringBootTest inside and have access to dependency injection etc.

Prefer normal junit tests to spring boot tests, as they are much faster and often sufficient.

7.8.4.3. Mocked RestController/MVC Tests (with spring context)

Those tests will also be called ${name}MockTest.java - will e.g. use use Spring annotation @WebMvcTest

7.8.4.4. WireMock tests

When we have to use wire mock - e.g. to mock up product servers, we call them ${name}WireMockTest.java

7.8.4.5. DB integration tests

Those tests will be called ${name}DBTest.java - and will use Spring annotation @DataJpaTest

For an example look into JobRepositoryDBTest

7.8.4.6. Integration tests

In project sechub-integrationtest full integration tests are settled. The project needs a running server in profile integrationtest. For more details about those tests read the README.md file inside projects root folder.

7.8.4.6.1. Integration tests using RestAPI

These tests will be called ${name}Scenario${n}IntTest.java

7.8.4.6.2. Integration tests using SecHubClient

Some integration tests do need a build SecHub client and execute the client. These tests will be called ${name}Scenario${n}SecHubClientIntTest.java

If these tests are failing, please check you have called gradlew buildGo before, otherwise no SecHub client is available for testing…

7.8.4.6.3. Integration tests generating event trace information

We wanted to have an overview about events happening when a usecase is executed and do this by special integration tests where event tracing is enabled. At the end of the test we write JSON files containing event trace information .

We use ${name}EventTraceScenario${n}IntTest.java as naming convention for those tests. See also Usecase event overview for more information.

7.8.4.7. RestDOC tests

In project sechub-doc there are RESTDOC tests settled. Those tests are annotated with UseCaseRestDoc and associated with dedicated UseCase. The tests will automatically create REST api documentation by using Spring REST DOC.

(See also REST Doc tooling.)

The tests MUST be settled here because gradle support classpath runtime information only at current project, so to prevent heavy changeds on build logic, we simply setup those tests inside sechub-doc project itself.

As a side effect it is very much easier for developers to see what parts are rest doc tested at one glance.

7.8.4.7.1. What is the difference between a MockTest and a RestDocTest?

RestDoc tests are designed to check fields, params and results described in documentations are really as is. There is no logic testing inside those tests. They are more or less just for documentation. On the other hand the MockTest pendants are only for logic testing, so also destructive variants and more technical parts are tested here.

7.8.4.7.2. How can I ensure that I do not forget to describe necessary REST API parts?

Every call to REST API must be described as a part for use cases . So there is a usecase annotation used at the restcontroller method which should have a method with an @Step result. At the @Step annotation there is a field needsRestDoc which is per default set to false. For steps doing rest operations and needs to be documented, just set needsRestDoc to true. When you have done this you cannot forget to document, because there is an automated test which fail when you got not RestDoc tests annotated with @UseCaseRestDoc for the use case… It will not break the build, but produce a failing test. There is also an opposite check that you got no @UseCaseRestDoc tests without corrsponding set of steps having needsRestDoc enabled.

You can also find easily restDoc relevant parts by search caller hierarchy of needsRestDoc inside your code. So you get a list of all controller methods having documented API…

7.8.4.7.3. Naming

We use ${restControllerClassName}RestDocTest.java as name pattern to find RestDoc tests easier.

restControllerClassname is just the java class name of the controller were the rest call is made (normally the @Step annotation must have there the needRestAPI='true' setup )

Having always the Controllers and also the necessary @MockBean annotations as spring test dependency this will reduce the boilerplate code to one location…

7.8.4.8. System tests

System tests are tests which test the entire application.

7.8.4.8.1. Naming

The name pattern ${nameOfClassToTest}SystemTest.java is used to find system tests.

7.9. Updates

7.9.1. Updating Spring Boot version

7.9.1.1. Update build.gradle

As first we update the spring boot version inside ${rootFolder}/build.gradle.

As an example we upgrade from version 3.2.2 to 3.2.4:

The existing code in ${rootFolder}/build.gradle

id 'org.springframework.boot' version '3.2.2' apply false

will be replaced by

id 'org.springframework.boot' version '3.2.4' apply false

7.9.1.2. Generate spring_boot_dependagen.gradle

We have some projects which do not have any Spring dependencies (e.g. sechub-commons-core). But these projects are used in different SecHub Spring boot applications as dependencies and also often use the same libraries which are used in Spring as well.

Here we could have version conflicts and it is pretty hard to handle this manually.

This is the reason why we use https://github.com/de-jcup/dependagen to create the file spring_boot_dependagen.gradle.

7.9.1.2.1. Howto use DependaGen

If not already done, clone the dependagen repository loca and generate IDE parts by gradle

For example:

git clone https://github.com/de-jcup/dependagen.git
cd dependagen
./gradlew eclipse

After this you can import the dependagen project into your Eclipse IDE and it is ready to use.

Change the spring boot template to wanted version

vim ./dependagen/gradle-templates/spring-boot/template_build.gradle

Change the spring boot version (and if necessary also the version for spring dependency management plugin)

// ...
plugins {
        id 'org.springframework.boot' version '3.2.4'
        id 'io.spring.dependency-management' version '1.1.4'
        id 'org.asciidoctor.convert' version '1.5.8'
        id 'java'
}
// ...

Generate files

Execute DependaGenApplication with generate as argument.

Copy the generated output/ Please copy dependagen/gen/gradle-templates/springboot/spring_boot_dependagen.gradle

sechub/gradle/spring_boot_dependagen.gradle

After this regenerate your IDE setup - e.g. for eclipse: ./gradlew cleanEclipse eclipse. Check there are no compile issues. If no problems appear you can commit and push and the update is done.

8. Documentation

8.1. Documentation types

8.1.1. Markdown

Simple technical information - e.g. about the content of an folder - should be written in a README.md with markdown syntax.

8.1.2. Asciidoc

When a full scaled documentation is needed it should be done with Asciidoc.
The documentation sources are inside the sechub-doc/src folder.

You can use the Asciidoc user manual or look into Asciidoc quick reference for more information

8.2. Documentation in code

8.2.1. Automated description of important code part

There exists an annotation @MustBeDocumented , which is not only used as a marker for important code parts but also is used by an automatic generation of an .adoc file which are included in asciidoc documentation.

8.2.2. Automated description of configuration properties

With usage of @MustBeDocumented at Spring annotation @Value the infrastructure properties can be documented automatically.

8.2.3. Automated description of use cases

With usage of special usecase annotations which itself are marked with @UseCaseDefintion it’s possible to create an automated use case description. It contains also generated Usecase event trace overview diagrams.

8.2.4. Automated Diagrams

8.2.4.1. Domain messaging overview

Using Annotations, which are itself tagged with @DomainMessaging annotation, those parts will automatically listed inside generated messaging diagram(s) gen_domain_messaging_overview.plantuml :

Click to reveal the diagram

For an example look into @IsReceivingAsyncMessage and look also for its references.

8.2.4.2. Usecase event overview diagrams

For some usecases we got event trace information (from special integration tests). With this information additional diagrams are generated and included at usecase description level. They show the events happening after a usecase has been triggered.

But not every usecase has got such a diagram: Either there are no events (can happen) or just no integration test for this case has been created.

8.3. Documentation generation

By calling gradlew documentation the AsciidocGenerator is build and used. This generator will automatically generate documentation areas like System properties or Scheduling which will be rendered by Asciidoctor afterwards.

8.4. Prerequisites

To have Usecase event overview generated, the integrationtests must have run before! Otherwise this information will not be shown inside the asciidoc output! This was optional to seperate documentation and integration tests. But even tracing can only be done at runtime - so it’s necessary to execute integration tests and then create documentation.

Build server and GitHub action do this automatically.

8.5. Generation of SecHub pages

With each release, the github pages documents are being updated automatically by the release action workflow.

9. Build

9.1. About build technology

Leading entry point/technology is always gradle. So if you want to build something, please look at the corresponding gradle tasks.

We use github-actions for CI which gives us a quick response at github.com. For automated deployment or S3 storage testing etc. Jenkins can be used by defined pipeline scripts.

9.2. Jenkins auto deployment

When you want to build and automate deployment of SecHub by Jenkins you can use a preconfigured pipeline script.

Your Jenkins server should be at minimum: Jenkins ver. 2.176.1.

The described Jenkins auto deployment is now relying on the GitHub actions build - see GitHub workflows folder. Deployment artifacts are available at after gradle workflow has been done.

In future the artifacts will be automatically available in github packages so you can use those for your autodeployment process and just use it as a maven repository. In the meantime you must deploy manually. Why still a jenkins file then?

You get informed about new available releases.
Also the jenkins will check additionally for problems
You can do a checksum test for outputs - if you want to check that the SecHub build is not corrupted and every version can be rebuild at any time

9.2.1. Continous integration build

This setup builds all branches except master (master is always build by next job…). The multibranch pipeline build is for continous integration builds - means to get fast feedback.

Please setup CI by…

Jenkins → Manage → Manage Credentials
- add sechub-server containing the SecHub server url
- add sechub-userid containing the SecHub user id
- add sechub-api-token containing the api token for sechub-userid
Jenkins → create new Item → Multibranch pipeline, name: sechub-open-source-ci
Branch sources: Git+
- Project repository: https://github.com/mercedes-benz/sechub.git
- Behaviours:
  1. Discover branches
  2. Filter by name (with wildcards):

      Include: *
      Exclude: master

Build configuration:
- Mode by jenkinsfile
- Script path: continous-integration-multibranch-pipeline.jenkins
Scan Multibranch Pipeline Triggers
- Periodically if not otherwise run
- Interval 5 minutes
Save …

9.2.2. Release build

Release builds are only done at master branch and do also publish artifacts to maven repository when commit has been tagged. The tags are starting with a v then be followed by major.minor.hotfix, a hyphen and then the type.

A server could be released by a tag like v1.1.0-server, a new client by v1.2.0-client for example.

For setup release build please do following:

Jenkins > create new Item → Pipeline, name: sechub-open-source-release
Build triggers : Poll SCM
Schedule:

  # every five minutes
  H/5 * * * *

Pipeline: Pipeline script from SCM
- SCM: Git
- Repository URL: https://github.com/mercedes-benz/sechub.git
- Branches to build: */master
- Script Path: release-pipeline.jenkins
Save …

Don’t use accidently a multibranch pipeline here but only a pipeline job! Otherwise the algorithm for automatical calling for sechub-serer-released and sechub-client-released jobs does not work. Reason: multibranch pipelines handle tags special and will not fetch tags - what is necessary for release.

9.2.3. Special client and server release trigger jobs

If there are new versions of client or server available - means tagged with client or server versions (e.g. v1.1.0-server or v1.2.0-client) the former created release job will automatically publish client and server artifacts (includes documentation, spring boot jars, binaries etc.) to dedicated maven repository and after this calls one/or two of the following jobs:

sechub-server-released with parameter SERVERVERSION as 1.1.0
sechub-client-released with parameter CLIENTVERSION as 1.2.0

So you have to add these additional Pipeline jobs.

The client and server release jobs has to be stored in another git repository containing your specific deployment parts etc.

9.2.3.1. Examples

Here are some simple examples - easy to adopt:

Example for a sechub-server-released job

// SPDX-License-Identifier: MIT
pipeline {
    agent any
    parameters {
         string(
             name: 'SERVERVERSION',
             defaultValue: '0.0.0',
             // OSS build does enter this automatically!
             description: 'New server version...'
         )
    }

    stages {
        stage('Handle new server released') {
            steps {
                echo "Implement me: deploy server :${params.SERVERVERSION}"
            }
        }
    }
}

Example for a sechub-client-released job

// SPDX-License-Identifier: MIT
pipeline {
    agent any
    parameters {
         string(
             name: 'CLIENTVERSION',
             defaultValue: '0.0.0',
             // OSS build does enter this automatically!
             description: 'New client version...'
         )
    }

    stages {
        stage('Handle new client released') {
            steps {
                echo "Implement me: upload client :${params.CLIENTVERSION}"
            }
        }
    }
}

9.3. Build stages

Builds stages were introduced because of a problematic build dependency situation when it comes to Java API generation. Build stages avoid cyclic build dependencies.

sechub-api-java uses a code generator which needs an OpenAPI file. But this file is only available when SecHub server and PDS projects are compiled!

Figure 5. Stages

To switch between the stages you have to define system property sechub.build.stage.

You do not need to define a build stage for "normal" SecHub development.

Only when you want to develop/build sechub-pds-tools, sechub-systemtest or the sechub-api-java you need to setup the build stage accordingly.

9.3.1. Kind of stages

The build has following stages:

without-api (default)
The build will build everything, except those gradle projects which require the OpenAPI file or the generated and compiled Java API.
api-necessary The Gradle initialization phase does contain additionally the Gradle projects which rely on an existing OpenAPI definition and/or access to build artifacts of sechub-api-java. This means the open file definition does already exist and may not change in the build.
all
Everything is included, no constraints at all.

The logic is provided inside BuildStage.groovy and a snippet inside settings.gradle. In a nutshell: During the Gradle initialization phase the API related projects are only added if wanted.

9.3.2. Special treatment on IDE imports

Because the API related gradle projects are not initialized per default, the IDE import mechanism will not automatically import gradle subprojects like sechub-systemtest.

For the gradle eclipse task there is a special treatment added inside sechub-developertools/build.gradle:

9.3.2.1. Eclipse

When you execute ./gradlew eclipse at command line the eclipse files for those projects will be generated. As next step import the additionally created projects manually into Eclipse ("Import → existing projects").

If you are using the Eclipse standard Gradle integration (Eclipse Buildship), the manual import step is probably necessary as well.

Another option is to use the EGradle plugin - it uses also ./gradlew eclipse and does the import automatically.

9.3.2.2. IntelliJ

For IntelliJ - similar to the steps for Eclipse - you can use the gradle idea task ./gradlew idea -Dsechub.build.stage=all

9.4. Gradle build commands overview

9.4.1. Build Server

Just call

./gradlew build

9.4.2. Build Client

Just call

./gradlew buildGo

9.4.3. Execute integration tests

Just call

./gradlew integrationtest

This will start also an integration test server

9.4.4. Build Documentation

Just call

./gradlew documentation

9.4.5. Publish artefacts

Just call

./gradlew publish

(if not already builds done this will be triggered automatically)

10. Concepts

10.1. 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 .

10.1.1. REST API for global mapping

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

REST API for UC_037-Admin updates mapping configuration
REST API for UC_038-Admin fetches mapping configuration

10.1.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"
  } ]
}

10.2. 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.

Technically we assign a projectId to a profile, because in domain scan we only know projectIds but not Project entity…

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

10.3. 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.

10.3.1. Data structure

10.3.1.1. Name

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

10.3.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).

10.3.1.3. UUID

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

10.3.1.4. Product identifier

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

PDS_CODESCAN
PDS_WEBSCAN
PDS_INFRASCAN
PDS_LICENSESCAN

10.3.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.

10.3.1.6. Product base URL

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

As an example: https://checkmarx.example.org:6011

10.3.1.7. Product credentials

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

10.3.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.

10.3.1.7.2. User

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

10.3.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.

10.3.1.8. Parameters

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

10.3.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.

10.3.1.8.2. Key values

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

10.3.2. Product specific details

10.3.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 26. 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

10.3.2.2. Checkmarx

10.3.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!

======= Technical details Checkmarx install setup does use a dedicated configuration support to provide presetId and teamId to adapter. Adapter will use presetId (if defined) and teamId (mandatory as before) when project creation is necessary

10.3.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…)

10.3.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…)

10.3.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

10.3.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.

10.3.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.

10.3.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!

10.4. 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.

10.4.1. General

10.4.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.

10.4.2. Mapping

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

Just use the provider ID as mapping ID.

10.4.2.1. Technical details

Usage

A caller can use the ScanMappingConfigurationService to fetch an NamePatternIdprovider which is able to provide an ID for a given name. This is a very generic approach and callers must only use unique IDs to have dedicated, name based id mappings.

An ID can be any string. Given regular expressions are handled by JAVA regular expression Pattern

Cluster handling Synchronization inside cluster is done over database and a special scheduler service: ScanMappingConfigurationRefreshTriggerService . This servcie checks periodically if current scan configuration has been changed by administrators. If so the name pattern provider will be rebuild.

10.4.3. Modules and module groups

10.4.3.1. Modules

Security tools are categorized into modules. Each module performs a different security testing method:

Module

Description

codeScan

Scans the code for potential vulnerabilities (weaknesses). Also known as SAST or static source code analysis

webScan

Scans a deployed web application for vulnerabilities. Also known as DAST.

infraScan

Scans infrastructure for vulnerabilities.

licenseScan

Scans code or artifacts for license information

secretScan

Scans code or artifacts for secrets

Internally a module is represented by a dedicated ScanType.

10.4.3.2. Module groups

Every module belongs to exact one module group:

Module

Module group

codeScan

static

webScan

dynamic

infraScan

network

licenseScan

static

secretScan

static

Every module group contains at least one module:

Module group

Contained modules

static

codeScan, licenseScan, secretScan

dynamic

webScan

network

infraScan

Inside a SecHub configuration file the user defines which modules shall be executed by the SecHub job. But only modules which are in same module group can be run as part of the same job.

As an example:

Inside one SecHub job configuration file, it is

not possible to define codeScan and a webScan
(because modules are in different module groups)
but it is possible to define a codeScan and a licenseScan
(because both belong to same module group)

A ScanProjectConfigService provides access to ScanProjectConfig entities for a given ScanProjectConfigID key for a dedicated project.

We currently store the following types of data through this mechanism:

Mock configuration
False positive configuration false positive configuration
Project access level

You can look into ScanProjectConfigID and check call hierarchy to get more details.

10.5. False-positive handling

SecHub must be able to handle false positives of used products.

10.5.1. General

10.5.1.1. How can false positives be handled across multiple security products?

10.5.1.1.1. Problem

Missing API

Most commercial security products are able to mark false positives, but maybe not every tool has a dedicated API for this feature. In addition, many FOSS security tools do not support false positive handling.

10.5.1.1.2. Solution

Instead of configuring false positives for each product (e.g. by calling a REST API) we do the filtering of false positives always at SecHub side only!

The involved product just returns all it’s findings without any false positive marking on the product side. SecHub will store the product results in the database without any filtering.

Only when it comes to report generation at the end, SecHub will filter the false positives from the result. This makes it easy to debug - the original information from the product is still available and problems on false positive marking can be reproduced and fixed.

10.5.1.2. Different kinds of false-positive filtering

Some people prefer code/API-centric way to define false positives, some prefer a WebUI.

10.5.1.2.1. API centric

Define false positive handling in JSON by referencing a former SecHub job UUID and the corresponding finding entry (by id) and post it to REST API.

JSON

{
  "apiVersion": "1.0", (1)
  "type": "falsePositiveJobDataList", (2)
  "jobData": [
    {
      "jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd", (3)
      "findingId": 1, (4)
      "comment": "Absolute Path Traversal, can be ignored because not in deployment" (5)
    },
    {
      "jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd",
      "findingId": 15
    }
  ]
}

1	API version
2	a type identifier for false positives, so it’s clear what this file represents
3	job UUID for which the given identifiers are representative
4	the finding id (number) in the report
5	comment (optional) are only to define why this is a false positive.

This is a very easy, generic approach - and also future-proof: The only dependency is to the job, UUID, for which the report must still exist while the definition is done. Every false-positive in any kind of scan can be handled like that.

The REST controller logic does read the job result data and creates internally false positive meta data. If we delete later the SecHub job it cannot destroy our false positive setup in SecHub.

ID handling

We must ensure identifiers are always correct and continue even for false positives. An example:

We have a SecHub job 1 were we mark the first finding with id 1 as a false positve. Executing now SecHub job 2 finding with id 1 must be filtered. But findings may no longer start with identifier 1! Because the finding already exists.

10.5.1.2.2. Web UI

Just uses the API centric approach (by using given REST API,) over UI.

10.5.1.2.3. Code centric

Inside source code / deployment scripts etc. users can define comments to define false positive handling - this is only possible for situations where we have access to source code - means SAST (static application security testing)

Currently this is not supported!

The detection algorithm is already implemented inside sechub-anlyzer-cli but we still have no analyzer phase and a PDS solution to collect these code information automatically.
So this will still need some time.

10.5.2. Technical details about false positive handling

There are two different kind of phases:

User definition of false positive definitions
Job execution / runtime

10.5.2.1. Definition phase

When a user has a SecHub report with some findings - the user can define false positives by the report UUID and the finding id which represents the false positive.

The configuration is described at how to define false positives by API.

The user gives only information about which finding in an existing report is seen as a false positive. While a new false positive is created, SecHub inspects the report and fetches all necessary meta data internally - depending on the scan type.

These meta data will be stored independently from the report. So even if the report will be deleted afterwards, the false-positive handling will still work!

At this phase duplicate checks are only done for tuples of report UUID and finding id!
Meta data is only collected in definition phase, but NOT inspected! !

Here a simple example for better understanding:

A user has 10 reports but containing always the same finding
The user marks for all of these reports the finding again as false positive
This will result in 10 false positive entries (and it’s meta data) inside the database because SecHub does NOT inspect at this time that we have duplicates here!

10.5.2.1.1. Overview

The next figure shows a simplified UML diagram (shows only relevant parts). Below the figure you will find sub chapters with more information.

Figure 6. Overview definition phase

10.5.2.1.2. Used storage mechanism

For every SecHub project a project scan config entry for false positives exists. The entry does contain a FalsePositiveProjectConfiguration object as JSON.

10.5.2.1.3. Data structure

The FalsePositiveProjectConfiguration object contains a list of FalsePositiveEntry objects.

Every FalsePositveEntry object contains

FalsePositiveJobData
contains job uuid, finding id and comment - this information is provided by user.
FalsePositiveMetaData
contains meta information about findings - this information is gathered and calculated by SecHub internally when a user has marked a report finding as a false positive. So the meta information is independent (so when a reoprt has been deleted, we still have the false positive meta information).
It contains many meta information - e.g. a cweId - but also FalsePositiveCodeMetaData for code scans details.

10.5.2.1.4. Definition by user

A user does define a FalsePositiveJobDataList object which contains only FalsePositiveJobData inside. Such a list will be used to add but also to remove false positives.

10.5.2.1.5. Merging

When a user adds or removes false positive definitions, the FalsePositiveProjectConfiguration will be updated by FalsePositiveJobDataConfigMerger.

10.5.2.2. Job execution phase

Here Sereco is in charge, which does only inspect the meta data.

10.5.2.2.1. Overview

Figure 7. Overview runtime phase

10.5.3. Code scan

10.5.3.1. API centric

see general concept

10.5.3.1.1. How to identify same vulnerability on code changes?

We inspect source and sink and use
- Location
- relevant part - this is absolutely necessary.
Line numbers must always be irrelevant!

Very important for Sereco: If no relevant part is available we must at least create a pseudo one by given source snippet - in a whitespace reduced form! We will compress the source content, so adding new lines, spaces, tabs etc. would not matter.

So if a product does not support "relevant part" detection we must create the "relevant part" inside Sereco as fallback!

10.5.3.2. Web UI

see general concept

10.5.3.3. Code centric

This approach is currently not enabled/full supported!

Details: CLI analyzer is already implemented which contains logic for search etc, but currently SecHub does not use it because there is a need for PDS execution. We also need a special type of executions introduced: AnalyzerProductExecutor, which is not at this moment.

Inside source code the developers will be able to mark their code, marked as vulnerable, as being a false positive by using comments. After the push to repository it’s inside history who was defining the vulnerability as a false positive.

We use following tags:

NOSECHUB

and

NOSECHUB-END

In future we could provide additional identifiers for NOSECHUB to define which kind of false positive is ignored/will not be fixed. The kind/type must be product independant defined and clear to understand. Maybe a CWE ID would be the best choice.

E.g. NOSECHUB:CWE-79

10.5.3.3.1. Java

We will provide single comments (//)

// SPDX-License-Identifier: MIT

public class FalsePositiveJavaApplication {
    
    public static void main(String[] args) {
        // NOSECHUB (1)
        falsePositiveCall(); //NOSECHUB-END (2)
    }
}

1	marks start
2	marks end

All between those tags will be ignored by SecHub.

10.5.4. Web scan

10.5.4.1. Code centric

Not possible

10.5.4.2. API centric

see general concept

10.5.4.3. Web UI

see general concept

10.5.5. Infra scan

10.5.5.1. Code centric

Not possible

10.5.5.2. API centric

see general concept

The identification of similarity is done here by

Code scans: CWE id
Web scans: CWE id

For infrastructure scans a false positive detection is currently not implemented.

10.5.5.3. Web UI

see general concept

10.6. Auto cleanup

To prevent full hard drives there is an option to automatically remove old data.

10.6.1. Configuration

Administrators can configure the auto cleanup configuration by uploading a json configuration via REST (see REST API for UC_065-Admin updates auto cleanup configuration ).

{
  "cleanupTime" : {
    "unit" : "months", (1)
    "amount" : 3 (2)
  }
}

1	The time unit to use. Can be day(s), DAY(S) month(s), MONTH(S) week(s), WEEK(S) or year(s), YEAR(S)
2	Amount of time. When `0` is defined, the auto cleanup is deactivated, all other positive values are time unit related. Negative values are not allowed.

10.6.2. Execution

The execution is automatically done by SecHub.

10.6.3. Cleaned data

All data which is older than the defined time period is removed from:

Scan product results
Scan project log
Schedule job entries
Administration job information

Scan report data is currently NOT deleted. So it can be used for statistics. In a later feature there will be specialized statistic tables - when this has been implemented, the auto cleanup will be extended to drop old scan report data as well.

10.7. Analytics

SecHub can be configured to analyze a scan situation at the beginning to improve runtime behavior or to create statistic data. This is done before all other scans.

As usual, different products can be used to provide the analytic data. The analytic scan products can be configured as any other product by defining a executor configuration and add it to a execution profile which can be assigned to SecHub projects.

The AnalyticsProductExecutionService inside the scan domain does not only execute and store the product results, but also creates an analytic data model after the analytic scan products have been executed.

This data model can be used at runtime by other product executors inside the scan domain but also in other domains via domain messaging.

Currently the information is not used at runtime by other product executors but only inside statistic domain.

10.8. Statistics

For statistic data handling exists an own domain statistic. The data is collected in dedicated statistic SQL tables.

Statistic data is NOT auto cleaned.

Every data which shall be stored as statistic data is send from other domains via domain message bus.

Here an short overview about the involved event locations:

Figure 8. Overview about incoming events for statistics

Inside the entity model we use a very loose coupling (no constraints).
To make SQL queries for static tools as easy as possible, the JobRunStatistic table has a little bit of redundance: created and projectId (but this was wanted).

Figure 9. Entity model for statistic tables

10.9. Domain driven design

10.9.1. Domain Message Bus

The domain message bus represents an abstraction layer for communication between different domains. It shall be the ONLY way to communicate between the different domains. Purpose: In future maybe the domains will be separate spring boot applications and be also autark deployable!

Currently SecHub contains of ONE deployable spring boot application. But to prevent the "Big ball of mud" this abstraction must be always used when one domain calls another one.

10.9.2. Domain communication and actions

Figure 10. Domain communication and actions

10.9.2.1. Overview

10.9.2.1.1. Diagram

10.9.2.1.2. List of all messages

ANALYZE_SCAN_RESULTS_AVAILABLE
AUTO_CLEANUP_CONFIGURATION_CHANGED
BINARY_UPLOAD_DONE
JOB_CANCELLATION_RUNNING
JOB_CREATED
JOB_DONE
JOB_EXECUTION_STARTING
JOB_FAILED
JOB_RESTART_CANCELED
JOB_RESTART_TRIGGERED
JOB_RESULTS_PURGED
JOB_RESULT_PURGE_DONE
JOB_RESULT_PURGE_FAILED
JOB_STARTED
MAPPING_CONFIGURATION_CHANGED
PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE
PROJECT_ACCESS_LEVEL_CHANGED
PROJECT_CREATED
PROJECT_DELETED
PROJECT_OWNER_CHANGED
PROJECT_WHITELIST_UPDATED
REQUEST_JOB_CANCELLATION
REQUEST_JOB_RESTART
REQUEST_JOB_RESTART_HARD
REQUEST_PURGE_JOB_RESULTS
REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING
REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING
REQUEST_SCHEDULER_JOB_STATUS
REQUEST_SCHEDULER_STATUS_UPDATE
REQUEST_USER_ROLE_RECALCULATION
SCAN_DONE
SCAN_FAILED
SCHEDULER_JOB_PROCESSING_DISABLED
SCHEDULER_JOB_PROCESSING_ENABLED
SCHEDULER_JOB_STATUS
SCHEDULER_STARTED
SCHEDULER_STATUS_UPDATE
SOURCE_UPLOAD_DONE
START_SCAN
UNSUPPORTED_OPERATION
USER_ADDED_TO_PROJECT
USER_API_TOKEN_CHANGED
USER_BECOMES_SUPERADMIN
USER_CREATED
USER_DELETED
USER_EMAIL_ADDRESS_CHANGED
USER_NEW_API_TOKEN_REQUESTED
USER_NO_LONGER_SUPERADMIN
USER_REMOVED_FROM_PROJECT
USER_ROLES_CHANGED
USER_SIGNUP_REQUESTED

10.9.2.2. Message ANALYZE_SCAN_RESULTS_AVAILABLE

Sequence diagram of messaging ANALYZE_SCAN_RESULTS_AVAILABLE

10.9.2.3. Message AUTO_CLEANUP_CONFIGURATION_CHANGED

Sequence diagram of messaging AUTO_CLEANUP_CONFIGURATION_CHANGED

Use cases related to this message

UC_065-ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

10.9.2.4. Message BINARY_UPLOAD_DONE

Sequence diagram of messaging BINARY_UPLOAD_DONE

10.9.2.5. Message JOB_CANCELLATION_RUNNING

Sequence diagram of messaging JOB_CANCELLATION_RUNNING

10.9.2.6. Message JOB_CREATED

Sequence diagram of messaging JOB_CREATED

10.9.2.7. Message JOB_DONE

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.8. Message JOB_EXECUTION_STARTING

Sequence diagram of messaging JOB_EXECUTION_STARTING

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.9. Message JOB_FAILED

Sequence diagram of messaging JOB_FAILED

10.9.2.10. Message JOB_RESTART_CANCELED

Sequence diagram of messaging JOB_RESTART_CANCELED

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.11. Message JOB_RESTART_TRIGGERED

Sequence diagram of messaging JOB_RESTART_TRIGGERED

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.12. Message JOB_RESULTS_PURGED

Sequence diagram of messaging JOB_RESULTS_PURGED

Use cases related to this message

UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.13. Message JOB_RESULT_PURGE_DONE

Sequence diagram of messaging JOB_RESULT_PURGE_DONE

10.9.2.14. Message JOB_RESULT_PURGE_FAILED

Sequence diagram of messaging JOB_RESULT_PURGE_FAILED

10.9.2.15. Message JOB_STARTED

Sequence diagram of messaging JOB_STARTED

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.16. Message MAPPING_CONFIGURATION_CHANGED

Sequence diagram of messaging MAPPING_CONFIGURATION_CHANGED

10.9.2.17. Message PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE

Sequence diagram of messaging PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE

10.9.2.18. Message PROJECT_ACCESS_LEVEL_CHANGED

Sequence diagram of messaging PROJECT_ACCESS_LEVEL_CHANGED

10.9.2.19. Message PROJECT_CREATED

Sequence diagram of messaging PROJECT_CREATED

10.9.2.20. Message PROJECT_DELETED

Sequence diagram of messaging PROJECT_DELETED

10.9.2.21. Message PROJECT_OWNER_CHANGED

Sequence diagram of messaging PROJECT_OWNER_CHANGED

10.9.2.22. Message PROJECT_WHITELIST_UPDATED

Sequence diagram of messaging PROJECT_WHITELIST_UPDATED

10.9.2.23. Message REQUEST_JOB_CANCELLATION

Sequence diagram of messaging REQUEST_JOB_CANCELLATION

10.9.2.24. Message REQUEST_JOB_RESTART

Sequence diagram of messaging REQUEST_JOB_RESTART

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB

10.9.2.25. Message REQUEST_JOB_RESTART_HARD

Sequence diagram of messaging REQUEST_JOB_RESTART_HARD

Use cases related to this message

UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.26. Message REQUEST_PURGE_JOB_RESULTS

Sequence diagram of messaging REQUEST_PURGE_JOB_RESULTS

Use cases related to this message

UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.27. Message REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING

Sequence diagram of messaging REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING

Use cases related to this message

UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

10.9.2.28. Message REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING

Sequence diagram of messaging REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING

Use cases related to this message

UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

10.9.2.29. Message REQUEST_SCHEDULER_JOB_STATUS

Sequence diagram of messaging REQUEST_SCHEDULER_JOB_STATUS

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.30. Message REQUEST_SCHEDULER_STATUS_UPDATE

Sequence diagram of messaging REQUEST_SCHEDULER_STATUS_UPDATE

10.9.2.31. Message REQUEST_USER_ROLE_RECALCULATION

Sequence diagram of messaging REQUEST_USER_ROLE_RECALCULATION

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

10.9.2.32. Message SCAN_DONE

10.9.2.33. Message SCAN_FAILED

Sequence diagram of messaging SCAN_FAILED

10.9.2.34. Message SCHEDULER_JOB_PROCESSING_DISABLED

Sequence diagram of messaging SCHEDULER_JOB_PROCESSING_DISABLED

Use cases related to this message

UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

10.9.2.35. Message SCHEDULER_JOB_PROCESSING_ENABLED

Sequence diagram of messaging SCHEDULER_JOB_PROCESSING_ENABLED

Use cases related to this message

UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

10.9.2.36. Message SCHEDULER_JOB_STATUS

Sequence diagram of messaging SCHEDULER_JOB_STATUS

10.9.2.37. Message SCHEDULER_STARTED

Sequence diagram of messaging SCHEDULER_STARTED

10.9.2.38. Message SCHEDULER_STATUS_UPDATE

Sequence diagram of messaging SCHEDULER_STATUS_UPDATE

10.9.2.39. Message SOURCE_UPLOAD_DONE

Sequence diagram of messaging SOURCE_UPLOAD_DONE

10.9.2.40. Message START_SCAN

Sequence diagram of messaging START_SCAN

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

10.9.2.41. Message UNSUPPORTED_OPERATION

Sequence diagram of messaging UNSUPPORTED_OPERATION

10.9.2.42. Message USER_ADDED_TO_PROJECT

Sequence diagram of messaging USER_ADDED_TO_PROJECT

Use cases related to this message

UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT

10.9.2.43. Message USER_API_TOKEN_CHANGED

Sequence diagram of messaging USER_API_TOKEN_CHANGED

10.9.2.44. Message USER_BECOMES_SUPERADMIN

Sequence diagram of messaging USER_BECOMES_SUPERADMIN

10.9.2.45. Message USER_CREATED

Sequence diagram of messaging USER_CREATED

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP

10.9.2.46. Message USER_DELETED

Sequence diagram of messaging USER_DELETED

10.9.2.47. Message USER_EMAIL_ADDRESS_CHANGED

Sequence diagram of messaging USER_EMAIL_ADDRESS_CHANGED

10.9.2.48. Message USER_NEW_API_TOKEN_REQUESTED

Sequence diagram of messaging USER_NEW_API_TOKEN_REQUESTED

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP

10.9.2.49. Message USER_NO_LONGER_SUPERADMIN

Sequence diagram of messaging USER_NO_LONGER_SUPERADMIN

10.9.2.50. Message USER_REMOVED_FROM_PROJECT

Sequence diagram of messaging USER_REMOVED_FROM_PROJECT

Use cases related to this message

UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

10.9.2.51. Message USER_ROLES_CHANGED

Sequence diagram of messaging USER_ROLES_CHANGED

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

10.9.2.52. Message USER_SIGNUP_REQUESTED

Use cases related to this message

UC_001-SIGNUP

10.10. Use cases

The complete documentation about use cases is generated. If you want to change content, please search for @UseCaseDefinition references in source code and make necessary changes inside code!

10.10.1. Overview about usecase groups

10.10.1.1. Anonymous

All these usecases handling anonymous access.

UC_039-Check if the server is alive and running.

10.10.1.2. User administration

Usecases handling administration of users

UC_004-Admin lists all users
UC_015-Admin assigns user to project
UC_016-Admin unassigns user from project
UC_017-Admin shows user details
UC_018-Admin deletes a user
UC_021-Admin shows project details
UC_026-Admin downloads all details about a scan job
UC_027-Admin grants admin rights to user
UC_028-Admin revokes admin rights from an admin
UC_029-Admin lists all admins
UC_060-Admin changes owner of a project
UC_063-Admin updates user email address
UC_072-Admin shows user details for email address

10.10.1.3. Project administration

Usecases for project administration

UC_013-Admin creates a project
UC_014-Admin lists all projects
UC_016-Admin unassigns user from project
UC_020-Admin deletes a project
UC_022-Update project whitelist
UC_025-Admin shows scan logs for project
UC_059-Update project metadata
UC_061-Admin changes project description
UC_062-Admin changes project access level

10.10.1.4. User profile

User actions belonging to their profiles

UC_012-User clicks link to get new api token

10.10.1.5. Sechub execution

Execution of SecHub -either by CLI or direct with REST api call

UC_005-User creates a new sechub job
UC_006-User uploads source code
UC_007-User approves sechub job
UC_009-User checks sechub job state
UC_010-User downloads sechub job report
UC_011-User starts scan by client
UC_044-User marks false positives for finished sechub job
UC_045-User unmarks existing false positive definitons
UC_046-User fetches false positive configuration of project
UC_069-User uploads binaries
UC_070-User downloads job report in SPDX format

All these usecases are handling user sign up (part of user self registration process)

UC_001-User self registration
UC_002-Admin lists open user signups
UC_003-Admin applies self registration
UC_019-Admin deletes user signup
UC_024-User requests new API token

10.10.1.7. Job administration

Usecases about job administration

UC_023-Admin lists all running jobs
UC_034-Admin cancels a job
UC_041-Admin restarts a job
UC_042-Admin restarts a job (hard)

10.10.1.8. Technical

Usecases about technical operations being executed by sechub itself

UC_008-Sechub scheduler starts job
UC_043-Admin receives notification about start of a new scheduler instance
UC_066-Sechub administration domain auto cleanup
UC_067-Sechub scan domain auto cleanup
UC_068-Sechub schedule domain auto cleanup

10.10.1.9. Testing

Some use cases for testing

UC_035-User defines mock data configuration for project
UC_036-User retrieves mock data configuration for project

10.10.1.10. Configuration

Usecases for configuration parts

UC_037-Admin updates mapping configuration
UC_038-Admin fetches mapping configuration
UC_047-Admin creates an executor configuration
UC_048-Admin deletes executor configuration
UC_049-Admin fetches executor configuration list
UC_050-Admin fetches executor configuration
UC_051-Admin updates executor configuration setup
UC_052-Admin creates an execution profile
UC_053-Admin deletes execution profile
UC_054-Admin updates execution profile
UC_055-Admin fetches execution profile
UC_056-Admin fetches execution profile list
UC_057-Admin assigns execution profile to project
UC_058-Admin unassigns execution profile from project
UC_064-Admin fetches auto cleanup configuration
UC_065-Admin updates auto cleanup configuration

10.10.1.11. Other

All other use cases

UC_030-Admin disables job processing in scheduler
UC_031-Admin enables scheduler job processing
UC_032-Admin get scheduler status
UC_033-Admin lists status information
UC_040-Admin fetches server runtime data
UC_071-User lists jobs for project

10.10.2. UC_001-User self registration

The self registration can be done by anonymous users.

If a user is not already inside the system and there exists not already a self registration the signup is persisted.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.UseCaseUserSignup

Event overview

Involved messages

UC_001-SIGNUP

Steps

Nr	Title	Next	Description
1	Rest API call	2	Rest api called to register user. Normally done by user itself This step is defined at method `registerUser` in class `com.mercedesbenz.sechub.domain.administration.signup.AnonymousSignupRestController`
2	Persistence	3	Valid self registration input will be persisted to database. This step is defined at method `register` in class `com.mercedesbenz.sechub.domain.administration.signup.AnonymousSignupCreateService`
3	Email to user	4	A notification is send per email to user that a new user signup has been created and waits for acceptance. This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.SignUpRequestedUserNotificationService`
4	Email to admin		A notification is send per email to admins that a new user signup has been created and waits for acceptance. This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.SignUpRequestedAdminNotificationService`

REST API documentation for usecase UC_001-User self registration

10.10.3. UC_002-Admin lists open user signups

In this usecase the administrator will list the currently unapplied user self registrations/signups.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.signup.UseCaseAdminListsOpenUserSignups

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

All self registrations are returned as json

This step is defined at method listUserSignups in class `com.mercedesbenz.sechub.domain.administration.signup.SignupAdministrationRestController`

REST API documentation for usecase UC_002-Admin lists open user signups

10.10.4. UC_003-Admin applies self registration

In this usecase the administrator will accept the self registration done by an user.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.signup.UseCaseAdminAcceptsSignup

Event overview

Involved messages

UC_003-ADMIN_ACCEPTS_SIGNUP
UC_003-ADMIN_ACCEPTS_SIGNUP
UC_003-ADMIN_ACCEPTS_SIGNUP
UC_003-ADMIN_ACCEPTS_SIGNUP

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator accepts a persisted self registration entry by calling rest api

This step is defined at method acceptUserSignUp in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`

Create user and send events

SUPERADMIN

3, 4

The service will create the user a one time token for api token generation and triggers asynchronous events. It will also remove the existing user signup because no longer necessary.

This step is defined at method createUserFromSelfRegistration in class `com.mercedesbenz.sechub.domain.administration.user.UserCreationService`

Email to user

A notification is send per email to user that a new api token was requested. The mail contains a link for getting the secure API token

This step is defined at method notify in class `com.mercedesbenz.sechub.domain.notification.user.NewApiTokenRequestedUserNotificationService`

Give user access

Authorization layer is informed about new user and gives access to sechub. But without any project information

This step is defined at method createUser in class `com.mercedesbenz.sechub.domain.authorization.service.AuthUserCreationService`

REST API documentation for usecase UC_003-Admin applies self registration

10.10.5. UC_004-Admin lists all users

An administrator downloads a json file containing all user ids

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminListsAllUsers

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

All userids of sechub users are returned as json

This step is defined at method listUsers in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`

Service call

SUPERADMIN

All userids of sechub users are returned as json

This step is defined at method listUsers in class `com.mercedesbenz.sechub.domain.administration.user.UserListService`

REST API documentation for usecase UC_004-Admin lists all users

10.10.6. UC_005-User creates a new sechub job

A user wants to create a new sechub job.

This will not directly start the job. Please refer to User approves job.

As a result the user will have created a new SecHub job and have a job UUID as result. After this the user is able to

approve the job
upload source code for code scanning

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserCreatesNewJob

Steps

Nr Title Role(s) Next Description

Authenticated REST call

SUPERADMIN, USER

This step is defined at method createJob in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

Persistence and result

Persist a new job entry and return Job UUID

This step is defined at method createJob in class `com.mercedesbenz.sechub.domain.schedule.SchedulerCreateJobService`

REST API documentation for usecase UC_005-User creates a new sechub job

10.10.7. UC_006-User uploads source code

A user wants to upload sourcecode for a former created sechub job.

The source code must be a valid zipfile.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserUploadsSourceCode

Steps

Nr Title Role(s) Next Description

Authenticated REST call

SUPERADMIN, USER

This step is defined at method uploadSourceCode in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

Try to find project and upload sourcecode as zipfile

USER

When project is found and user has access and job is initializing the sourcecode file will be uploaded

This step is defined at method uploadSourceCode in class `com.mercedesbenz.sechub.domain.schedule.SchedulerSourcecodeUploadService`

REST API documentation for usecase UC_006-User uploads source code

10.10.8. UC_007-User approves sechub job

A user wants to approve a former created sechub job.

This means the user has done all necessary preparations - e.g. uploading source code for code scanning - and wants the job marked as ready for execution

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserApprovesJob

Steps

Nr Title Role(s) Next Description

Authenticated REST call

SUPERADMIN, USER

This step is defined at method approveJob in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

Try to find job annd update execution state

When job is found and user has access job will be marked as ready for execution

This step is defined at method approveJob in class `com.mercedesbenz.sechub.domain.schedule.SchedulerApproveJobService`

REST API documentation for usecase UC_007-User approves sechub job

10.10.9. UC_008-Sechub scheduler starts job

Scheduler service starts next SchedulerJob. Before a user has only created and approved a job which was lead only to database persistence of JobData. The work itself is triggered/executed here by asynchronous batch operation.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.job.UseCaseSchedulerStartsJob

Steps

Nr	Title	Next	Description
1	Scheduling	2	Fetches next schedule job from queue and trigger execution. This step is defined at method `triggerExecutionOfNextJob` in class `com.mercedesbenz.sechub.domain.schedule.SchedulerJobBatchTriggerService`
2	Execution	3, 4	Triggers job execution - done parallel, but with synchronous domain communication (to wait for result). This step is defined at method `executeJob` in class `com.mercedesbenz.sechub.domain.schedule.ScheduleJobLauncherService`
4	Store admin job info	5	Fetches event about started job and store info in admin domain. This step is defined at method `createByMessage` in class `com.mercedesbenz.sechub.domain.administration.job.JobInformationCreateService`
5	Update admin job info		Deletes store info in admin domain when job is done. This step is defined at method `delete` in class `com.mercedesbenz.sechub.domain.administration.job.JobInformationDeleteService`

10.10.10. UC_009-User checks sechub job state

User wants to get the state of the current running job.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserChecksJobStatus

Steps

Nr Title Role(s) Next Description

Authenticated REST call

SUPERADMIN, USER

This step is defined at method getJobStatus in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

Try to find project and fail or return job status

This step is defined at method getJobStatus in class `com.mercedesbenz.sechub.domain.schedule.SchedulerGetJobStatusService`

REST API documentation for usecase UC_009-User checks sechub job state

10.10.11. UC_010-User downloads sechub job report

A user wants to download a SecHub report for an executed job by its given job UUID.

The report standard format is a human and machine readable JSON format. Additionally, there is the option to download the report as HTML file.

Both, the HTML and the JSON file have a reduced view of the scan results. Code snippets etc. can be found on the real security products.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserDownloadsJobReport

Steps

Nr Title Role(s) Next Description

REST API call to get JSON report

SUPERADMIN, USER

This step is defined at method getScanSecHubReportAsJSON in class `com.mercedesbenz.sechub.domain.scan.report.ScanReportRestController`

REST API call to get HTML report

SUPERADMIN, USER

This step is defined at method getScanSecHubReportAsHTML in class `com.mercedesbenz.sechub.domain.scan.report.ScanReportRestController`

Resolve scan report result

This step is defined at method getObfuscatedScanSecHubReport in class `com.mercedesbenz.sechub.domain.scan.report.DownloadScanReportService`

REST API documentation for usecase UC_010-User downloads sechub job report

10.10.12. UC_011-User starts scan by client

Sechub has got it’s own client, written in go. The client is available for Linux and Windows and can be downloaded at https://github.com/mercedes-benz/sechub .

The client encapsulated and simplifies the necessary steps to do a scan to one single step only

It does automate following usecases:

Create a job
Upload sources if necessary
Approve the job
Check job has finished periodically
Download scan report

If the scan report traffic light is RED the build client will return an System exit code greater than zero so build will break.

More information about the client can be found inside the user documentation.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserStartsSynchronousScanByClient

Steps

Nr Title Role(s) Next Description

create new job

SUPERADMIN, USER

2, 3

This step is defined at method createJob in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

upload binaries

SUPERADMIN, USER

This step is defined at method uploadBinaries in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

upload sourcecode

SUPERADMIN, USER

This step is defined at method uploadSourceCode in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

approve job

SUPERADMIN, USER

This step is defined at method approveJob in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

download job report and traffic light

SUPERADMIN, USER

This step is defined at method getScanSecHubReportAsJSON in class `com.mercedesbenz.sechub.domain.scan.report.ScanReportRestController`

get job status

SUPERADMIN, USER

This step is defined at method getJobStatus in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

10.10.13. UC_012-User clicks link to get new api token

The user has to open the received email and click there on the contained link with a onetimetoken api which is another usecase.

This use case is either triggered by when a new user was initial registered or a new API token was requested by user.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.UseCaseUserClicksLinkToGetNewAPIToken

Steps

Nr	Title	Next	Description
1	Rest call	2	User opens url by browser This step is defined at method `getNewAPITokenByOneTimeToken` in class `com.mercedesbenz.sechub.domain.administration.user.AnonymousUserGetApiTokenByOneTimeTokenRestController`
2	Validation and update	3, 4	When its a valid one time token a new api token is generated and persisted hashed to user. The token itself is returned. When not valid an emtpy string is the result … This step is defined at method `createNewAPITokenForUserByOneTimeToken` in class `com.mercedesbenz.sechub.domain.administration.user.AnonymousUserGetAPITokenByOneTimeTokenService`
3	Update auth data		This step is defined at method `updateAPIToken` in class `com.mercedesbenz.sechub.domain.authorization.service.AuthUpdateUserApiTokenService`
4	Inform user about api token change done		This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.NewAPITokenAppliedUserNotificationService`

REST API documentation for usecase UC_012-User clicks link to get new api token

10.10.14. UC_013-Admin creates a project

Administrator creates a project inside SecHub.

A Project is the main entry point for every SecHub operation! For example a user must have a project assigned to be able to scan on it!

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminCreatesProject

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator creates a new project by calling rest api

This step is defined at method createProject in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`

Create project

SUPERADMIN

The service will create the project when not already existing with such name.

This step is defined at method createProject in class `com.mercedesbenz.sechub.domain.administration.project.ProjectCreationService`

REST API documentation for usecase UC_013-Admin creates a project

10.10.15. UC_014-Admin lists all projects

An administrator downloads a json file containing all project ids

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminListsAllProjects

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

All project ids of sechub are returned as json

This step is defined at method listProjects in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`

REST API documentation for usecase UC_014-Admin lists all projects

10.10.16. UC_015-Admin assigns user to project

An administrator assigns an user to an existing sechub project.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminAssignsUserToProject

Event overview

"Overview of events happening at usecase UC_ADMIN_ASSIGNS_USER_TO_PROJECT

Involved messages

UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator does call rest API to assign user This step is defined at method `assignUserToProject` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`
2	Assign user	SUPERADMIN	2	The service will add the user to the project. If user does not have ROLE_USER it will obtain it This step is defined at method `assignUserToProject` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAssignUserService`
2	Update schedule authorization parts		3	This step is defined at method `grantUserAccessToProject` in class `com.mercedesbenz.sechub.domain.schedule.access.ScheduleGrantUserAccessToProjectService`
3	Update scan authorization parts		4	This step is defined at method `grantUserAccessToProject` in class `com.mercedesbenz.sechub.domain.scan.access.ScanGrantUserAccessToProjectService`
4	Roles changed in auth			Authorization layer adds ROLE_USER This step is defined at method `updateRoles` in class `com.mercedesbenz.sechub.domain.authorization.service.AuthUserUpdateRolesService`

REST API documentation for usecase UC_015-Admin assigns user to project

10.10.17. UC_016-Admin unassigns user from project

An administrator unassigns an user from a sechub project.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminUnassignsUserFromProject

Event overview

"Overview of events happening at usecase UC_ADMIN_UNASSIGNS_USER_FROM_PROJECT

Involved messages

UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator does call rest API to unassign user This step is defined at method `unassignUserFromProject` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`
2	Unassign user	SUPERADMIN	2	The service will remove the user to the project. If users has no longer access to projects ROLE_USER will be removed This step is defined at method `unassignUserFromProject` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectUnassignUserService`
2	Update authorization parts		2	This step is defined at method `revokeUserAccessFromProject` in class `com.mercedesbenz.sechub.domain.scan.access.ScanRevokeUserAccessFromProjectService`
2	Update authorization parts		4	This step is defined at method `revokeUserAccessFromProject` in class `com.mercedesbenz.sechub.domain.schedule.access.ScheduleRevokeUserAccessFromProjectService`
4	Roles changed in auth			Authorization layer removes ROLE_USER This step is defined at method `updateRoles` in class `com.mercedesbenz.sechub.domain.authorization.service.AuthUserUpdateRolesService`

REST API documentation for usecase UC_016-Admin unassigns user from project

10.10.18. UC_017-Admin shows user details

An administrator downloads a json file containing json containing user details

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminShowsUserDetails

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Json returned containing details about user and her/his projects

This step is defined at method showUserDetails in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`

Service fetches user details.

SUPERADMIN

The service will fetch user details for given user id

This step is defined at method fetchDetails in class `com.mercedesbenz.sechub.domain.administration.user.UserDetailInformationService`

REST API documentation for usecase UC_017-Admin shows user details

10.10.19. UC_018-Admin deletes a user

An administrator deletes an user. All associations etc. are removed as well.

If the user is still a project owner the delete will not work and an error message will appear that this is not acceptable and that the ownership must be moved before User delete is possible.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminDeletesUser

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	User will be deleted This step is defined at method `deleteUser` in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`
2	Service deletes user.	SUPERADMIN	3, 4	The service will delete the user with dependencies and triggers asynchronous events This step is defined at method `deleteUser` in class `com.mercedesbenz.sechub.domain.administration.user.UserDeleteService`
3	revoke user from schedule access		3	This step is defined at method `revokeUserAccess` in class `com.mercedesbenz.sechub.domain.scan.access.ScanRevokeUserAccessAtAllService`
3	revoke user from schedule access		4	This step is defined at method `revokeUserAccess` in class `com.mercedesbenz.sechub.domain.schedule.access.ScheduleRevokeUserAccessAtAllService`
4	Delete user access			Authorization layer is informed about user deltete and removes access to sechub. But without any project information This step is defined at method `deleteUser` in class `com.mercedesbenz.sechub.domain.authorization.service.AuthUserDeleteService`
5	Inform user that the account has been deleted by administrator			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.UserDeletedNotificationService`

REST API documentation for usecase UC_018-Admin deletes a user

10.10.20. UC_019-Admin deletes user signup

In this usecase the administrator will not accept the self registration done by an user but delete the entry.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.signup.UseCaseAdminDeletesSignup

Steps

Nr Title Role(s) Next Description

Rest API call

SUPERADMIN

Rest api called to remove user signup

This step is defined at method deleteSignup in class `com.mercedesbenz.sechub.domain.administration.signup.SignupAdministrationRestController`

Persistence

SUPERADMIN

Existing signup will be deleted

This step is defined at method delete in class `com.mercedesbenz.sechub.domain.administration.signup.SignupDeleteService`

REST API documentation for usecase UC_019-Admin deletes user signup

10.10.21. UC_020-Admin deletes a project

Administrator deletes a project from SecHub.

A Project is the main entry point for every SecHub operation and deleting this will result in:

Terminate all running jobs for this project
Remove project administration setup
User to project association
All existing project report results

Albert Tregnaghi, 2018-08-03: This is currently not full implemented!

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminDeleteProject

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Project will be deleted This step is defined at method `deleteProject` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`
2	Service deletes projects.	SUPERADMIN	3, 4, 5, 6, 7	The service will delete the project with dependencies and triggers asynchronous events This step is defined at method `deleteProject` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectDeleteService`
3	Inform sechub admins that project has been deleted		4	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatProjectHasBeenDeletedNotificationService`
4	Inform project owner that the project has been deleted		5	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.owner.InformOwnerThatProjectHasBeenDeletedNotificationService`
5	Inform users that the project has been deleted		6	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.InformUsersThatProjectHasBeenDeletedNotificationService`
6	Update authorization parts - remove entries for deleted project		7	This step is defined at method `deleteAnyAccessDataForProject` in class `com.mercedesbenz.sechub.domain.schedule.access.ScheduleDeleteAllProjectAcessService`
7	revoke any scan access from project		8	This step is defined at method `deleteAnyAccessDataForProject` in class `com.mercedesbenz.sechub.domain.scan.access.ScanDeleteAnyAccessToProjectAtAllService`
8	delete all project scan data			This step is defined at method `deleteAllDataForProject` in class `com.mercedesbenz.sechub.domain.scan.ProjectDataDeleteService`

REST API documentation for usecase UC_020-Admin deletes a project

10.10.22. UC_021-Admin shows project details

An administrator downloads a json file containing json with project details

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminShowsProjectDetails

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Json returned containing details about project

This step is defined at method showProjectDetails in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`

Service fetches project details.

SUPERADMIN

The service will fetch project details

This step is defined at method fetchDetails in class `com.mercedesbenz.sechub.domain.administration.project.ProjectDetailInformationService`

REST API documentation for usecase UC_021-Admin shows project details

10.10.23. UC_022-Update project whitelist

Administrator creates a project inside SecHub.

A Project is the main entry point for every SecHub operation! For example a user must have a project assigned to be able to scan on it!

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseUpdateProjectWhitelist

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

White list will be updated

This step is defined at method updateProjectWhitelist in class `com.mercedesbenz.sechub.domain.administration.project.ProjectUpdateAdministrationRestController`

Update project

SUPERADMIN

The service will update the Project whitelist.

This step is defined at method updateProjectWhitelist in class `com.mercedesbenz.sechub.domain.administration.project.ProjectUpdateWhitelistService`

REST API documentation for usecase UC_022-Update project whitelist

10.10.24. UC_023-Admin lists all running jobs

Administrator lists all running jobs inside SecHub. The list entries do contain

jobUUID
project id
owner of job (id of user who executed job)
status
since time stamp
configuration

These entries are only available at running jobs

This is an important action to get info about current treshold in sechub.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.job.UseCaseAdminListsAllRunningJobs

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator lists all running jobs by calling rest api

This step is defined at method fetchAllRunningJobs in class `com.mercedesbenz.sechub.domain.administration.job.JobAdministrationRestController`

Fetchjob information from database

Fetches stored job information from administration database.

This step is defined at method fetchRunningJobs in class `com.mercedesbenz.sechub.domain.administration.job.JobInformationListService`

REST API documentation for usecase UC_023-Admin lists all running jobs

10.10.25. UC_024-User requests new API token

It shall be possible to achieve this by calling REST API and also by just visiting static sechub website and entering email address and post request by simple web form.

When user exists a new one time token will be created and sent to user per email - so same way as done when a new user signup is accepted by admin.

The user has to open the received email.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.UseCaseUserRequestsNewApiToken

Steps

Nr Title Role(s) Next Description

Rest API call

Rest api called to request new user api token. Normally done by user itself

This step is defined at method anonymousRequestToGetNewApiTokenForUserEmailAddress in class `com.mercedesbenz.sechub.domain.administration.user.AnonymousUserRequestNewApiTokenRestController`

REST API documentation for usecase UC_024-User requests new API token

10.10.26. UC_025-Admin shows scan logs for project

An admin downloads a json file containing log for scans of project

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminShowsScanLogsForProject

Steps

Nr Title Role(s) Next Description

REST API call to get JSON list

SUPERADMIN

This step is defined at method getScanLogsForProject in class `com.mercedesbenz.sechub.domain.scan.log.ScanLogRestController`

REST API documentation for usecase UC_025-Admin shows scan logs for project

10.10.27. UC_026-Admin downloads all details about a scan job

An administrator downloads a ZIP file containing full details of a scan. Main reason for this use case is for debugging when there are problems with security products. Another reason is for developers to adopt new security products easier.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminDownloadsFullScanDataForJob

Steps

Nr Title Role(s) Next Description

REST API call to zip file containing full scan data

SUPERADMIN

This step is defined at method getFullScanZipFileForJob in class `com.mercedesbenz.sechub.domain.scan.admin.FullScanDataRestController`

Collect all scan data

SUPERADMIN

This step is defined at method getFullScanData in class `com.mercedesbenz.sechub.domain.scan.admin.FullScanDataService`

REST API documentation for usecase UC_026-Admin downloads all details about a scan job

10.10.28. UC_027-Admin grants admin rights to user

An administrator grants admin rights to another user. So this user will become also an administrator.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminGrantsAdminRightsToUser

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	User will be granted admin rights This step is defined at method `grantSuperAdminrights` in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`
2	Service grants user admin rights.	SUPERADMIN	3, 4	The service will grant user admin righs and triggers asynchronous events This step is defined at method `grantSuperAdminRightsFor` in class `com.mercedesbenz.sechub.domain.administration.user.UserGrantSuperAdminRightsService`
3	Inform user that he/she became administrator		4	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.InformUserThatUserBecomesAdminNotificationService`
4	Inform SecHub admins that another user became administrator			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatUserBecomesAdminNotificationService`

REST API documentation for usecase UC_027-Admin grants admin rights to user

10.10.29. UC_028-Admin revokes admin rights from an admin

An administrator revokes existing admin rights from another administrator.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminRevokesAdminRightsFromAdmin

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Admin rights will be revoked from admin This step is defined at method `revokeSuperAdminrights` in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`
2	Service revokes user admin rights.	SUPERADMIN	3, 4	The service will revoke user admin righs and triggers asynchronous events This step is defined at method `revokeSuperAdminRightsFrom` in class `com.mercedesbenz.sechub.domain.administration.user.UserRevokeSuperAdminRightsService`
3	Inform user about loosing administrator rights		4	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.InformUserThatUserNoLongerAdminNotificationService`
4	Inform SecHub admins that another admin is no longer admin			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatUserNoLongerAdminNotificationService`

REST API documentation for usecase UC_028-Admin revokes admin rights from an admin

10.10.30. UC_029-Admin lists all admins

An administrator downloads a json file containing all names of SecHub admins

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminListsAllAdmins

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

All userids of sechub administrators are returned as json

This step is defined at method listAdministrators in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`

Service call

SUPERADMIN

All userids of sechub administrators are returned as json

This step is defined at method listAdministrators in class `com.mercedesbenz.sechub.domain.administration.user.UserListService`

REST API documentation for usecase UC_029-Admin lists all admins

10.10.31. UC_030-Admin disables job processing in scheduler

An administrator disables scheduler job processing. This can be a preparation for system wide update - when scheduling is stoped, user can ask for new SecHub Jobs etc. But as long as scheduler is stopped nothing is executed - so JVMs/PODs can be updated in cluster

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.schedule.UseCaseAdminDisablesSchedulerJobProcessing

Event overview

"Overview of events happening at usecase UC_ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

Involved messages

UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING
UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator wants to stop (pause) scheduler job processing This step is defined at method `disableJobProcessing` in class `com.mercedesbenz.sechub.domain.administration.scheduler.SchedulerAdministrationRestController`
2	Service call	SUPERADMIN	2	Sends request to scheduler to send updates about current status. This step is defined at method `triggerSchedulerStatusRefresh` in class `com.mercedesbenz.sechub.domain.administration.scheduler.TriggerSchedulerStatusRefreshService`
2	Service call	SUPERADMIN	3	Sends request to scheduler domain to disable scheduler job processing This step is defined at method `disableJobProcessing` in class `com.mercedesbenz.sechub.domain.administration.scheduler.SwitchSchedulerJobProcessingService`
3	Disable processing		4	Disables job processing inside scheduler database This step is defined at method `disableJobProcessing` in class `com.mercedesbenz.sechub.domain.schedule.config.SchedulerConfigService`
4	Inform SecHub admins that scheduler job processing has been disabled			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatSchedulerJobProcessingHasBeenDisabledService`

REST API documentation for usecase UC_030-Admin disables job processing in scheduler

10.10.32. UC_031-Admin enables scheduler job processing

An administrator starts scheduler job processing. This can be a necessary step after a system wide update where processing of jobs was stoped before.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.schedule.UseCaseAdminEnablesSchedulerJobProcessing

Event overview

"Overview of events happening at usecase UC_ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

Involved messages

UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING
UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator wants to start (unpause) scheduler job processing This step is defined at method `enableJobProcessing` in class `com.mercedesbenz.sechub.domain.administration.scheduler.SchedulerAdministrationRestController`
2	Service call	SUPERADMIN	3	Sends request to scheduler domain to enable scheduler job processing This step is defined at method `enableJobProcessing` in class `com.mercedesbenz.sechub.domain.administration.scheduler.SwitchSchedulerJobProcessingService`
3	Enable processing		4	Enables job processing inside scheduler database This step is defined at method `enableJobProcessing` in class `com.mercedesbenz.sechub.domain.schedule.config.SchedulerConfigService`
4	Inform SecHub admins that scheduler job processing has been enabled			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatSchedulerJobProcessingHasBeenEnabledService`

REST API documentation for usecase UC_031-Admin enables scheduler job processing

10.10.33. UC_032-Admin get scheduler status

An administrator wants to update information about scheduler status

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.schedule.UseCaseAdminTriggersRefreshOfSchedulerStatus

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator wants to trigger a refresh of scheduler status. Will update information about running, waiting and all jobs in scheduler etc. etc.

This step is defined at method triggerRefreshOfSchedulerStatus in class `com.mercedesbenz.sechub.domain.administration.scheduler.SchedulerAdministrationRestController`

REST API documentation for usecase UC_032-Admin get scheduler status

10.10.34. UC_033-Admin lists status information

An administrator fetches current known status information about sechub

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.status.UseCaseAdminListsStatusInformation

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator wants to list status information about sechub

This step is defined at method listStatusInformation in class `com.mercedesbenz.sechub.domain.administration.status.StatusAdministrationRestController`

REST API documentation for usecase UC_033-Admin lists status information

10.10.35. UC_034-Admin cancels a job

Administrator does cancel a job by its Job UUID

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.job.UseCaseAdminCancelsJob

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Triggers job cancellation request, owners of project will be informed This step is defined at method `cancelJob` in class `com.mercedesbenz.sechub.domain.administration.job.JobAdministrationRestController`
2	Cancel job		3	Will trigger event that job cancel requested This step is defined at method `cancelJob` in class `com.mercedesbenz.sechub.domain.administration.job.JobCancelService`
3	Try to find job and mark as being canceled		4	When job is found and user has access the state will be updated and marked as canceled This step is defined at method `cancelJob` in class `com.mercedesbenz.sechub.domain.schedule.SchedulerCancelJobService`
4	Inform user that her/his job has been canceled			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.user.InformUserThatJobHasBeenCanceledService`

REST API documentation for usecase UC_034-Admin cancels a job

10.10.36. UC_035-User defines mock data configuration for project

User retrieves project mockdata - see define project mockdata

SecHub must be started with mocked_products profile activated to fetch this!

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.UseCaseUserDefinesProjectMockdata

Steps

Nr Title Role(s) Next Description

REST API call to define mock configuration byJSON data

SUPERADMIN, USER

This step is defined at method defineProjectMockDataConfiguration in class `com.mercedesbenz.sechub.domain.scan.project.ScanProjectMockDataRestController`

Service call to store mock configuration

This step is defined at method defineProjectMockDataConfiguration in class `com.mercedesbenz.sechub.domain.scan.project.ScanProjectMockDataConfigurationService`

REST API documentation for usecase UC_035-User defines mock data configuration for project

10.10.37. UC_036-User retrieves mock data configuration for project

When other systems integrate sechub into their live cylce (this means not a build server integration, but an integration from another product…) they also want to integrate into their integration tests as well - so a special environment is necessary an INT environment.

When using commercial security products it can happen that integration tests will lead to additional license costs. To prevent this the INT environment can be setup to use mocked adapters. These adapters will not communicate with the real security products but instead return mocked product results. All logic, every behaviour inside SecHub is exactly the same except the communication with the security product. This technique is used by SecHub for integration testing itself.

SecHub must be started with mocked_products profile activated to have this enabled!

Tests/Testers have the possibility to setup wanted traffic-light result on their SecHub projects by REST API.

green will contain only green results,
yellow shall contain green and yellow results and
red will contain green, yellow and red ones.

Example mock configuration for web-,infra- and code-scans

{
  "codeScan" : {
    "result" : "RED"
  },
  "webScan" : {
    "result" : "YELLOW"
  },
  "infraScan" : {
    "result" : "GREEN"
  }
}

Of course you can reduce mock to wanted parts only:

Example mock configuration for code scan only

{
  "codeScan" : {
    "result" : "YELLOW"
  }
}

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.UseCaseUserRetrievesProjectMockdata

Steps

Nr Title Role(s) Next Description

REST API call to get JSON data

SUPERADMIN, USER

This step is defined at method retrieveProjectMockDataConfiguration in class `com.mercedesbenz.sechub.domain.scan.project.ScanProjectMockDataRestController`

Service call to get JSON data

This step is defined at method retrieveProjectMockDataConfiguration in class `com.mercedesbenz.sechub.domain.scan.project.ScanProjectMockDataConfigurationService`

REST API documentation for usecase UC_036-User retrieves mock data configuration for project

10.10.38. UC_037-Admin updates mapping configuration

An administrator changes mapping configuration. Mappings represents a generic mechanism to replace a given string, matched by configured regular expression pattern with a replacement string. Some of the mappings are used for adapter behaviour.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdmiUpdatesMappingConfiguration

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator wants to update a mapping configuration This step is defined at method `updateMapping` in class `com.mercedesbenz.sechub.domain.administration.mapping.MappingAdministrationRestController`
2	Service call		3	Services updates data in database and sends event This step is defined at method `updateMapping` in class `com.mercedesbenz.sechub.domain.administration.mapping.UpdateMappingService`
3	Event handler		4	Receives mapping configuration change event This step is defined at method `handleMappingConfigurationChanged` in class `com.mercedesbenz.sechub.domain.scan.ScanMessageHandler`
4	Service call		5	Updates scan mapping in DB This step is defined at method `updateScanMapping` in class `com.mercedesbenz.sechub.domain.scan.config.UpdateScanMappingConfigurationService`
5	Trigger service		6	Checks periodically for updates in scan configuration This step is defined at method `triggerRefreshCheck` in class `com.mercedesbenz.sechub.domain.scan.config.ScanMappingConfigurationRefreshTriggerService`
6	Service call			Checks if current mappings in DB lead to a new scan configuration. This step is defined at method `refreshScanConfigIfNecessary` in class `com.mercedesbenz.sechub.domain.scan.config.ScanMappingConfigurationService`

REST API documentation for usecase UC_037-Admin updates mapping configuration

10.10.39. UC_038-Admin fetches mapping configuration

An administrator fetches mapping configuration by its ID.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminFetchesMappingConfiguration

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator wants to fetch a mapping configuration

This step is defined at method fetchMappingData in class `com.mercedesbenz.sechub.domain.administration.mapping.MappingAdministrationRestController`

Service call

Services fetches data from database, if not set an empty mapping data result will be returned

This step is defined at method fetchMappingData in class `com.mercedesbenz.sechub.domain.administration.mapping.FetchMappingService`

REST API documentation for usecase UC_038-Admin fetches mapping configuration

10.10.40. UC_039-Check if the server is alive and running.

An anonymous user or system wants to know if the server is alive and running.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.anonymous.UseCaseAnonymousCheckAlive

Steps

Nr Title Role(s) Next Description

REST API call

An anonymous user checks if the server is alive and running using the REST API

This step is defined at method checkAlive in class `com.mercedesbenz.sechub.server.core.AnonymousCheckAliveRestController`

REST API documentation for usecase UC_039-Check if the server is alive and running.

10.10.41. UC_040-Admin fetches server runtime data

An administrator fetches the current SecHub server runtime data. Only administrators are allowed to do this because it contains the server version and knowing the exact server version makes it easier for penetration tester or attacker to attack the system.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.status.UseCaseAdminFetchesServerRuntimeData

Steps

Nr Title Role(s) Next Description

REST API Call

SUPERADMIN

Administrator wants to fetch server runtime data. This data contains for example the server version

This step is defined at method getServerRuntimeData in class `com.mercedesbenz.sechub.server.core.ServerInfoAdministrationRestController`

REST API documentation for usecase UC_040-Admin fetches server runtime data

10.10.42. UC_041-Admin restarts a job

Administrator restarts job

When a JVM (or POD) crashes with running SecHub job, the job process execution has been terminated without resetting the scheduler state.

If this has happened, somebody or a build server who/which is waiting for sechub job result will wait infinite and without hope of having a status refresh.

So the admin must be able to restart a job.

The restart will be intransparent for end user so they will just keep on waiting but get the result as soon as possible.

The restart will

first of all write an audit log enry
be canceled, when job does not exist in scheduler
be canceled, when execution already finished
check for running batch jobs with SecHub job UUID.
If there are existing batch operations, those will be stopped
new scan will be restarted immediately without scheduling, will try to reuse existing results
E.g. when a static code scan job is triggered to a product and scan ID is wellknown, no new scan will be started, but state of this scan is refetched by the ID, etc. etc. But exact resilience behaviour depends on adapter implementation

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.job.UseCaseAdminRestartsJob

Event overview - variant: accidently restart because job has already finished

"Overview of events happening at usecase UC_ADMIN_RESTARTS_JOB - variant: accidently restart because job has already finished

Event overview - variant: crashed jvm with product result

"Overview of events happening at usecase UC_ADMIN_RESTARTS_JOB - variant: crashed jvm with product result

Involved messages

UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB
UC_041-ADMIN_RESTARTS_JOB

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Triggeres job restart (soft) This step is defined at method `restartJob` in class `com.mercedesbenz.sechub.domain.administration.job.JobAdministrationRestController`
2	Restart job		3	Will trigger event that job restart (soft) requested This step is defined at method `restartJob` in class `com.mercedesbenz.sechub.domain.administration.job.JobRestartRequestService`
3	Inform sechub admins when job restart was canceled		4	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatJobRestartWasCanceledService`
4	Inform sechub admins when job has been restarted		5	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatJobRestartHasBeenTriggeredService`
5	Inform sechub admins when job results have been purged			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatJobResultsHaveBeenPurgedService`

REST API documentation for usecase UC_041-Admin restarts a job

10.10.43. UC_042-Admin restarts a job (hard)

Administrator restarts job the hard way , means it is possible to restart a running (not finished) job and destroy all former results.

It is very similar to related use case admin restarts job, but with difference that all former product results and also adapter meta data is removed.

We do NOT allow restarts of former finished jobs because finalization does destroy interim data - e.g. uploaded source code etc. - and is no longer restartable. Also we cannot ensure that a client has not already downloaded the existing results, so we we keep them as is!

The term "hard" is only because we destroy former meta data and product results! So the restart is like from "scratch".

The restart will

first of all write an audit log enry
be canceled, when job does not exist in scheduler
be canceled, when execution already finished
delete all former product results and also adapter meta data
check for running batch jobs with SecHub job UUID.
If there are existing batch operations, those will be stopped
new scan will be restarted immediately without scheduling, will not try to reuse existing results because such information was formerly deleted

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.job.UseCaseAdminRestartsJobHard

Event overview - variant: accidently restart because job has already finished

"Overview of events happening at usecase UC_ADMIN_RESTARTS_JOB_HARD - variant: accidently restart because job has already finished

Event overview - variant: crashed jvm with product result

"Overview of events happening at usecase UC_ADMIN_RESTARTS_JOB_HARD - variant: crashed jvm with product result

Event overview

"Overview of events happening at usecase UC_ADMIN_RESTARTS_JOB_HARD

Involved messages

UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD
UC_042-ADMIN_RESTARTS_JOB_HARD

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Triggeres job restart (hard) This step is defined at method `restartJobHard` in class `com.mercedesbenz.sechub.domain.administration.job.JobAdministrationRestController`
2	Restart job		3	Will trigger event that job restart (hard) requested This step is defined at method `restartJobHard` in class `com.mercedesbenz.sechub.domain.administration.job.JobRestartRequestService`
3	Inform sechub admins when job restart was canceled		3	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatJobRestartWasCanceledService`
3	Try to restart job		3	When job is found and job is not already finsihed, a restart will be triggered. Existing batch jobs will be terminated This step is defined at method `restartJob` in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestartJobService`
3	Try to rstart job (hard)		4	When job is found, a restart will be triggered. Existing batch jobs will be terminated This step is defined at method `restartJobHard` in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestartJobService`
4	Inform sechub admins when job has been restarted		5	This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatJobRestartHasBeenTriggeredService`
5	Inform sechub admins when job results have been purged			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatJobResultsHaveBeenPurgedService`

REST API documentation for usecase UC_042-Admin restarts a job (hard)

10.10.44. UC_043-Admin receives notification about start of a new scheduler instance

Administrators receive notification about start of a new scheduler instance.

The notification will contain also information about potential zombie jobs - just show all started but not finished jobs before scheduler start.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.status.UseCaseAdminReceivesNotificationAboutNewchedulerInstanceStart

Steps

Nr	Title	Role(s)	Next	Description
1	send domain message that new scheduler instance has been started and information about potential zombie jobs		2	This step is defined at method `schedulerHasBeenStarted` in class `com.mercedesbenz.sechub.domain.schedule.SchedulerStartHandler`
2	Inform sechub admins that new scheduler job has been started			This step is defined at method `notify` in class `com.mercedesbenz.sechub.domain.notification.superadmin.InformAdminsThatNewSchedulerInstanceHasBeenStarted`

10.10.45. UC_044-User marks false positives for finished sechub job

A user wants to mark false positives for a finished job. This means the job has been executed, has finished without failure and job is NOT deleted.

The user will be able to mark former job results by their given id as false positives.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserMarksFalsePositivesForJob

Steps

Nr Title Role(s) Next Description

REST API call to define false positives by JSON data containing identifiers for existing job

SUPERADMIN, USER

This step is defined at method addFalsePositivesByJobData in class `com.mercedesbenz.sechub.domain.scan.project.FalsePositiveRestController`

REST API documentation for usecase UC_044-User marks false positives for finished sechub job

10.10.46. UC_045-User unmarks existing false positive definitons

A user wants to unmark existing false positives This means the false positives has been marked before.

This will NOT change any former job report where the false positive to unmark has been filtered!

After next scan job the former false positive is no longer filtering the finding.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserUnmarksFalsePositives

Steps

Nr Title Role(s) Next Description

REST API call to remove existing false positive definition

SUPERADMIN, USER

This step is defined at method removeFalsePositiveFromProjectByJobUUIDAndFindingId in class `com.mercedesbenz.sechub.domain.scan.project.FalsePositiveRestController`

REST API documentation for usecase UC_045-User unmarks existing false positive definitons

10.10.47. UC_046-User fetches false positive configuration of project

A user wants to fetch false positive configuration of project.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserFetchesFalsePositiveConfigurationOfProject

Steps

Nr Title Role(s) Next Description

REST API call to fetch existing false positive configuration of project

SUPERADMIN, USER

This step is defined at method fetchFalsePositivesProjectConfiguration in class `com.mercedesbenz.sechub.domain.scan.project.FalsePositiveRestController`

REST API documentation for usecase UC_046-User fetches false positive configuration of project

10.10.48. UC_047-Admin creates an executor configuration

An administrator creates an executor a new configuration entry.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminCreatesExecutorConfiguration

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator adds a new product executor configuration by calling REST API

This step is defined at method addProductExecutorConfig in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutorConfigRestController`

Service call

SUPERADMIN

Service creates a new product executor configuration

This step is defined at method createProductExecutorConfig in class `com.mercedesbenz.sechub.domain.scan.product.config.CreateProductExecutorConfigService`

REST API documentation for usecase UC_047-Admin creates an executor configuration

10.10.49. UC_048-Admin deletes executor configuration

An administrator deletes an executor by removing the configuration entry identified by its uuid

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminDeletesExecutorConfiguration

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator deletes an existing product executor configuration by calling REST API

This step is defined at method removeProductExecutorConfig in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutorConfigRestController`

Service call

SUPERADMIN

Service deletes an existing product executor configuration by its UUID

This step is defined at method deleteProductExecutorConfig in class `com.mercedesbenz.sechub.domain.scan.product.config.DeleteProductExecutorConfigService`

REST API documentation for usecase UC_048-Admin deletes executor configuration

10.10.50. UC_049-Admin fetches executor configuration list

An administrator fetches executor configuration list which contains all executor configurations

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminFetchesExecutorConfigurationList

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator fetches lsit of existing product executor configurations by calling REST API, will not contain setup information

This step is defined at method fechProductExecutorConfiguraitonsAsList in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutorConfigRestController`

Service call

SUPERADMIN

Service fetches data and creates a list containing all executor configurations

This step is defined at method fetchProductExecutorConfigList in class `com.mercedesbenz.sechub.domain.scan.product.config.FetchProductExecutorConfigListService`

REST API documentation for usecase UC_049-Admin fetches executor configuration list

10.10.51. UC_050-Admin fetches executor configuration

An administrator fetches one explicit executor configuration by its uuid.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminFetchesExecutorConfiguration

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator fetches setup of an existing product executor configuration by calling REST API

This step is defined at method fechProductExecutorConfigSetup in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutorConfigRestController`

Service call

SUPERADMIN

Service reads setup information for an existing product executor configuration

This step is defined at method fetchProductExecutorConfig in class `com.mercedesbenz.sechub.domain.scan.product.config.FetchProductExecutorConfigService`

REST API documentation for usecase UC_050-Admin fetches executor configuration

10.10.52. UC_051-Admin updates executor configuration setup

An administrator updateds dedicated executor configuration. The update does change description, enabled state and also used executors, but Will NOT change any associations between profile and projects.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminUpdatesExecutorConfig

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator updates setup for an existing product executor configuration by calling REST API

This step is defined at method updateProductExecutorConfigSetup in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutorConfigRestController`

Service call

SUPERADMIN

Service updates existing executor configuration

This step is defined at method updateExecutionProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.UpdateProductExecutionProfileService`

Service call

SUPERADMIN

Service updates existing executor configuration

This step is defined at method updateProductExecutorSetup in class `com.mercedesbenz.sechub.domain.scan.product.config.UpdateProductExecutorConfigService`

REST API documentation for usecase UC_051-Admin updates executor configuration setup

10.10.53. UC_052-Admin creates an execution profile

An administrator creates an execution profile

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminCreatesExecutionProfile

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator adds a new product execution profile by calling REST API

This step is defined at method createProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

Service call

SUPERADMIN

Service creates a new product executor configuration

This step is defined at method createProductExecutionProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.CreateProductExecutionProfileService`

REST API documentation for usecase UC_052-Admin creates an execution profile

10.10.54. UC_053-Admin deletes execution profile

An administrator deletes execution profile

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminDeletesExecutionProfile

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator deletes an existing product execution profile by calling REST API

This step is defined at method deleteProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

Service call

SUPERADMIN

Service deletes an existing product execution profile by its profile id

This step is defined at method deleteProductExecutionProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.DeleteProductExecutionProfileService`

REST API documentation for usecase UC_053-Admin deletes execution profile

10.10.55. UC_054-Admin updates execution profile

An administrator updateds dedicated execution profile

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminUpdatesExecutionProfile

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator updates existing profile by calling REST API

This step is defined at method udpateProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

REST API documentation for usecase UC_054-Admin updates execution profile

10.10.56. UC_055-Admin fetches execution profile

An administrator fetches details about an execution profile

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminFetchesExecutionProfile

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator fetches setup of an existing product executor configuration by calling REST API

This step is defined at method fechProductExecutorConfigSetup in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

Service call

SUPERADMIN

Service reads setup information for an existing product executor configuration

This step is defined at method fetchProductExecutorConfig in class `com.mercedesbenz.sechub.domain.scan.product.config.FetchProductExecutionProfileService`

REST API documentation for usecase UC_055-Admin fetches execution profile

10.10.57. UC_056-Admin fetches execution profile list

An administrator fetches execution profile list

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminFetchesExecutionProfileList

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator fetches lsit of all available execution profiles by calling REST API

This step is defined at method fetchProfileList in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

Service call

SUPERADMIN

Service fetches data and creates a list containing all executor profiles

This step is defined at method fetchProductExecutionProfileList in class `com.mercedesbenz.sechub.domain.scan.product.config.FetchProductExecutionProfileListService`

REST API documentation for usecase UC_056-Admin fetches execution profile list

10.10.58. UC_057-Admin assigns execution profile to project

An administrator assigns an execution profile to an existing project

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminAssignsExecutionProfileToProject

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator adds profile relation to project by calling REST API

This step is defined at method addProjectToProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

Service call

SUPERADMIN

Services creates a new association between project id and profile

This step is defined at method addProjectToProfileRelation in class `com.mercedesbenz.sechub.domain.scan.product.config.UpdateProductExecutionProfileService`

REST API documentation for usecase UC_057-Admin assigns execution profile to project

10.10.59. UC_058-Admin unassigns execution profile from project

An administrator unassigns an execution profile from a projects.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminUnassignsExecutionProfileFromProject

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator removes profile relation to project by calling REST API

This step is defined at method removeProjectFromProfile in class `com.mercedesbenz.sechub.domain.scan.product.config.ProductExecutionProfileRestController`

Service call

SUPERADMIN

Services deletes an existing association between project id and profile

This step is defined at method removeProjectToProfileRelation in class `com.mercedesbenz.sechub.domain.scan.product.config.UpdateProductExecutionProfileService`

REST API documentation for usecase UC_058-Admin unassigns execution profile from project

10.10.60. UC_059-Update project metadata

Administrator updates project meta data inside SecHub.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseUpdateProjectMetaData

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

MetaData will be updated

This step is defined at method updateProjectMetaData in class `com.mercedesbenz.sechub.domain.administration.project.ProjectUpdateAdministrationRestController`

Update project

SUPERADMIN

The service will update the Project metadata.

This step is defined at method updateProjectMetaData in class `com.mercedesbenz.sechub.domain.administration.project.ProjectUpdateMetaDataEntityService`

REST API documentation for usecase UC_059-Update project metadata

10.10.61. UC_060-Admin changes owner of a project

An administrator changes the owner of an existing sechub project.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminChangesProjectOwner

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator does call rest API to set new project owner

This step is defined at method changeProjectOwner in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`

Change project owner

SUPERADMIN

The service will set the user as the owner of the project. If user does not have ROLE_OWNER it will obtain it. The old owner will loose project ownership.

This step is defined at method changeProjectOwner in class `com.mercedesbenz.sechub.domain.administration.project.ProjectChangeOwnerService`

Inform new and previous project owners that the project owner ship has changed

This step is defined at method notify in class `com.mercedesbenz.sechub.domain.notification.owner.InformThatProjectHasNewOwnerNotificationService`

REST API documentation for usecase UC_060-Admin changes owner of a project

10.10.62. UC_061-Admin changes project description

An administrator changes the project description

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdminChangesProjectDescription

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Changes project description. Json returned containing details about changed project

This step is defined at method changeProjectDescription in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`

Service changes project description.

SUPERADMIN

The service will change project description.

This step is defined at method changeProjectDescription in class `com.mercedesbenz.sechub.domain.administration.project.ProjectDetailChangeService`

REST API documentation for usecase UC_061-Admin changes project description

10.10.63. UC_062-Admin changes project access level

An administrator is able to change the access level of a project.

Project access levels do constraint possible user operations for a project - e.g. restrict to read only operations. The details of different restrictions are described below.

A project access level none will make it also for administrators impossible to fetch reports from the project. Only special administrator REST API calls are not restricted.

10.10.63.1. Levels

full
no restrictions
read_only
users can download their reports, get job status, but cannot trigger any project jobs
none
users have no access to reports, jobs and cannot trigger any jobs for the project

10.10.63.2. Conststraints

10.10.63.2.1. Full

When a project has access level full any read or write user operation is possible:

a new scan can be triggered, so user can
- create job
- approve job
- upload job data
scheduling is active for the project new jobs are processed
user can check status for a job in their project
user can download their former reports

10.10.63.2.2. Read only

When a project has access level read_only only read user operations are possible:

a new scan is not possible, HTTP 403: Forbidden will be sent for
- create job
- approve job
- upload job data
running jobs are still running
already scheduled jobs will be scheduled
user are still able to check status for a job in their project
user can still download their former reports

10.10.63.2.3. None

When a project has access level none no user operation is possible:

a new scan is not possible, HTTP 403: Forbidden will be sent for
- create job
- approve job
- upload job data
running jobs are still running
already scheduled jobs will be scheduled
user are NOT able to check status for a job in their project, HTTP 403: Forbidden will be sent
user can NOT download their former reports, HTTP 403: Forbidden will be sent

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.project.UseCaseAdministratorChangesProjectAccessLevel

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Admin does call REST API to change project access level This step is defined at method `changeProjectAccessLevel` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectAdministrationRestController`
2	Change access level	SUPERADMIN	3	The service will change the project access level inside administration domain and trigger a change event to inform recipients about the new situation. This step is defined at method `changeProjectAccessLevel` in class `com.mercedesbenz.sechub.domain.administration.project.ProjectChangeAccessLevelService`
3	Event handler		4	Receives change project access level event This step is defined at method `handleProcessAccessLevelChanged` in class `com.mercedesbenz.sechub.domain.scan.ScanMessageHandler`
4	Event handler			Receives change project access level event This step is defined at method `handleProcessAccessLevelChanged` in class `com.mercedesbenz.sechub.domain.schedule.ScheduleMessageHandler`

REST API documentation for usecase UC_062-Admin changes project access level

10.10.64. UC_063-Admin updates user email address

An administrator update the email address of an user. After the change an email will be sent to the old email-address to inform the user about the change. In addition, a new mail to the new email address will be sent as well.

When the new email address is the same as before, the action will be rejected.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminUpdatesUserEmailAddress

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

User emaill address will be changed

This step is defined at method updateUserEmailAdderss in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`

Service updates user email address.

SUPERADMIN

The service will update the user email address and also trigger events.

This step is defined at method updateUserEmailAddress in class `com.mercedesbenz.sechub.domain.administration.user.UserEmailAddressUpdateService`

Inform user that the email address has been changed

This step is defined at method notify in class `com.mercedesbenz.sechub.domain.notification.user.UserEmailAddressChangedNotificationService`

REST API documentation for usecase UC_063-Admin updates user email address

10.10.65. UC_064-Admin fetches auto cleanup configuration

An administrator feches current auto cleanup configuration.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminFetchesAutoCleanupConfiguration

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Administrator fetches auto cleanup configuration

This step is defined at method fetchAutoCleanupConfiguration in class `com.mercedesbenz.sechub.domain.administration.config.ConfigAdministrationRestController`

Fetches auto cleanup config

Fetches auto cleanup configuration from database

This step is defined at method fetchAutoCleanupConfiguration in class `com.mercedesbenz.sechub.domain.administration.config.AdministrationConfigService`

REST API documentation for usecase UC_064-Admin fetches auto cleanup configuration

10.10.66. UC_065-Admin updates auto cleanup configuration

An administrator changes auto cleanup configuration.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.config.UseCaseAdminUpdatesAutoCleanupConfiguration

Event overview

"Overview of events happening at usecase UC_ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

Involved messages

UC_065-ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator changes auto cleanup configuration This step is defined at method `updateAutoCleanupConfiguration` in class `com.mercedesbenz.sechub.domain.administration.config.ConfigAdministrationRestController`
2	Updates auto cleanup config		3, 4, 5	Updates auto cleanup configuration as JSON in database and sends event This step is defined at method `updateAutoCleanupConfiguration` in class `com.mercedesbenz.sechub.domain.administration.config.AdministrationConfigService`
3	Administration domain receives auto cleanup event		4	Received event in administration domain about auto cleanup configuration change. Stores data, so available for next auto clean execution This step is defined at method `updateAutoCleanupInDays` in class `com.mercedesbenz.sechub.domain.administration.config.AdministrationConfigService`
4	Schedule domain receives auto cleanup event		5	Received event in schedule domain about auto cleanup configuration change. Stores data, so available for next auto clean execution This step is defined at method `updateAutoCleanupInDays` in class `com.mercedesbenz.sechub.domain.schedule.config.SchedulerConfigService`
5	Scan domain receives auto cleanup event			Received event in scan domain about auto cleanup configuration change. Stores data, so available for next auto clean execution This step is defined at method `updateAutoCleanupInDays` in class `com.mercedesbenz.sechub.domain.scan.config.ScanConfigService`

REST API documentation for usecase UC_065-Admin updates auto cleanup configuration

10.10.67. UC_066-Sechub administration domain auto cleanup

The administration domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.autocleanup.UseCaseAdministrationAutoCleanExecution

Steps

Nr Title Role(s) Next Description

Scheduling

Checks for parts to auto clean.

This step is defined at method triggerAutoCleanup in class `com.mercedesbenz.sechub.domain.administration.autocleanup.AdministrationAutoCleanupTriggerService`

Delete old data

deletes old job information

This step is defined at method cleanup in class `com.mercedesbenz.sechub.domain.administration.autocleanup.AdministrationAutoCleanupService`

10.10.68. UC_067-Sechub scan domain auto cleanup

The scan domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.autocleanup.UseCaseScanAutoCleanExecution

Steps

Nr Title Role(s) Next Description

Scheduling

Checks for parts to auto clean.

This step is defined at method triggerAutoCleanup in class `com.mercedesbenz.sechub.domain.scan.autocleanup.ScanAutoCleanupTriggerService`

Delete old data

deletes old job information

This step is defined at method cleanup in class `com.mercedesbenz.sechub.domain.scan.autocleanup.ScanAutoCleanupService`

10.10.69. UC_068-Sechub schedule domain auto cleanup

The schedule domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.autocleanup.UseCaseScheduleAutoCleanExecution

Steps

Nr Title Role(s) Next Description

Scheduling

Checks for parts to auto clean.

This step is defined at method triggerAutoCleanup in class `com.mercedesbenz.sechub.domain.schedule.autocleanup.ScheduleAutoCleanupTriggerService`

Delete old data

deletes old job information

This step is defined at method cleanup in class `com.mercedesbenz.sechub.domain.schedule.autocleanup.ScheduleAutoCleanupService`

10.10.70. UC_069-User uploads binaries

A user wants to upload binearies for a former created sechub job.

The binaries must be inside a valid tar file.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserUploadsBinaries

Steps

Nr Title Role(s) Next Description

Authenticated REST call

SUPERADMIN, USER

This step is defined at method uploadBinaries in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

Try to find project and upload binaries as tar

USER

When project is found and user has access and job is initializing the binaries file will be uploaded

This step is defined at method uploadBinaries in class `com.mercedesbenz.sechub.domain.schedule.SchedulerBinariesUploadService`

REST API documentation for usecase UC_069-User uploads binaries

10.10.71. UC_070-User downloads job report in SPDX format

A user wants to download a SPDX report for a finished SecHub job using the job UUID.

Only SPDX JSON is supported.

In case, there is no SPDX JSON result for a given job an error will be thrown.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.user.execute.UseCaseUserDownloadsSpdxJobReport

Steps

Nr Title Role(s) Next Description

REST API call to get SPDX JSON report

SUPERADMIN, USER

This step is defined at method getScanSecHubReportAsSpdxJson in class `com.mercedesbenz.sechub.domain.scan.report.ScanReportRestController`

REST API documentation for usecase UC_070-User downloads job report in SPDX format

10.10.72. UC_071-User lists jobs for project

User fetches a list containing information about jobs of a SecHub project. Per default only the last created job is returned, but it is possible to define a limit and fetch more than one. In this case the returned entries are ordered by creation date.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.job.UseCaseUserListsJobsForProject

Steps

Nr Title Role(s) Next Description

get pageable list of jobs in project

SUPERADMIN, USER

This step is defined at method listJobsForProject in class `com.mercedesbenz.sechub.domain.schedule.SchedulerRestController`

Assert access by service and fetch job information for user

This step is defined at method listJobsForProject in class `com.mercedesbenz.sechub.domain.schedule.job.SecHubJobInfoForUserService`

REST API documentation for usecase UC_071-User lists jobs for project

10.10.73. UC_072-Admin shows user details for email address

An administrator fetches user details for an email address.

Technical information

You will find relevant code parts by searching for references of @com.mercedesbenz.sechub.sharedkernel.usecases.admin.user.UseCaseAdminShowsUserDetailsForEmailAddress

Steps

Nr Title Role(s) Next Description

Rest call

SUPERADMIN

Json returned containing details about user and her/his projects

This step is defined at method showUserDetailsForEmailAddress in class `com.mercedesbenz.sechub.domain.administration.user.UserAdministrationRestController`

Service fetches user details.

SUPERADMIN

The service will fetch user details for given user email address

This step is defined at method fetchDetailsByEmailAddress in class `com.mercedesbenz.sechub.domain.administration.user.UserDetailInformationService`

REST API documentation for usecase UC_072-Admin shows user details for email address

11. API

11.1. Rest API documentation

The complete documentation about REST API is generated. If you want to change content, please search for @UseCaseRestDoc references in source code and make necessary changes inside code!

11.1.1. Overview

11.1.1.1. Anonymous

All these usecases handling anonymous access.

REST API for UC_039-Check if the server is alive and running.

11.1.1.2. User administration

Usecases handling administration of users

REST API for UC_004-Admin lists all users
REST API for UC_015-Admin assigns user to project
REST API for UC_016-Admin unassigns user from project
REST API for UC_017-Admin shows user details
REST API for UC_018-Admin deletes a user
REST API for UC_021-Admin shows project details
REST API for UC_026-Admin downloads all details about a scan job
REST API for UC_027-Admin grants admin rights to user
REST API for UC_028-Admin revokes admin rights from an admin
REST API for UC_029-Admin lists all admins
REST API for UC_060-Admin changes owner of a project
REST API for UC_063-Admin updates user email address
REST API for UC_072-Admin shows user details for email address

11.1.1.3. Project administration

Usecases for project administration

REST API for UC_013-Admin creates a project
REST API for UC_014-Admin lists all projects
REST API for UC_016-Admin unassigns user from project
REST API for UC_020-Admin deletes a project
REST API for UC_022-Update project whitelist
REST API for UC_025-Admin shows scan logs for project
REST API for UC_059-Update project metadata
REST API for UC_061-Admin changes project description
REST API for UC_062-Admin changes project access level

11.1.1.4. User profile

User actions belonging to their profiles

REST API for UC_012-User clicks link to get new api token

11.1.1.5. Sechub execution

Execution of SecHub -either by CLI or direct with REST api call

REST API for UC_005-User creates a new sechub job
REST API for UC_006-User uploads source code
REST API for UC_007-User approves sechub job
REST API for UC_009-User checks sechub job state
REST API for UC_010-User downloads sechub job report
REST API for UC_044-User marks false positives for finished sechub job
REST API for UC_045-User unmarks existing false positive definitons
REST API for UC_046-User fetches false positive configuration of project
REST API for UC_069-User uploads binaries
REST API for UC_070-User downloads job report in SPDX format

All these usecases are handling user sign up (part of user self registration process)

REST API for UC_001-User self registration
REST API for UC_002-Admin lists open user signups
REST API for UC_003-Admin applies self registration
REST API for UC_019-Admin deletes user signup
REST API for UC_024-User requests new API token

11.1.1.7. Job administration

Usecases about job administration

REST API for UC_023-Admin lists all running jobs
REST API for UC_034-Admin cancels a job
REST API for UC_041-Admin restarts a job
REST API for UC_042-Admin restarts a job (hard)

11.1.1.8. Testing

Some use cases for testing

REST API for UC_035-User defines mock data configuration for project
REST API for UC_036-User retrieves mock data configuration for project

11.1.1.9. Configuration

Usecases for configuration parts

REST API for UC_037-Admin updates mapping configuration
REST API for UC_038-Admin fetches mapping configuration
REST API for UC_047-Admin creates an executor configuration
REST API for UC_048-Admin deletes executor configuration
REST API for UC_049-Admin fetches executor configuration list
REST API for UC_050-Admin fetches executor configuration
REST API for UC_051-Admin updates executor configuration setup
REST API for UC_052-Admin creates an execution profile
REST API for UC_053-Admin deletes execution profile
REST API for UC_054-Admin updates execution profile
REST API for UC_055-Admin fetches execution profile
REST API for UC_056-Admin fetches execution profile list
REST API for UC_057-Admin assigns execution profile to project
REST API for UC_058-Admin unassigns execution profile from project
REST API for UC_064-Admin fetches auto cleanup configuration
REST API for UC_065-Admin updates auto cleanup configuration

11.1.1.10. Other

All other use cases

REST API for UC_030-Admin disables job processing in scheduler
REST API for UC_031-Admin enables scheduler job processing
REST API for UC_032-Admin get scheduler status
REST API for UC_033-Admin lists status information
REST API for UC_040-Admin fetches server runtime data
REST API for UC_071-User lists jobs for project

11.1.2. Check if the server is alive and running.

REST API for usecase UC_039-Check if the server is alive and running.

11.1.2.1. HEAD variant

Definition

Table 27. General request information
	Value
Path	/api/anonymous/check/alive
Method	HEAD
Status code	200 OK

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/check/alive' -i -X HEAD

Response body
(empty)

11.1.2.2. GET variant

Definition

Table 28. General request information
	Value
Path	/api/anonymous/check/alive
Method	GET
Status code	200 OK

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/check/alive' -i -X GET

Response body
(empty)

11.1.3. Admin lists all users

REST API for usecase UC_004-Admin lists all users

Definition

Table 29. General request information
	Value
Path	/api/admin/users
Method	GET
Status code	200 OK

Response fields

Path Type Description

[]

Array

List of user Ids

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/users' -i -u 'user:secret' -X GET

Response body

["user1","user2","admin1"]

11.1.4. Admin assigns user to project

REST API for usecase UC_015-Admin assigns user to project

Definition

Table 30. General request information
	Value
Path	/api/admin/project/{projectId}/membership/{userId}
Method	POST
Status code	200 OK

Path parameters

Table 31. https://localhost:8081/api/admin/project/{projectId}/membership/{userId}
Parameter	Description
`projectId`	The id for project
`userId`	The user id of the user to assign to project

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/membership/userId1' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.5. Admin unassigns user from project

REST API for usecase UC_016-Admin unassigns user from project

Definition

Table 32. General request information
	Value
Path	/api/admin/project/{projectId}/membership/{userId}
Method	DELETE
Status code	200 OK

Path parameters

Table 33. https://localhost:8081/api/admin/project/{projectId}/membership/{userId}
Parameter	Description
`projectId`	The id for project
`userId`	The user id of the user to unassign from project

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/userId1/membership/projectId1' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.6. Admin shows user details

REST API for usecase UC_017-Admin shows user details

Definition

Table 34. General request information
	Value
Path	/api/admin/user/{userId}
Method	GET
Status code	200 OK

Path parameters

Table 35. https://localhost:8081/api/admin/user/{userId}
Parameter	Description
`userId`	The user id of user to show details for

Request headers

Name

Description

Response fields

Path Type Description

userId

String

The name of the user

email

String

The email address of the user

superAdmin

Boolean

True, when this user is a super administrator

projects

Array

The projects the user has access to

ownedProjects

Array

The projects the user is owner of

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/user/user1' -i -u 'user:secret' -X GET

Response body

{"userId":"user1","email":"user1@example.org","superAdmin":false,"projects":["project1"],"ownedProjects":[]}

11.1.7. Admin deletes a user

REST API for usecase UC_018-Admin deletes a user

Definition

Table 36. General request information
	Value
Path	/api/admin/user/{userId}
Method	DELETE
Status code	200 OK

Path parameters

Table 37. https://localhost:8081/api/admin/user/{userId}
Parameter	Description
`userId`	The userId of the user who shall be deleted

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/user/USER_ID' -i -u 'user:secret' -X DELETE

Response body
(empty)

11.1.8. Admin shows project details

REST API for usecase UC_021-Admin shows project details

Definition

Table 38. General request information
	Value
Path	/api/admin/project/{projectId}
Method	GET
Status code	200 OK

Path parameters

Table 39. https://localhost:8081/api/admin/project/{projectId}
Parameter	Description
`projectId`	The id for project to show details for

Request headers

Name

Description

Response fields

Path Type Description

projectId

String

The name of the project

users

Array

A list of all users having access to the project

owner

String

Username of the owner of this project. An owner is the person in charge.

whiteList

Array

A list of all whitelisted URIs. Only these ones can be scanned for the project!

metaData

Object

An JSON object containing metadata key-value pairs defined for this project.

metaData.key1

String

An arbitrary metadata key

accessLevel

String

The project access level

description

String

The project description.

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"projectId":"projectId1","users":["name1","name2"],"metaData":{"key1":"value1"},"owner":"name1","description":"description","accessLevel":"full","whiteList":["http://www.sechub.example.org","http://www.sechub.example.com"]}

11.1.9. Admin downloads all details about a scan job

REST API for usecase UC_026-Admin downloads all details about a scan job

Definition

Table 40. General request information
	Value
Path	/api/admin/scan/download/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 41. https://localhost:8081/api/admin/scan/download/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/scan/download/f558a331-0bc3-4a1f-af63-6c437876033e' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

11.1.10. Admin grants admin rights to user

REST API for usecase UC_027-Admin grants admin rights to user

Definition

Table 42. General request information
	Value
Path	/api/admin/user/{userId}/grant/superadmin
Method	POST
Status code	200 OK

Path parameters

Table 43. https://localhost:8081/api/admin/user/{userId}/grant/superadmin
Parameter	Description
`userId`	The userId of the user who becomes admin

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/user/USER_ID/grant/superadmin' -i -u 'user:secret' -X POST

Response body
(empty)

11.1.11. Admin revokes admin rights from an admin

REST API for usecase UC_028-Admin revokes admin rights from an admin

Definition

Table 44. General request information
	Value
Path	/api/admin/user/{userId}/revoke/superadmin
Method	POST
Status code	200 OK

Path parameters

Table 45. https://localhost:8081/api/admin/user/{userId}/revoke/superadmin
Parameter	Description
`userId`	The userId of the user who becomes admin

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/user/USER_ID/revoke/superadmin' -i -u 'user:secret' -X POST

Response body
(empty)

11.1.12. Admin lists all admins

REST API for usecase UC_029-Admin lists all admins

Definition

Table 46. General request information
	Value
Path	/api/admin/admins
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

List of admin Ids

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/admins' -i -u 'user:secret' -X GET

Response body

["admin1","admin2"]

11.1.13. Admin changes owner of a project

REST API for usecase UC_060-Admin changes owner of a project

Definition

Table 47. General request information
	Value
Path	/api/admin/project/{projectId}/owner/{userId}
Method	POST
Status code	200 OK

Path parameters

Table 48. https://localhost:8081/api/admin/project/{projectId}/owner/{userId}
Parameter	Description
`projectId`	The id for project
`userId`	The user id of the user to assign to project as the owner

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/owner/userId1' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.14. Admin updates user email address

REST API for usecase UC_063-Admin updates user email address

Definition

Table 49. General request information
	Value
Path	/api/admin/user/{userId}/email/{emailAddress}
Method	PUT
Status code	200 OK

Path parameters

Table 50. https://localhost:8081/api/admin/user/{userId}/email/{emailAddress}
Parameter	Description
`userId`	The userId of the user whose email address will be changed
`emailAddress`	The new email address

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/user/USER_ID/email/EMAIL_ADDRESS' -i -u 'user:secret' -X PUT

Response body
(empty)

11.1.15. Admin shows user details for email address

REST API for usecase UC_072-Admin shows user details for email address

Definition

Table 51. General request information
	Value
Path	/api/admin/user-by-email/{emailAddress}
Method	GET
Status code	200 OK

Path parameters

Table 52. https://localhost:8081/api/admin/user-by-email/{emailAddress}
Parameter	Description
`emailAddress`	The email address of user to show details for

Request headers

Name Description

Authorization

Basic authentication credentials

Response fields

Path Type Description

userId

String

The name of the user

email

String

The mail address of the user

superAdmin

Boolean

True, when this user is a super administrator

projects

Array

The projects the user has access to

ownedProjects

Array

The projects the user is owner of

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/user-by-email/user1@example.org' -i -u 'user:secret' -X GET

Response body

{"userId":"user1","email":"user1@example.org","superAdmin":false,"projects":["project1"],"ownedProjects":[]}

11.1.16. Admin creates a project

REST API for usecase UC_013-Admin creates a project

Definition

Table 53. General request information
	Value
Path	/api/admin/project
Method	POST
Status code	201 CREATED

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

name

String

Name of the project to create. Is also used as a unique ID!

description

String

The description of the project.

owner

String

Username of the owner of this project. An owner is the person in charge

whiteList.uris

Array

All URIs used now for whitelisting. Former parts will be replaced completely!

metaData

Object

An JSON object containing metadata key-value pairs defined for this project

metaData.*

String

An arbitrary metadata key-value pair

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0", "name":"projectId", "description":"A description of the project.", "owner":"ownerName1", "whiteList":{"uris":["192.168.1.1","https://my.special.server.com/myapp1/"]}, "metaData":{"key1":"value1", "key2":"value2"}}'

Response body
(empty)

11.1.17. Admin lists all projects

REST API for usecase UC_014-Admin lists all projects

Definition

Table 54. General request information
	Value
Path	/api/admin/projects
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

List of project Ids

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/projects' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

["project1","project2"]

11.1.18. Admin deletes a project

REST API for usecase UC_020-Admin deletes a project

Definition

Table 55. General request information
	Value
Path	/api/admin/project/{projectId}
Method	DELETE
Status code	200 OK

Path parameters

Table 56. https://localhost:8081/api/admin/project/{projectId}
Parameter	Description
`projectId`	The id for project to delete

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.19. Update project whitelist

REST API for usecase UC_022-Update project whitelist

Definition

Table 57. General request information
	Value
Path	/api/admin/project/{projectId}/whitelist
Method	POST
Status code	200 OK

Path parameters

Table 58. https://localhost:8081/api/admin/project/{projectId}/whitelist
Parameter	Description
`projectId`	The id of the project for which whitelist shall be updated

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

whiteList.uris

Array

All URIS used now for whitelisting. Former parts will be replaced completely!

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/whitelist' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0", "whiteList":{"uris":["192.168.1.1","https://my.special.server.com/myapp1/"]}}'

Response body
(empty)

11.1.20. Admin shows scan logs for project

REST API for usecase UC_025-Admin shows scan logs for project

Definition

Table 59. General request information
	Value
Path	/api/admin/project/{projectId}/scan/logs
Method	GET
Status code	200 OK

Path parameters

Table 60. https://localhost:8081/api/admin/project/{projectId}/scan/logs
Parameter	Description
`projectId`	The project Id

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

An array of scan log summary entries

[].executedBy

String

The user id of the user which executed the scan

[].started

String

The timestamp when the scan was started

[].ended

String

The timestamp when the scan was ended

[].status

String

A status field about scan situation

[].sechubJobUUID

String

The uuid of corresponding sechub Job.

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/project1/scan/logs' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

[{"sechubJobUUID":"71d49f6c-c9a3-4a82-b53f-21ac50cc2e1f","executedBy":"spartakus","started":"2024-04-29T15:29:56.69565274","ended":"2024-04-30T15:29:56.695671105","status":"OK"}]

11.1.21. Update project metadata

REST API for usecase UC_059-Update project metadata

Definition

Table 61. General request information
	Value
Path	/api/admin/project/{projectId}/metadata
Method	POST
Status code	200 OK

Path parameters

Table 62. https://localhost:8081/api/admin/project/{projectId}/metadata
Parameter	Description
`projectId`	The id of the project for which metadata shall be updated

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

metaData

Object

Metadata object. Contains key-value pairs.

metaData.key1

String

An arbitrary metadata key.

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/metadata' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0", "metaData":{"key1":"value1"}}'

Response body
(empty)

11.1.22. Admin changes project description

REST API for usecase UC_061-Admin changes project description

Definition

Table 63. General request information
	Value
Path	/api/admin/project/{projectId}
Method	POST
Status code	200 OK

Path parameters

Table 64. https://localhost:8081/api/admin/project/{projectId}
Parameter	Description
`projectId`	The id for project to change details for

Request headers

Name

Description

Response fields

Path Type Description

projectId

String

The name of the project.

users

Array

A list of all users having access to the project.

owner

String

Username of the owner of this project. An owner is the person in charge.

whiteList

Array

A list of all whitelisted URIs. Only these ones can be scanned for the project!

metaData

Object

An JSON object containing metadata key-value pairs defined for this project.

metaData.key1

String

An arbitrary metadata key.

accessLevel

String

The project access level

description

String

The project description.

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "description" : "new description"
}'

Response body

{"projectId":"projectId1","users":["name1","name2"],"metaData":{"key1":"value1"},"owner":"name1","description":"description","accessLevel":"full","whiteList":["http://www.sechub.example.org"]}

11.1.23. Admin changes project access level

REST API for usecase UC_062-Admin changes project access level

Definition

Table 65. General request information
	Value
Path	/api/admin/project/{projectId}/accesslevel/{projectAccessLevel}
Method	POST
Status code	200 OK

Path parameters

Table 66. https://localhost:8081/api/admin/project/{projectId}/accesslevel/{projectAccessLevel}
Parameter	Description
`projectId`	The id for project
`projectAccessLevel`	The new project access level. Accepted values: full(Full access to project, no restrictions), read_only(Users have only read access to existing data, No new jobs possible), none(Users have no access at all.)

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/accesslevel/read_only' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.24. User clicks link to get new api token

REST API for usecase UC_012-User clicks link to get new api token

Definition

Table 67. General request information
	Value
Path	/api/anonymous/apitoken/{oneTimeToken}
Method	GET
Status code	200 OK

Path parameters

Table 68. https://localhost:8081/api/anonymous/apitoken/{oneTimeToken}
Parameter	Description
`oneTimeToken`	A one time token the user has got by a previous mail from sechub server

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/apitoken/oneTimeToken1' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.25. User creates a new sechub job

REST API for usecase UC_005-User creates a new sechub job

11.1.25.1. Code Scan variant

Definition

Table 69. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 70. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

codeScan

Object

Code scan configuration block

codeScan.use

Array

Referenced data configuration objects by their unique names

codeScan.fileSystem.folders

Array

Code scan sources from given file system folders

codeScan.fileSystem.files

Array

Code scan sources from given file system files

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"codeScan":{"fileSystem":{"files":[],"folders":["testproject1/src/main/java","testproject2/src/main/java"]},"use":[]},"apiVersion":"1.0"}'

Response body

{"jobId":"07bca11c-137c-479e-b611-1750e78a48cf"}

11.1.25.2. Code Scan using data section variant

Definition

Table 71. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 72. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

codeScan

Object

Code scan configuration block

codeScan.use

Array

Referenced data configuration objects by their unique names

data.sources[].name

String

Unique reference name

data.sources[].fileSystem.folders[]

Array

Sources from given file system folders

data.sources[].fileSystem.files[]

Array

Sources from given file system files

data.binaries[].name

String

Unique reference name

data.binaries[].fileSystem.folders[]

Array

Binaries from given file system folders

data.binaries[].fileSystem.files[]

Array

Binaries from given file system files

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"codeScan":{"use":["source-ref-name","bin-ref-name"]},"data":{"sources":[{"fileSystem":{"files":["testproject1/src/other/example/php-example.php"],"folders":["testproject1/src/main/java","testproject2/src/main/java"]},"name":"source-ref-name"}],"binaries":[{"fileSystem":{"files":["testproject1/build/other/native.dll"],"folders":["testproject1/build/kotlin","testproject1/build/kotlin"]},"name":"bin-ref-name"}]},"apiVersion":"1.0"}'

Response body

{"jobId":"0d3b29a9-cb52-4de5-98eb-195031c53fb8"}

11.1.25.3. Secret scan variant

Definition

Table 73. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 74. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

secretScan

Object

Secret scan configuration block

secretScan.use

Array

Referenced data configuration objects by their unique names

data.sources[].name

String

Unique reference name

data.binaries[].name

String

Unique reference name

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"data":{"sources":[{"name":"source-ref-name"}],"binaries":[{"name":"bin-ref-name"}]},"secretScan":{"use":["source-ref-name","bin-ref-name"]},"apiVersion":"1.0"}'

Response body

{"jobId":"f46fc8f3-05a4-48c6-b3b6-9ec9ae9e2581"}

11.1.25.4. License scan variant

Definition

Table 75. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 76. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

licenseScan

Object

License scan configuration block

licenseScan.use

Array

Referenced data configuration objects by their unique names

data.sources[].name

String

Unique reference name

data.binaries[].name

String

Unique reference name

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"data":{"sources":[{"name":"source-ref-name"}],"binaries":[{"name":"bin-ref-name"}]},"licenseScan":{"use":["source-ref-name","bin-ref-name"]},"apiVersion":"1.0"}'

Response body

{"jobId":"9fe77eba-e3bb-4345-a549-93a5dfed520e"}

11.1.25.5. Infrastructure scan variant

Definition

Table 77. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 78. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

infraScan

Object

Infrastructure configuration block

infraScan.uris

Array

Infrastructure URIs to scan for

infraScan.ips

Array

Infrastructure IPs to scan for

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"infraScan":{"uris":["https://localhost"],"ips":["127.0.0.1"]},"apiVersion":"1.0"}'

Response body

{"jobId":"1b431868-47a0-440e-946c-23f09615f2da"}

11.1.25.6. Web scan anonymous variant

Definition

Table 79. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 80. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.maxScanDuration.duration

Number

Duration of the scan as integer

webScan.maxScanDuration.unit

String

Unit of the duration. Possible values are: millisecond(s), second(s), minute(s), hour(s), day(s)

webScan.includes[]

Array

Include URL sub-paths to scan. Example: /hidden

webScan.excludes[]

Array

Exclude URL sub-paths to scan. Example: /admin

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"maxScanDuration":{"duration":1,"unit":"HOUR"},"url":"https://localhost/mywebapp/login","includes":["/admin","/hidden","/admin.html"],"excludes":["/public/media","/static","/contaxt.html"]},"apiVersion":"1.0"}'

Response body

{"jobId":"7bb13c95-83bb-458d-b472-6d8e83ff550c"}

11.1.25.7. Web scan with api definition variant

Definition

Table 81. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 82. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.api.type

String

Type of the API definition files that will be provided

webScan.api.use

Array

Reference to the data section containing the API definition files. Always use 'sources' with 'files' instead 'folders'.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"api":{"type":"OPEN_API","use":["openApi-file-reference"]},"url":"https://localhost/mywebapp/login"},"apiVersion":"1.0"}'

Response body

{"jobId":"336fb177-98d5-494c-aff1-9cc61d2025b6"}

11.1.25.8. Web scan with client certificate definition variant

Definition

Table 83. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 84. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.clientCertificate.password

String

Password the client certificate file is protected with

webScan.clientCertificate.use

Array

Reference to the data section containing the client certificate definition file. Always use 'sources' with a single 'file' instead 'folders'.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"url":"https://localhost/mywebapp","clientCertificate":{"password":"example-cert-password","use":["client-certificate-file-reference"]}},"apiVersion":"1.0"}'

Response body

{"jobId":"b976c0d9-3633-4a96-8003-0eeefbe99e44"}

Definition

Table 85. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 86. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.login

Object

Webscan login definition

webScan.login.url

String

webScan.login.basic

Object

basic login definition

webScan.login.basic.user

String

username

webScan.login.basic.password

String

password

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"login":{"url":"https://localhost/mywebapp/login","basic":{"user":"username1","password":"password1"}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'

Response body

{"jobId":"a744c96b-d5d0-48e8-bc0e-7ddd1d75b62f"}

Definition

Table 87. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 88. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.login

Object

Webscan login definition

webScan.login.url

String

webScan.login.form

Object

form login definition

webScan.login.form.script

Object

script

webScan.login.form.script.pages[].actions[].type

String

action type: username, password, input, click, wait

webScan.login.form.script.pages[].actions[].selector

String

css selector

webScan.login.form.script.pages[].actions[].value

String

value

webScan.login.form.script.pages[].actions[].description

String

description

webScan.login.form.script.pages[].actions[].unit

String

the time unit to wait: millisecond, second, minute, hour, day.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"login":{"url":"https://localhost/mywebapp/login","form":{"script":{"pages":[{"actions":[{"type":"USERNAME","selector":"#example_login_userid","value":"username1","description":"the username field"},{"type":"INPUT","selector":"#example_login_email_id","value":"user@example.com","description":"The email id field."}]},{"actions":[{"type":"WAIT","value":"2345","unit":"MILLISECOND"},{"type":"PASSWORD","selector":"#example_login_pwd","value":"Super$ecret234!"},{"type":"CLICK","selector":"#example_login_button"}]}]}}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'

Response body

{"jobId":"ab7fafe6-162d-45c3-9cf7-c29026e9b937"}

11.1.25.11. Web Scan headers variant

Definition

Table 89. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 90. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.headers

Array

List of HTTP headers. Can be used for authentication or anything else.

webScan.headers[].name

String

Name of the defined HTTP header.

webScan.headers[].value

String

Value of the defined HTTP header. Either specify the header value directly here or reference a data section with 'use' e.g. if the value is to big, but never specify both.

webScan.headers[].use

Array

Reference to the data section containing a file with the value for this header, e.g if the value is to big for the sechub configuration. Always use 'sources' with a single 'file' instead 'folders'.

webScan.headers[].onlyForUrls[]

Array

Optional list of URLs this header shall be used for like: https://mywebapp.com/path/. Can contain wildcards like: https://mywebapp.com/path/<*>/with/wildcard

webScan.headers[].sensitive

Boolean

Defines header masking. If 'true' the header value will be replaced with '**' inside the report, 'false' will show the value as is. Default is set to 'true'.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"url":"https://localhost/mywebapp","headers":[{"name":"api-token","value":"secret","onlyForUrls":["https://localhost/mywebapp/admin","https://localhost/mywebapp/<*>/profile","https://localhost/mywebapp/blog/<*>"],"sensitive":true,"use":["header-value-file-ref-for-big-tokens"]}]},"apiVersion":"1.0"}'

Response body

{"jobId":"e646cfbd-5527-4754-aa27-b524e411693c"}

11.1.26. User uploads source code

REST API for usecase UC_006-User uploads source code

Definition

Table 91. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}/sourcecode
Method	POST
Status code	200 OK

Path parameters

Table 92. https://localhost:8081/api/project/{projectId}/job/{jobUUID}/sourcecode
Parameter	Description
`projectId`	The id of the project where sourcecode shall be uploaded for
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/6d308234-2ad5-4628-a79f-e907b02ae48f/sourcecode?checkSum=checkSumValue' -i -X POST \
    -H 'Content-Type: multipart/form-data;charset=UTF-8' \
    -F 'file=PK  
      �<M                       test1.txtPK  ?
      �<M                     $               test1.txt
            ��IW�  ��IW�  ��IW� PK          [   '     '

Response body
(empty)

11.1.27. User approves sechub job

REST API for usecase UC_007-User approves sechub job

Definition

Table 93. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}/approve
Method	PUT
Status code	200 OK

Path parameters

Table 94. https://localhost:8081/api/project/{projectId}/job/{jobUUID}/approve
Parameter	Description
`projectId`	The id of the project where sechub job shall be approved
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/c289eafc-3409-421f-a65a-6efc02f14406/approve' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.28. User checks sechub job state

REST API for usecase UC_009-User checks sechub job state

Definition

Table 95. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 96. https://localhost:8081/api/project/{projectId}/job/{jobUUID}
Parameter	Description
`projectId`	The id of the project where sechub job was started for
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name

Description

Response fields

Path Type Description

jobUUID

String

The job uuid

created

String

Creation timestamp of job

started

String

Start timestamp of job execution

ended

String

End timestamp of job execution

owner

String

Owner / initiator of job

state

String

State of job

result

String

Result of job

trafficLight

String

Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/dd67a2c2-74ae-4032-8ea6-7e6c6561f099' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"jobUUID":"dd67a2c2-74ae-4032-8ea6-7e6c6561f099","owner":"CREATOR1","created":"","started":"2024-04-30T15:14:55.350966931","ended":"2024-04-30T15:29:55.350989543","state":"ENDED","result":"OK","trafficLight":"GREEN"}

11.1.29. User downloads sechub job report

REST API for usecase UC_010-User downloads sechub job report

11.1.29.1. JSON variant

Definition

Table 97. General request information
	Value
Path	/api/project/{projectId}/report/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 98. https://localhost:8081/api/project/{projectId}/report/{jobUUID}
Parameter	Description
`projectId`	The project Id
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/report/aa193217-8ee5-42f5-9788-6b38b24b2783' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

11.1.29.2. HTML variant

Definition

Table 99. General request information
	Value
Path	/api/project/{projectId}/report/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 100. https://localhost:8081/api/project/{projectId}/report/{jobUUID}
Parameter	Description
`projectId`	The project Id
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/report/2eabeea2-0b97-42dc-a6d3-e318d4ad1ca5' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/xhtml+xml'

11.1.30. User marks false positives for finished sechub job

REST API for usecase UC_044-User marks false positives for finished sechub job

Definition

Table 101. General request information
	Value
Path	/api/project/{projectId}/false-positives
Method	PUT
Status code	200 OK

Path parameters

Table 102. https://localhost:8081/api/project/{projectId}/false-positives
Parameter	Description
`projectId`	The projectId of the project where users adds false positives for

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

type

String

The type of the json content. Currently only accepted value is 'falsePositiveJobDataList'.

jobData

Array

Job data list containing false positive setup based on former jobs

jobData[].jobUUID

String

SecHub job uuid where finding was

jobData[].findingId

Number

SecHub finding identifier - identifies problem inside the job which shall be markeda as a false positive. ATTENTION: at the moment only code scan false positive handling is supported. Infra and web scan findings will lead to a non accepted error!

jobData[].comment

String

A comment describing why this is a false positive

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0","type":"falsePositiveJobDataList","jobData":[{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"an optional comment why this is a false positive..."}]}'

Response body
(empty)

11.1.31. User unmarks existing false positive definitons

REST API for usecase UC_045-User unmarks existing false positive definitons

Definition

Table 103. General request information
	Value
Path	/api/project/{projectId}/false-positive/{jobUUID}/{findingId}
Method	DELETE
Status code	200 OK

Path parameters

Table 104. https://localhost:8081/api/project/{projectId}/false-positive/{jobUUID}/{findingId}
Parameter	Description
`projectId`	The project id
`jobUUID`	Job uuid
`findingId`	Finding id - in combination with job UUID this defines the false positive to remove

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/false-positive/f1d02a9d-5e1b-4f52-99e5-401854ccf936/42' -i -u 'user:secret' -X DELETE

Response body
(empty)

11.1.32. User fetches false positive configuration of project

REST API for usecase UC_046-User fetches false positive configuration of project

Definition

Table 105. General request information
	Value
Path	/api/project/{projectId}/false-positives
Method	GET
Status code	200 OK

Path parameters

Table 106. https://localhost:8081/api/project/{projectId}/false-positives
Parameter	Description
`projectId`	The project id

Request headers

Name

Description

Response fields

Path Type Description

falsePositives

Array

Job data list containing false positive setup based on former jobs

falsePositives[].author

String

User id of author who created false positive

falsePositives[].created

String

Creation timestamp

falsePositives[].metaData

Object

Meta data for this false positive

falsePositives[].metaData.scanType

String

Scan type - e.g. codeScan

falsePositives[].metaData.name

String

Name of origin finding marked as false positive

falsePositives[].metaData.cweId

Number

CWE (common weakness enumeration). For code scans this is always set.

falsePositives[].metaData.cveId

String

CVE (common vulnerability and exposures). For infra scans this is always set.

falsePositives[].metaData.owasp

String

OWASP At least this field must be set for web scans when no cwe identifier is defined.

falsePositives[].metaData.severity

String

Severity of origin report entry marked as false positive

falsePositives[].metaData.code

Object

Code part. Only available for scan type 'codeScan'

falsePositives[].metaData.code.start

Object

entry point

falsePositives[].metaData.code.start.location

String

location of code

falsePositives[].metaData.code.start.relevantPart

String

relevant part of source vulnerability

falsePositives[].metaData.code.start.sourceCode

String

source code

falsePositives[].metaData.code.end

Object

end point (sink)

falsePositives[].metaData.code.end.location

String

location of code

falsePositives[].metaData.code.end.relevantPart

String

relevant part of source vulnerability

falsePositives[].metaData.code.end.sourceCode

String

source code

falsePositives[].jobData

Object

Job data parts, can be used as key to identify false positives

falsePositives[].jobData.jobUUID

String

SecHub job uuid where finding was

falsePositives[].jobData.findingId

Number

falsePositives[].jobData.comment

String

A comment from author describing why this was marked as a false positive

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X GET

Response body

{"falsePositives":[{"jobData":{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"Only used in documentation build not in deployment"},"author":"developer1","metaData":{"scanType":"codeScan","name":"Absolute Path Traversal","severity":"MEDIUM","code":{"start":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"args","sourceCode":"\tpublic static void main(String[] args) throws Exception {"},"end":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"File","sourceCode":"\t\tFile documentsGenFolder = new File(path);"}},"cweId":36},"created":"2020-06-12 11:53:15"}]}

11.1.33. User uploads binaries

REST API for usecase UC_069-User uploads binaries

Definition

Table 107. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}/binaries
Method	POST
Status code	200 OK

Path parameters

Table 108. https://localhost:8081/api/project/{projectId}/job/{jobUUID}/binaries
Parameter	Description
`projectId`	The id of the project for which the binaries are uploaded for
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name Description

x-file-size

The file size of the tar-archive to upload in bytes. Needs to be a positive integer value.

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/f946c2e6-4c00-4372-b1a1-2f5ba9090ae5/binaries' -i -X POST \
    -H 'Content-Type: multipart/form-data;charset=UTF-8' \
    -H 'x-file-size: 10240' \
    -F 'file=test1.txt                                                                                           0000664 0001750 0001750 00000000000 13353454574 012170  0                                                                                                    ustar   albert                          albert                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 ' \
    -F 'checkSum=checkSumValue'

Response body
(empty)

11.1.34. User downloads job report in SPDX format

REST API for usecase UC_070-User downloads job report in SPDX format

Definition

Table 109. General request information
	Value
Path	/api/project/{projectId}/report/spdx/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 110. https://localhost:8081/api/project/{projectId}/report/spdx/{jobUUID}
Parameter	Description
`projectId`	The project Id
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/report/spdx/2c623362-da14-4140-9199-8f6138179065' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

11.1.35. User self registration

REST API for usecase UC_001-User self registration

Definition

Table 111. General request information
	Value
Path	/api/anonymous/signup
Method	POST
Status code	200 OK

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

userId

String

Wanted userid, the userid must be lowercase only!

emailAddress

String

Email address

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/signup' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0","userId":"valid_userid","emailAddress":"valid_mailaddress@example.org"}'

Response body
(empty)

11.1.36. Admin lists open user signups

REST API for usecase UC_002-Admin lists open user signups

Definition

Table 112. General request information
	Value
Path	/api/admin/signups
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

List of user signups

[].userId

String

The user id

[].emailAddress

String

The email address

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/signups' -i -u 'user:secret' -X GET

Response body

[{"userId":"johnsmith","emailAddress":"john.smith@example.com"},{"userId":"janesmith","emailAddress":"jane.smith@example.com"}]

11.1.37. Admin applies self registration

REST API for usecase UC_003-Admin applies self registration

Definition

Table 113. General request information
	Value
Path	/api/admin/signup/accept/{userId}
Method	POST
Status code	201 CREATED

Path parameters

Table 114. https://localhost:8081/api/admin/signup/accept/{userId}
Parameter	Description
`userId`	The userId of the signup which shall be accepted

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/signup/accept/user1' -i -u 'user:secret' -X POST

Response body
(empty)

REST API for usecase UC_019-Admin deletes user signup

Definition

Table 115. General request information
	Value
Path	/api/admin/signup/{userId}
Method	DELETE
Status code	200 OK

Path parameters

Table 116. https://localhost:8081/api/admin/signup/{userId}
Parameter	Description
`userId`	The userId of the signup which shall be deleted

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/signup/userId1' -i -u 'user:secret' -X DELETE

Response body
(empty)

11.1.39. User requests new API token

REST API for usecase UC_024-User requests new API token

Definition

Table 117. General request information
	Value
Path	/api/anonymous/refresh/apitoken/{emailAddress}
Method	POST
Status code	200 OK

Path parameters

Table 118. https://localhost:8081/api/anonymous/refresh/apitoken/{emailAddress}
Parameter	Description
`emailAddress`	Email address for user where api token shall be refreshed.

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/refresh/apitoken/emailAddress@example.com' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.40. Admin lists all running jobs

REST API for usecase UC_023-Admin lists all running jobs

Definition

Table 119. General request information
	Value
Path	/api/admin/jobs/running
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

[].jobUUID

String

The uuid of the running job

[].projectId

String

The name of the project the job is running for

[].owner

String

Owner of the job - means user which triggered it

[].status

String

A status information

[].since

String

Timestamp since when job has been started

[].configuration

String

Configuration used for this job

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/running' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

[{"jobUUID":"ae921708-6c4b-4a5e-a8ef-509f3e8c0e0e","projectId":"project-name","owner":"owner-userid","status":"RUNNING","since":"2024-04-30T15:29:59.365613511","configuration":"{ config data }"}]

11.1.41. Admin cancels a job

REST API for usecase UC_034-Admin cancels a job

Definition

Table 120. General request information
	Value
Path	/api/admin/jobs/cancel/{jobUUID}
Method	POST
Status code	200 OK

Path parameters

Table 121. https://localhost:8081/api/admin/jobs/cancel/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/cancel/4c2e06e5-bda5-4235-b58e-e61fb66083d8' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.42. Admin restarts a job

REST API for usecase UC_041-Admin restarts a job

Definition

Table 122. General request information
	Value
Path	/api/admin/jobs/restart/{jobUUID}
Method	POST
Status code	200 OK

Path parameters

Table 123. https://localhost:8081/api/admin/jobs/restart/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/restart/d0073ed1-3784-42ba-a3f8-d4a68178b60f' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.43. Admin restarts a job (hard)

REST API for usecase UC_042-Admin restarts a job (hard)

Definition

Table 124. General request information
	Value
Path	/api/admin/jobs/restart-hard/{jobUUID}
Method	POST
Status code	200 OK

Path parameters

Table 125. https://localhost:8081/api/admin/jobs/restart-hard/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/restart-hard/e4017208-f80f-40d1-8466-0a8144b6941e' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.44. User defines mock data configuration for project

REST API for usecase UC_035-User defines mock data configuration for project

Definition

Table 126. General request information
	Value
Path	/api/project/{projectId}/mockdata
Method	PUT
Status code	200 OK

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/mockdata' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{"codeScan":{"result":"RED"},"webScan":{"result":"YELLOW"},"infraScan":{"result":"GREEN"}}'

Response body
(empty)

11.1.45. User retrieves mock data configuration for project

REST API for usecase UC_036-User retrieves mock data configuration for project

Definition

Table 127. General request information
	Value
Path	/api/project/{projectId}/mockdata
Method	GET
Status code	200 OK

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/mockdata' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

Response body

{"codeScan":{"result":"RED"},"webScan":{"result":"YELLOW"},"infraScan":{"result":"GREEN"}}

11.1.46. Admin updates mapping configuration

REST API for usecase UC_037-Admin updates mapping configuration

Definition

Table 128. General request information
	Value
Path	/api/admin/config/mapping/{mappingId}
Method	PUT
Status code	200 OK

Path parameters

Table 129. https://localhost:8081/api/admin/config/mapping/{mappingId}
Parameter	Description
`mappingId`	The mappingID, identifiying which mapping shall be updated

Request headers

Name

Description

Request fields

Path Type Description

entries.[].pattern

String

Pattern

entries.[].replacement

String

Replacement

entries.[].comment

String

Comment

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/mapping/checkmarx.newproject.teamid.mapping' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"entries":[{"pattern":"testproject_*","replacement":"8be4e3d4-6b53-4636-b65a-949a9ebdf6b9","comment":"testproject-team"},{"pattern":".*","replacement":"3be4e3d2-2b55-2336-b65a-949b9ebdf6b9","comment":"default-team"}]}'

Response body
(empty)

11.1.47. Admin fetches mapping configuration

REST API for usecase UC_038-Admin fetches mapping configuration

Definition

Table 130. General request information
	Value
Path	/api/admin/config/mapping/{mappingId}
Method	GET
Status code	200 OK

Path parameters

Table 131. https://localhost:8081/api/admin/config/mapping/{mappingId}
Parameter	Description
`mappingId`	The mapping Id

Request headers

Name

Description

Response fields

Path Type Description

entries.[].pattern

String

Pattern

entries.[].replacement

String

Replacement

entries.[].comment

String

Comment

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/mapping/checkmarx.newproject.teamid.mapping' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"entries":[{"pattern":"testproject_*","replacement":"8be4e3d4-6b53-4636-b65a-949a9ebdf6b9","comment":"testproject-team"},{"pattern":".*","replacement":"3be4e3d2-2b55-2336-b65a-949b9ebdf6b9","comment":"default-team"}]}

11.1.48. Admin creates an executor configuration

REST API for usecase UC_047-Admin creates an executor configuration

Definition

Table 132. General request information
	Value
Path	/api/admin/config/executor
Method	POST
Status code	201 CREATED

Request headers

Name

Description

Request fields

Path Type Description

name

String

A name for this configuration

productIdentifier

String

Executor product identifier

executorVersion

Number

Executor version

enabled

Boolean

Enabled state of executor, per default false

setup.baseURL

String

Base URL to the product

setup.credentials.user

String

User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable

setup.credentials.password

String

Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable

setup.jobParameters[].key

String

Job parameter key

setup.jobParameters[].value

String

Job parameter value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"name":"PDS gosec config 1","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productXYZ.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"},{"key":"example.key2","value":"Another value"}]}}'

Response body

27b8f5fc-3892-434e-8594-0d80a11e373f

11.1.49. Admin deletes executor configuration

REST API for usecase UC_048-Admin deletes executor configuration

Definition

Table 133. General request information
	Value
Path	/api/admin/config/executor/{uuid}
Method	DELETE
Status code	200 OK

Path parameters

Table 134. https://localhost:8081/api/admin/config/executor/{uuid}
Parameter	Description
`uuid`	The configuration uuid

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor/d1622a9a-60cd-451e-9e50-296894a03fc0' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.50. Admin fetches executor configuration list

REST API for usecase UC_049-Admin fetches executor configuration list

Definition

Table 135. General request information
	Value
Path	/api/admin/config/executors
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

type

String

Always executorConfigurationList as an identifier for the list

executorConfigurations[].uuid

String

The uuid of the configuration

executorConfigurations[].name

String

The configuration name

executorConfigurations[].enabled

Boolean

Enabled state of configuration

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executors' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"executorConfigurations":[{"uuid":"34a78392-d24d-4b8d-b92b-5f98a6aa69d8","name":"example configuration","enabled":true}],"type":"executorConfigurationList"}

11.1.51. Admin fetches executor configuration

REST API for usecase UC_050-Admin fetches executor configuration

Definition

Table 136. General request information
	Value
Path	/api/admin/config/executor/{uuid}
Method	GET
Status code	200 OK

Path parameters

Table 137. https://localhost:8081/api/admin/config/executor/{uuid}
Parameter	Description
`uuid`	The configuration uuid

Request headers

Name

Description

Response fields

Path Type Description

uuid

String

The uuid of this configuration

name

String

The name of this configuration

productIdentifier

String

Executor product identifier

executorVersion

Number

Executor version

enabled

Boolean

Enabled state of executor

setup.baseURL

String

Base URL to the product

setup.credentials.user

String

User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable

setup.credentials.password

String

Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable

setup.jobParameters[].key

String

Job parameter key

setup.jobParameters[].value

String

Job parameter value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor/e08f35c6-c0a5-45d5-8a80-d2b9e0b8c1db' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"}]},"executorVersion":1,"enabled":false,"uuid":"e08f35c6-c0a5-45d5-8a80-d2b9e0b8c1db"}

11.1.52. Admin updates executor configuration setup

REST API for usecase UC_051-Admin updates executor configuration setup

Definition

Table 138. General request information
	Value
Path	/api/admin/config/executor/{uuid}
Method	PUT
Status code	200 OK

Path parameters

Table 139. https://localhost:8081/api/admin/config/executor/{uuid}
Parameter	Description
`uuid`	The configuration uuid

Request headers

Name

Description

Request fields

Path Type Description

name

String

The name of this configuration

productIdentifier

String

Executor product identifier

executorVersion

Number

Executor version

enabled

Boolean

Enabled state of executor, per default false

setup.baseURL

String

Base URL to the product

setup.credentials.user

String

User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable

setup.credentials.password

String

Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable

setup.jobParameters[].key

String

Job parameter key

setup.jobParameters[].value

String

Job parameter value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor/0169bf99-fb43-4ecb-b4b1-451574318b23' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"name":"New name","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productNew.example.com","credentials":{"user":"env:EXAMPLE_NEW_USENAME","password":"env:EXAMPLE_NEW_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]}}'

Response body
(empty)

11.1.53. Admin creates an execution profile

REST API for usecase UC_052-Admin creates an execution profile

Definition

Table 140. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	POST
Status code	201 CREATED

Path parameters

Table 141. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Request fields

Path Type Description

description

String

A short description for the profile

enabled

Boolean

Enabled state of profile, default is false

configurations[]

Array

Configurations can be linked at creation time as well - see update description

projectIds[]

Array

Projects can be linked by their ids at creation time as well - see update description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/new-profile-1' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"description":"a short description for profile","configurations":[],"projectIds":[],"enabled":false}'

Response body
(empty)

11.1.54. Admin deletes execution profile

REST API for usecase UC_053-Admin deletes execution profile

Definition

Table 142. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	DELETE
Status code	200 OK

Path parameters

Table 143. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-to-delete-1' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.55. Admin updates execution profile

REST API for usecase UC_054-Admin updates execution profile

Definition

Table 144. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	PUT
Status code	200 OK

Path parameters

Table 145. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Request fields

Path Type Description

description

String

A short description for the profile

enabled

Boolean

Enabled state of profile, default is false

configurations[].uuid

String

Add uuid for configuration to use here

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/existing-profile-1' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"description":"changed description","configurations":[{"uuid":"fb93a42f-7399-44f6-be33-b2686be472fb","executorVersion":0,"enabled":false,"setup":{"credentials":{},"jobParameters":[]}}],"enabled":true}'

Response body
(empty)

11.1.56. Admin fetches execution profile

REST API for usecase UC_055-Admin fetches execution profile

Definition

Table 146. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	GET
Status code	200 OK

Path parameters

Table 147. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Response fields

Path Type Description

description

String

A short description for the profile

enabled

Boolean

Enabled state of profile, default is false

configurations[].uuid

String

uuid of configuration

configurations[].name

String

name of configuration

configurations[].enabled

Boolean

enabled state of this config

configurations[].productIdentifier

String

executed product

configurations[].executorVersion

Number

executor version

projectIds[]

Array

Projects can be linked by their ids here

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/existing-profile-1' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"description":"a description","enabled":true,"configurations":[{"name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]},"executorVersion":1,"enabled":false,"uuid":"c92808e3-297b-43fd-97d2-f0c389c66be7"}],"projectIds":["project-1","project-2"]}

11.1.57. Admin fetches execution profile list

REST API for usecase UC_056-Admin fetches execution profile list

Definition

Table 148. General request information
	Value
Path	/api/admin/config/execution/profiles
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

type

String

Always executorProfileList as an identifier for the list

executionProfiles[].id

String

The profile id

executionProfiles[].description

String

A profile description

executionProfiles[].enabled

Boolean

Enabled state of profile

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profiles' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"executionProfiles":[{"id":"profile1","description":"A short decription for profile1","enabled":false},{"id":"profile2","description":"A short decription for profile2","enabled":false}],"type":"executionProfileList"}

11.1.58. Admin assigns execution profile to project

REST API for usecase UC_057-Admin assigns execution profile to project

Definition

Table 149. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}/project/{projectId}
Method	POST
Status code	201 CREATED

Path parameters

Table 150. https://localhost:8081/api/admin/config/execution/profile/{profileId}/project/{projectId}
Parameter	Description
`projectId`	The project id
`profileId`	The profile id

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-1/project/project-1' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.59. Admin unassigns execution profile from project

REST API for usecase UC_058-Admin unassigns execution profile from project

Definition

Table 151. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}/project/{projectId}
Method	DELETE
Status code	200 OK

Path parameters

Table 152. https://localhost:8081/api/admin/config/execution/profile/{profileId}/project/{projectId}
Parameter	Description
`projectId`	The project id
`profileId`	The profile id

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-1/project/project-1' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.60. Admin fetches auto cleanup configuration

REST API for usecase UC_064-Admin fetches auto cleanup configuration

Definition

Table 153. General request information
	Value
Path	/api/admin/config/autoclean
Method	GET
Status code	200 OK

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/autoclean' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"cleanupTime":{"unit":"MONTH","amount":0}}

11.1.61. Admin updates auto cleanup configuration

REST API for usecase UC_065-Admin updates auto cleanup configuration

Definition

Table 154. General request information
	Value
Path	/api/admin/config/autoclean
Method	PUT
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/autoclean' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"cleanupTime":{"unit":"MONTH","amount":0}}'

Response body
(empty)

11.1.62. Admin disables job processing in scheduler

REST API for usecase UC_030-Admin disables job processing in scheduler

Definition

Table 155. General request information
	Value
Path	/api/admin/scheduler/disable/job-processing
Method	POST
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/scheduler/disable/job-processing' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.63. Admin enables scheduler job processing

REST API for usecase UC_031-Admin enables scheduler job processing

Definition

Table 156. General request information
	Value
Path	/api/admin/scheduler/enable/job-processing
Method	POST
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/scheduler/enable/job-processing' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.64. Admin get scheduler status

REST API for usecase UC_032-Admin get scheduler status

Definition

Table 157. General request information
	Value
Path	/api/admin/scheduler/status/refresh
Method	POST
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/scheduler/status/refresh' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

11.1.65. Admin lists status information

REST API for usecase UC_033-Admin lists status information

Definition

Table 158. General request information
	Value
Path	/api/admin/status
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

[].key

String

Status key identifier

[].value

String

Status value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/status' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

[{"key":"status.scheduler.enabled","value":"true"},{"key":"status.scheduler.jobs.all","value":"100"},{"key":"status.scheduler.jobs.initializing","value":"1"},{"key":"status.scheduler.jobs.ready_to_start","value":"19"},{"key":"status.scheduler.jobs.started","value":"20"},{"key":"status.scheduler.jobs.ended","value":"50"},{"key":"status.scheduler.jobs.cancel_requested","value":"2"},{"key":"status.scheduler.jobs.canceled","value":"8"}]

11.1.66. Admin fetches server runtime data

REST API for usecase UC_040-Admin fetches server runtime data

Definition

Table 159. General request information
	Value
Path	/api/admin/info/server
Method	GET
Status code	200 OK

Response fields

Path Type Description

serverVersion

String

The sechub server version.

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/info/server' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"serverVersion":"0.12.3"}

11.1.67. User lists jobs for project

REST API for usecase UC_071-User lists jobs for project

Definition

Table 160. General request information
	Value
Path	/api/project/{projectId}/jobs
Method	GET
Status code	200 OK

Path parameters

Table 161. https://localhost:8081/api/project/{projectId}/jobs
Parameter	Description
`projectId`	The id of the project where job information shall be fetched for

Request headers

Name

Description

Response fields

Path Type Description

page

Number

The page number

totalPages

Number

The total pages available

content[].jobUUID

String

The job uuid

content[].created

String

Creation timestamp of job

content[].started

String

Start timestamp of job execution

content[].ended

String

End timestamp of job execution

content[].executedBy

String

User who initiated the job

content[].executionState

String

Execution state of job

content[].executionResult

String

Execution result of job

content[].trafficLight

String

Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF

content[].metaData.*

Object

Meta data of job - but only contained in result, when query parameter withMetaData is defined as 'true'.

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/jobs?size=1&page=0&withMetaData=true&metadata.labels.stage=testing' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"page":0,"totalPages":1,"content":[{"jobUUID":"2a7ac811-798b-4f92-8df7-449b13f3d2f3","executedBy":"User1","created":"2024-04-30T15:12:55.476455968","started":"2024-04-30T15:14:55.47648388","ended":"2024-04-30T15:29:55.476494771","executionState":"ENDED","trafficLight":"GREEN","executionResult":"OK","metaData":{"labels":{"stage":"test"}}}]}

12. Technical debt

12.1. Long running transactions

There could be a problem about long running transactions.

12.2. Domain messaging system

12.2.1. Authorization

At the moment the domain auth is not 100% correct implemented respectively used more as layer that being a domain having a bounded context.

Explanation:

Inside project sechub-authorizhation spring boot auth handling is defined. We got our own database table starting with "AUTH_" and communication is done by events. So far so good. It works very well at the moment.

But… this works only because we currently have ONE self contained system. Spring boot uses the UserDetailService defined inside this project. If we decide to separate SecHub into different deployment units, we must either use the project as a library for deployed parts (so more a "layer") or we introduce a possiblitiy for other domains to get authorization info from this one.

As long as we do not separate and have all contained in ONE application this is not a problem. When separation must be done, we need a concept to change auth handling in adequate way.

12.2.2. Current event bus implementation

Currently the domain messaging is done by a simple observer pattern.
It’s working, is easy to maintain, simple but has some caveats:

Domain communication is done only inside ONE cluster member (seen from starting point).
(We got still cluster side working! The scheduling approach handles it correctly. But a job will have communication etc. only inside same JVM - which is maybe even a good thing ? - and reduces complexity)
- What does this include?
  - We got no "cluster communication".
  - We got no fallback handling when e.g. a cluster fails we got no respawning of the handling or queue entry

This was a wanted architecture decision to keep things simple on startup. The used wrapper mechanism gives us t the chance to change the implementation when necessary, without too much effort. The benefits of data separation is still there.

12.2.2.1. Additional information

Sending asynchronous messages are really asynchronous
The implementation in DomainMessageService uses a spring task executor to provide this in conjunction with observer pattern.

12.2.3. What possibilities do we have to change this in future?

Use Queuing System (maybe something more lightweight than KAFKA…)
Write another spring application which has got REST API and is installed one time in cluster
- Problem: Bottleneck, much effort, deployment, etc.
Keep simple implementation as is but implement resilience

13. HowTos

13.1. Howto integrate a new product

At the beginning of SecHub it was always necessary to implement a new product adapter (in Java), create a new product executor (in Java) and create new product result importer (also in Java).

Those days are gone. Nowadays we are shifting every new product into a PDS (product delegation server) solution. For PDS we have an already existing PDS adapter (the logic to communicate with PDS) which is used always.

At the moment we have still some direct product adapters. Some are marked as deprecated and will vanish. Others will be replaced by PDS solutions.

In the future there shall be only two products which have dedicated adapter implementations: SERECO and PDS.

For every existing type of scan there is a dedicated PDS product executor available. When the security product is able to produce SARIF output, we are able to import this already. You can find multiple existing solutions and more details at https://github.com/mercedes-benz/sechub/tree/develop/sechub-pds-solutions.

In the best case scenario there is no need to write anything in Java - we copy an existing pds-solution to a new folder name, make some necessary adjustments, change the caller script and we are done…

Only when a product result is not already supported by SERECO (SecHub report collector), we must write a special ProductResultImporter.

13.2. Howto configure mock behaviours

13.2.1. Default mock adapter used in SecHub integration tests

The MockedAdapterSetupService reads a JSON configfile from file path.

Default file is located at /sechub-other/mockdata/mockdata_setup.json

If you want to use another location, use system property defined in MockedAdapterSetupService.java to define another location.

Example:

{
    "entries": [
        { (1)
            "adapterId": "MockedNetsparkerAdapter",
            "combinations": [
                {(2)
                    "target" : "https://vulnerable.demo.example.org", (3)
                    "throwsAdapterException": false,(4)
                    "filePath": "./../sechub-other/mockdata/netsparker-mockdata-one-important-vulnerability.xml" (5)
                },
                {
                    "target": "https://safe.demo.example.org",
                    "throwsAdapterException": false,
                    "filePath": "./../sechub-other/mockdata/netsparker-mockdata-green.xml"
                },
                {
                    "target": "{any-other-target}",
                    "throwsAdapterException": false,
                    "filePath": "./../sechub-other/mockdata/netsparker-mockdata-green.xml"
                }
            ]
        }

    ]
}

1	One Adapter definition for mocking, can be multiple times, but for each adapter only one definition!
2	A combination for the adapter
3	Target url definition, for code scanners the file resource folders are the targets e.g. `"../sechub-doc/src/main/java"`. When using `"{any-other-target}"` this will the combination used for all not defined combinations.
4	Mocked adapter will not throw an exception on execution time, when true defined the adapter will thow an adapter execution. Interesting for tests
5	Filepath for result file to return by mock when target url of Job starts with defined one

13.2.2. Project specific mock adapter behaviour

Users can define a mock configuration via REST. This is convenient for integration tests from foreign systems. But there can not be any product specific configuration.

For more details see use case description or look at GitHub issue #141

13.3. Howto start a local development server like in production

In most cases its enough to use mocked adapter variants for development. But sometimes its necessary to start up a local development server using real security products (e.g. full integration testing etc.)

Launch configuration is described at Test/Use real products. You should also use same storage as you use in production! So when you are using a S3 bucket for storage there you should define this as well!

13.4. Howto quickly test a SecHub server release on local machine

For a "quick test" we start the release simply in integrationtest mode.

13.4.1. Get the release

You got different options: You can either download an existing release from https://github.com/mercedes-benz/sechub/releases , or you build it from scratch.

Here an example for a scratch-build: Checked out GIT tag v0.19.1-server and by executing ./gradlew bootJar) you will find the server release 0.19.1 at sechub-server/build/libs/sechub-server-0.19.1.jar

13.4.2. Start release on your machine

Open a shell at the folder where your jar (In the next script we use sechub-server-0.19.1.jar) is located. Then execute the server in integrationtest mode.

java -Dspring.profiles.active=mocked_products,h2,integrationtest -Dsechub.server.debug=false -Dsechub.storage.sharedvolume.upload.dir=temp -Dsechub.targettype.detection.intranet.hostname.endswith=intranet.example.org -Dsechub.config.trigger.nextjob.initialdelay=0 -Dsechub.integrationtest.ignore.missing.serverproject=true -jar sechub-server-0.19.1.jar

13.4.3. Further steps

Use the DAUI (Developer Administration User Interface) to test the server. In integration test mode, you can test nearly all SecHub server features - except the real product communication, because all adapters are mocked.

14. Reporting

This chapter describes the different SecHub report types and how to read them.

Job reports do only contain information of exact one scan job done by SecHub.

14.1. Job reports

Users can download the results of their finished scan jobs. SecHub provides these report formats:

HTML
human friendly report variant with less details
JSON
as an also machine readable format. It can be directly used by the SecHub IDE plugins (Eclipse, IntelliJ, VSCode/Codium)
SPDX JSON

14.1.1. HTML

The main purpose for the HTML report is to have a human friendly report which gives you a fast overview.

At the top left corner you see a traffic light showing either

GREEN
YELLOW or
RED.

You can open the details by clicking on "Open details". This allows you to see the full hierarchy from entry point down to data sink and can help you in analyzing this finding. It also shows a description and a possible solution (if there is one).

The next picture shows a report which resulted in a red traffic light.

At the top of the report you find the most critical parts - in this example it is a "red" finding with finding ID 19 which is a "Stored XSS".
The second finding with ID 20 is of the same type. Here the details view is opened so more details can be seen.

If available, you can find the corresponding CWE-Id (Common Weakness Enumeration) as a link to the knowledge base of MITRE in the Type column.

The SecHub client will exit with a non-zero return code per default only at a RED traffic light, but you can also configure the client to do this on color YELLOW.

14.1.2. JSON

This is the machine readable report format.

14.1.2.1. Example code scan report with yellow traffic light

{
  "jobUUID": "6cf02ccf-da13-4dee-b529-0225ed9661bd", (1)
  "trafficLight": "YELLOW", (2)
  "messages": [],
  "status": "SUCCESS",
  "reportVersion": "1.0",
  "result": {
    "count": 2,
    "findings": [
      {
        "id": 1, (3)
        "description": "",
        "name": "Absolute Path Traversal", (4)
        "severity": "MEDIUM", (5)
        "code": {
          "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java", (6)
          "line": 28, (7)
          "column": 35,
          "source": "\tpublic static void main(String[] args) throws Exception {",
          "relevantPart": "args",
          "calls": { (8)
            "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java",
            "line": 33,
            "column": 17,
            "source": "\t\tString path = args[0];",
            "relevantPart": "args",
            "calls": {
              "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java",
              "line": 33,
              "column": 10,
              "source": "\t\tString path = args[0];",
              "relevantPart": "path",
              "calls": {
                "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java",
                "line": 34,
                "column": 38,
                "source": "\t\tFile documentsGenFolder = new File(path);",
                "relevantPart": "path",
                "calls": {
                  "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java", (9)
                  "line": 34, (10)
                  "column": 29,
                  "source": "\t\tFile documentsGenFolder = new File(path);", (11)
                  "relevantPart": "File" (12)
                }
              }
            }
          }
        },
        "type": "codeScan",
        "cweId": 778
      },
      {
        "id": 2,
        "description": "",
        "hostnames": [],
        "name": "Insufficient Logging of Exceptions",
        "references": [],
        "severity": "INFO",
        "code": {
          "location": "java/com/mercedesbenz/sechub/docgen/usecase/UseCaseRestDocModelDataCollector.java",
          "line": 137,
          "column": 5,
          "source": "\t\t} catch (IOException e) {",
          "relevantPart": "catch"
        },
        "type": "codeScan",
        "cweId": 778
      }
    ]
  }
}

1	SecHub job UUID
2	Traffic light color of report - here YELLOW
3	Finding ID inside report
4	The name of the vulnerability in our case an `Absolute path traversal` where attackers could try to manipulate path input, so output could contain unwanted content/wrong file (e.g. a passwd file etc.)
5	The severity of this finding (will be used to calculate the traffic light color)
6	Entry point location in this case the Java class where the potential malicious input starts
7	Line number of entry point
8	Next call hierarchy element this is the next element of the call hierarchy, means what is called by entry point with potential malicious content as parameter. This is ongoing until last entry inside call hierarchy which is the so called "data sink"
9	Data sink location
10	Line number inside data sink
11	Source snippet
12	Relevant code part where the found vulnerability lies/could be exploited

15. System tests

This chapter describes the system test framework.

15.1. Purpose

Integration tests do rely on SecHub running in integration test mode, using one PDS server in integration test mode.

In this scenario, the integration test API can fetch internal meta data and is able to check correctness of the logic inside SecHub and also inside PDS. But it does not test real product execution - in the end it only uses mocked test scripts and static test data.

"The system tests are different to integration tests: Their main purpose is to test SecHub server(s) in combination with one or multiple PDS solutions in real live scenarios. This helps developers of PDS solutions to drastically reduce development time and to write automated tests without having to constantly test manually. To run the system tests a command line call in the OS shell or calling a unit test is sufficient.

The system test framework is designed, to make things easier for developers when testing SecHub / PDS. It provides as many defaults as possible, therefore it is usually not necessary to explicitly define much to have a running system test!

Try to only define the necessary minimum and let the system test framework do the rest.

It is also possible to use already running local servers (SecHub and/or PDS). For example: When you are developing a PDS solution you can start a local SecHub server in your IDE and run your tests only with start definitions for your PDS solution! This will increase speed, because the test will not spawn (and also not shutdown) the SecHub server instance!

15.2. Write a system test configuration file

This section describes the different parts inside the test configuration model.

System tests can be written in two ways:

Write a JUnit test and use methods provided by SystemTestAPI or
Write a JSON file and execute it with pds-tools.

It does not matter if you write the configuration directly in JSON or with the Java SystemTestFramework API - the underlying model is the same.

15.2.1. Script definitions

At many locations it is possible to define script execution steps (e.g. SecHub start/stop, PDS start/stop or at test preparation)

As the name indicates the system test will execute a script.

You can define the following:

path
arguments (optional)
envVariables (optional)
as a map
workingDirectory_(optional)_
process (optional)
- timeout (optional)
stageWaits (optional)
if true the stage will wait until this script is executed and has successfully finished.
The default is false - please set this to true only when really necessary. E.g. for a prepare
script which must be done before a next step.

15.2.1.1. Example snippet

"script" : {
            "path" : "./01-start-single-docker-compose.sh", (1)
            "arguments" : [ "alpine" ],(2)
            "envVariables" : { (3)
                "NAME1" : "value1",
                "NAME2" : "value2"
            }
            "workingDirectory" : "./../my-preparaton-folder1", (4)
            "process" : { (5)
              "timeOut" : {
                "amount" : 10, (6)
                "unit" : "MINUTES"
              }
            },
            "stageWaits" : false (7)
          }

1	The path for the executable script
2	Arguments (optional)
3	Environment variables (optional)
4	The working directory (optional, per default the working directory of system test call)
5	The process definition (optional). A user can define here some additional constraints for the created process (currently only a time out is supported).
6	Time out definition. When not defined, the default is 5 minutes. When a time out happens, the test will fail and the system test runtime will shutdown.
7	Defines if the current stage (e.g. test preparation) needs to wait for this script to be executed before next stage can be entered (e.g. test execution)

15.2.2. Comments

If you want to comment your configuration file setup, you have different options, depending how you use the framework.

15.2.2.1. PDS-Tools using a JSON configuration file

Here you have two options:

Use Javascript comments inside your JSON (the framework just ignores it) - for example: // I am comment or
use the comment attribute

15.2.2.2. JUnit tests

The SystemTestAPI configuration builder provides for many attributes a comment method as well. Those parts will be transformed to corresponding JSON attribute inside the model.

15.2.3. Variables

15.2.3.1. Environment variables

You can use environment variables inside the test configuration. The prefix for those variables is env.

For example, when you want to use the environment variable USER_NAME inside the configuration you reference it by ${env.USER_NAME}.

It is forbidden to use environment variables which have ${env.* as content!

15.2.3.2. Secret environment variables

When an error appears, the altered configuration model will be logged as JSON to make it easier to understand the problem.

But inside this output, all standard variables (environment, runtime, user variables) are revealed and will be shown in plain text.

To hide sensitive information you can use secret environment variables.

Secret environment variables are hidden in the log output. Use secret information for all sensitive information (secrets, passwords, credentials, personal information etc.).

It is forbidden to use secret environment variables which have ${env. or ${secretEnv. as content!

The prefix for those variables is secretEnv.

For example, when you want to use the environment variable USER_PASSWORD inside the configuration you reference it by ${secretEnv.USER_PASSWORD}.

When you are using secret environment variables but they are not defined at runtime, the system test framework will fail with an error about the missing variables.

But those variables can only be used in some locations:

15.2.3.2.1. Inside script environments

"script" : {
            "envVariables" : {
              "D_RESOLVED_SECRET" : "${secretEnv.USER_PASSWORD}" (1)
            },
            "path" : "./05-start-single-sechub-network-docker-compose.sh",
            "arguments" : [ "will-not-be-revealed-as-argument:${secretEnv.USER_PASSWORD}" ] (2)
          }

1	This works, at runtime the environment entry for the script will contain `USER_PASSWORD` inside variable `D_RESOLVED_SECRET`.
2	The secret will not be sent as an argument (for security reasons we only allow env entries)

15.2.3.2.2. Inside credentials

This is possible for tech users and also for admin credentials.

15.2.3.3. User variables

You can define your own variables inside the test configuration. The prefix for those variables is variables.

For example, if you have defined the variable uploadFolder inside the configuration you can reference it by ${variables.uploadFolder}.

15.2.3.4. Runtime variables

Some variables are created by the test framework and are available at runtime. You can use such variables inside the test configuration with the prefix runtime.

Variable name Description

currentTestFolder

Contains the absolute path to the folder for the current test inside the workspace. This will be calculated at runtime. This variable can only be used in test preparation script definitions or in runSecHubJob definitions!

additionalResourcesFolder

Containts the absolute path for a folder were additional resources can be found. For example a suite of preparation scripts which shall be used inside tests. If not explicit defined, the variable points to the location where the system tests has been started from

15.2.3.4.1. Workspace root

A workspace root for a system test means the root folder location where all data for the current system test is stored. This includes test folders and also the .runtime folder which contains information about processes and their output and error streams.

If not defined a temporary workspace folder will be created and can be used inside the configuration.

15.2.3.4.2. Test folders

The test folders are located inside the workspace root folder. Every executed test has its own sub folder.

Uploads for SecHub etc. must be done with relative paths from this location. You need to copy necessary parts for testing in a prepare step to the current test folder (see runtime variables tables for names etc.)

15.2.4. Default fallbacks

Following parts will be automatically defined in preparation phase when not defined explicit inside system test configuration model:

Type Scope Default value

Project id

Global

default-test-project

Profile id

Global

default-test-profile

SecHub url

Local

https://localhost:8443

SecHub admin user

Global

admin

SecHub admin token

Global

myTop$ecret!

PDS admin user

Global

admin

PDS admin token

Global

pds-apitoken

PDS tech user

Global

techuser

PDS tech user token

Global

pds-apitoken

PDS url

Local

https://localhost:8444

PDS wait for available

Local

true

SecHub wait for available

Global

true

Upload reference id

Global

default-ref

15.2.5. Setup

Inside the setup we define things necessary to setup our system test environment.

It is possible to run system tests locally and start & configure SecHub and PDS solutions automatically.

But it is also possible to use an existing real SecHub platform and run the defined tests using a remote setup. In this setup it is not possible to change any existing configuration. This means that executor configurations, users, projects, profiles etc. must all be configured on the server side by administrators before the start of the remote tests.

15.2.5.1. Local

When we run system tests in a local environment, all necessary settings and the setup will be done by the system testing framework. This means an administrator account is necessary to setup the system.

If not defined, the default credentials for integration test server will be used. If you do not define SecHub or PDS you can also use a running local servers (for example integration test servers) and only start the tests.

15.2.5.1.1. Start

With a script definition the start process for the SecHub server instance(s) can be defined.

15.2.5.1.2. Stop

With a script definition the stop process for the SecHub server instance(s) can be defined.

15.2.5.1.3. Configure

The configuration can contain one or more product executor configurations.

15.2.5.2. Remote

It is also possible to use an existing real SecHub platform and run the defined tests there. The configuration is not changed here - executor configurations, users, projects and profiles must be already configured by administrators. A remote setup does not require an administrative account, a normal user account which has access to the project is sufficient.

The framework does help you by setting fallback default values when you do not configure some parts. But if those fallbacks are in use, you must ensure that the remote environment can handle it.

An example: if you did not define a project inside the configuration, the default project name will be used at system test runtime. In this case you must have created a project with this name at your remote SecHub server before.

15.2.5.3. Example snippet

  setup" : {
    "local" : {
      "secHub" : {
        "admin" : { (1)
          "userId" : "${secretEnv.ADMIN_USERID}",
          "apiToken" : "${secretEnv.ADMIN_APITOKEN}"
        },
        "start" : [ {(2)
          "script" : {
            "path" : "./01-start-single-docker-compose.sh",
            "arguments" : [ "alpine" ]
          }
        } ],
        "configure" : {
          "executors" : [ {(3)
            "pdsProductId" : "NEW_FANCY_PRODUCT",
            "name" : "system-test-codescan-new-fancy"
          } ]
        },
        "stop" : [ {(4)
          "script" : {
            "path" : "./01-stop-single-docker-compose.sh"
          }
        } ]
      },
      "pdsSolutions" : [ {
        "name" : "new-fancy",(5)
        "url" : "${env.PDS_SERVER}",
        "start" : [ {
          "script" : {
            "path" : "./05-start-single-new-fancy-pds-docker-compose.sh",
            "arguments" : [ "2" ]
          }
        } ],
        "stop" : [ {
          "script" : {
            "path" : "./05-stop-single-new-fancy-pds-docker-compose.sh"
          }
        } ],
        "techUser" : {
          "userId" : "${secretEnv.PDS_USERID}",
          "apiToken" : "${secretEnv.PDS_APITOKEN}"
        }
      } ]
    }

1	defines SecHub administrator credentials to use for communication
2	starts the SecHub server by executing the script
3	configures executors and their products to use. It’s a good style to define a name here for the executor so restarting the system test will override always the same executor configuration. The scan type is automatically determined from meta information inside the PDS configuration file.
4	stop script to shutown the SecHub server
5	define a pds solution defintion for "new-fancy" (not existing, but would be inside a folder `new-fancy` below `sechub-pds-solutions folder`. In this example "new-fancy" would have "NEW_FANCY_PRODUCT" as product identifier inside its PDS configuration file.

15.2.6. Tests

Tests are defined at root level of the configuration file. It is possible to define multiple tests in one configurationfile.

15.2.6.1. Prepare

A test can have one or more preparation steps where following commands can be executed:

copy
Provides parameters "from" and "to" and enables users to copy folders or files to other locations
script
Provides the possibility to execute a script

15.2.6.2. Execute

The test execution phase can contain currently:

runSecHubJob
Here we can define the uploads and also the different scan types. When nothing is defined, the default reference identifier will be used, but it is also possible to define more complex data structures with different content and identifiers.

15.2.6.3. Assert

Asserts are done after the execution phase. Following steps are possible

secHubResult
Here we assert there is a SecHub result (JSON report) available (the job is automatically started by system test framework). We have following possibilities to check the content:
- hasTrafficLight
  Checks if the report has the expected traffic light
- containsStrings
  Asserts that the JSON report contains all of the defined strings inside the given array
- equalsFile Loads the given template report file and asserts that if the SecHub JSON report matches the template. Following place holders are supported to handle dynamic content:
  1. {sechub.jobuuid} - can be used at any location inside the report if there is the job uuid inside the report
  2. {*:n} - n represents the number for characters to be ignored.

15.2.6.4. Cleanup

A test can have one or more cleanup steps where following commands can be executed:

copy
Provides parameters "from" and "to" and enables users to copy folders or files to other locations
script
Provides the possibility to execute a script

15.2.6.5. Example snippet

"tests" : [ {
    "name" : "test1",
    "prepare" : [ {
      "copy" : { (1)
        "from" : "./../sechub-cli/src",
        "to" : "${runtime.currentTestFolder}/testsources/src"
      }
    } ],
    "execute" : {
      "runSecHubJob" : {
        "uploads" : [ {
          "sourceFolder" : "./testsources/src"  (2)
        } ],
        "codeScan" : { }
      }
    },
    "assert" : [ {
      "sechubResult" : { (3)
        "hasTrafficLight" : "YELLOW",
        "containsStrings" : {
          "values" : [ "MEDIUM" ]
        }
      }
    } ]
  } ]

1	copies sources to current test folder at subfolder "testsources"
2	uploads source folder (files which were previously copied)
3	assert that there is an ended SecHub job for this test where the SecHub report has traffic light `yellow` and contains at least one time a string "MEDIUM" inside JSON report.

15.3. Example configurations

15.3.1. Testing with already running integration test servers

This example is being used inside integration test SystemTestFrameworkIntTest.java.

{
  "variables" : {
    "testSourceUploadFolder" : "${runtime.currentTestFolder}/testsources"
  },
  "setup" : {
    "local" : {
      "secHub" : {
        "comment" : "We do not define start/stop here, because reuse running local SecHub server",
        "url" : "https://localhost:8443",
        "admin" : {
          "userId" : "${env.TEST_INTTEST_ADMIN_USERID}",
          "apiToken" : "${secretEnv.TEST_INTTEST_ADMIN_APITOKEN}"
        },
        "configure" : {
          "executors" : [ {
            "comment" : "This executor will be re-created by the framework",
            "pdsProductId" : "PDS_INTTEST_PRODUCT_CODESCAN",
            "name" : "system-test-codescan-exec1",
            "parameters" : {
              "product1.qualititycheck.enabled" : "true",
              "product1.level" : "A",
              "pds.mocking.disabled" : "true"
            }
          } ],
          "projects" : [ {
            "name" : "default-test-project",
            "whitelistedURIs" : [ "https://example.org/testproject1" ]
          } ]
        }
      },
      "pdsSolutions" : [ {
        "comment" : "We do not define start/stop here, because reuse running local PDS server",
        "name" : "PDS_INTTEST_PRODUCT_CODESCAN",
        "url" : "https://localhost:8444",
        "pathToPdsServerConfigFile" : "./../sechub-integrationtest/src/main/resources/pds-config-integrationtest.json",
        "techUser" : {
          "userId" : "${env.TEST_INTTEST_PDS_TECHUSER_USERID}",
          "apiToken" : "${secretEnv.TEST_INTTEST_PDS_TECHUSER_APITOKEN}"
        },
        "admin" : {
          "userId" : "${env.TEST_INTTEST_PDS_ADMIN_USERID}",
          "apiToken" : "${secretEnv.TEST_INTTEST_PDS_ADMIN_APITOKEN}"
        }
      } ]
    }
  },
  "tests" : [ {
    "name" : "test1",
    "prepare" : [ {
      "script" : {
        "path" : "./prepare-inttest-copy-codescan-medium-findings.sh",
        "workingDirectory" : "./src/test/resources/additional-resources/preparation",
        "arguments" : [ "${variables.testSourceUploadFolder}" ],
        "process" : {
          "timeOut" : {
            "amount" : 5,
            "unit" : "MINUTES"
          }
        }
      }
    } ],
    "execute" : {
      "runSecHubJob" : {
        "uploads" : [ {
          "sourceFolder" : "${variables.testSourceUploadFolder}"
        } ],
        "codeScan" : { }
      }
    },
    "assert" : [ {
      "sechubResult" : {
        "hasTrafficLight" : "YELLOW",
        "equalsFile" : {
          "path" : "./src/test/resources/additional-resources/expected-output/sechub-result1.json"
        },
        "containsStrings" : {
          "values" : [ "MEDIUM", "ERROR", "WARNING", "INFO", "SUCCESS", "integration test code only!" ]
        }
      }
    } ]
  } ]
}

15.3.2. A full blown example

This example is just an overview what steps could be configured at all. It is not used in any real world scenario but only for documentation.

{
  "variables" : {
    "var1" : "1",
    "custom_data_txt" : "${env.FROM_OUTSIDE}/subfolder1/data.txt"
  },
  "setup" : {
    "local" : {
      "comment" : "This is a local setup - it does not use existing SecHub infrastructure, instead it does build up all by its own",
      "secHub" : {
        "comment" : "If there are variants defined, the further defined tests will be run with all of those variants by the framework! ADDITION: we could introduce here start/stop step like in pds solutions to build the sechub container from scratch as well (with different jdks etc.)",
        "admin" : {
          "userId" : "${secretEnv.SECHUB_ADMIN_USERID}",
          "apiToken" : "${secretEnv.SECHUB_ADMIN_TOKEN}"
        },
        "start" : [ {
          "script" : {
            "path" : "./01-start-single-docker-compose.sh",
            "arguments" : [ "alpine" ],
            "process" : {
              "timeOut" : {
                "amount" : 5,
                "unit" : "MINUTES"
              }
            }
          }
        } ],
        "configure" : {
          "comment" : "Here we can configure sechub. At least one executor entry is mandatory (we must know which products shall be inside the profile). Projects is optional. If not defined only a default project and a default profile for the given executors will be automatically created and used.",
          "executors" : [ {
            "pdsProductId" : "GOSEC",
            "parameters" : {
              "gosec.additional.parameter" : "${variables.custom_data_txt}",
              "pds.reuse.sechubstorage" : "false (overrides default)"
            },
            "baseURL" : "https://gosec_pds.example.com:8443"
          } ],
          "projects" : [ {
            "comment" : "The profile can define a profile. When nothing is defined, the default will be 'default-test-profile'",
            "name" : "a-project-id-when-not-default-used",
            "profiles" : [ "a-defined-profile-when-not-default-used" ]
          } ]
        },
        "stop" : [ {
          "comment" : "One single step to finally stop the gosec PDS solution when tests have been done.",
          "script" : {
            "path" : "./01-stop-single-docker-compose.sh",
            "process" : {
              "timeOut" : {
                "amount" : 5,
                "unit" : "MINUTES"
              }
            }
          }
        } ]
      },
      "pdsSolutions" : [ {
        "comment" : "Test solution1, the scan types etc. cannot be defined, because runtime loads all meta information from config file. Basedir is optional, normally calculated automatically by name",
        "name" : "gosec",
        "baseDir" : "${env.base_dir}/pds-solutions/gosec",
        "techUser" : {
          "userId" : "${secretEnv.GOSEC_PDS_TECHUSER_USERID}",
          "apiToken" : "${secretEnv.GOSEC_PDS_TECHUSER_TOKEN}"
        },
        "admin" : { },
        "start" : [ {
          "comment" : "In first start step, we build the image",
          "script" : {
            "path" : "./01-build-the-image.sh ${variables.myContainer.values}",
            "workingDirectory" : "./",
            "process" : {
              "timeOut" : {
                "amount" : 5,
                "unit" : "MINUTES"
              }
            }
          }
        }, {
          "comment" : "As last start step... start the gosec PDS solution",
          "script" : {
            "path" : "./05-start-container.sh",
            "process" : {
              "timeOut" : {
                "amount" : 5,
                "unit" : "MINUTES"
              }
            }
          }
        } ],
        "stop" : [ {
          "comment" : "One single step to finally stop the gosec PDS solution when tests have been done.",
          "script" : {
            "path" : "./01-build-the-image.sh ${variables.myContainer.values}",
            "workingDirectory" : "./",
            "process" : {
              "timeOut" : {
                "amount" : 5,
                "unit" : "MINUTES"
              }
            }
          }
        } ]
      } ]
    },
    "remote" : {
      "comment" : "This is a remote setup - we use an existing and configured SecHub cluster/instance",
      "secHub" : {
        "url" : "https://sechub.example.com:8443",
        "user" : {
          "userId" : "testuser",
          "apiToken" : "${env.SYSTEM_TEST_USER_TOKEN}"
        }
      }
    }
  },
  "tests" : [ {
    "comment" : "This test does a git checkout of a simple gosec application. After this we ensure the sechub result json file is as expected.",
    "name" : "Test1",
    "prepare" : [ {
      "script" : {
        "comment" : "The script call here would call the script inside the 'tests' subfoler of the solution",
        "path" : "./../tests/checkout-simple-go-project-withouth-sechub-json.sh ${runtime.currentTestFolder}/checkout",
        "process" : {
          "timeOut" : {
            "amount" : 5,
            "unit" : "MINUTES"
          }
        }
      }
    }, {
      "script" : {
        "comment" : "Just another script call as an example for possibility of multiple scripts + an environment variable from 'outside'...",
        "path" : "${env.FROM_OUT_SIDE}/do-something-else.sh",
        "process" : {
          "timeOut" : {
            "amount" : 5,
            "unit" : "MINUTES"
          }
        }
      }
    } ],
    "execute" : {
      "comment" : "This part can be defined only once. It describes what is executed",
      "runSecHubJob" : {
        "comment" : "If a project is defined, it will be used, otherwise always 'default-test-project' is used as default",
        "project" : "a-project-id-when-not-default-used",
        "uploads" : [ {
          "comment" : "Here we can define either binaries or sources to upload - we define the folders, framework will create tars/zips automatically. When no upload reference id is defined, default-ref is used as default",
          "sourceFolder" : "./checkout/sources",
          "referenceId" : "an-upload-reference-id"
        } ],
        "codeScan" : {
          "use" : [ "an-upload-reference-id" ]
        },
        "secretScan" : {
          "use" : [ "an-upload-reference-id" ]
        }
      }
    },
    "assert" : [ {
      "sechubResult" : {
        "hasTrafficLight" : "GREEN",
        "equalsFile" : {
          "comment" : "At execution time, the different job uuids inside the two reports may are handled automatically. The given file is just a normal report but dynamic parts can be marked with parameters.",
          "path" : "./../tests/expected-sechub-json.json"
        },
        "containsStrings" : {
          "comment" : "Checks if the sechub result file contains the given strings.",
          "values" : [ "CWE-89", "SQL-Injection", "Improper" ]
        }
      }
    } ]
  } ]
}

15.4. How to execute system tests

15.4.1. With PDS tools

As a first step, download the latest release of pds-tools from https://github.com/mercedes-benz/sechub/releases.

Execute: java -jar sechub-pds-tools-cli-<version>.jar systemTest --file ${pathToTestConfigurationJson} --pds-solutions-rootfolder ${pathToPDSSolutions}

15.4.2. JUnit tests

Just execute the Junit test from your IDE.

15.5. Behavior

15.5.1. Stages

We have different stages:

Setup
Test
Shutdown

Every stage can contain different steps inside. For example: The setup phase contains start scripts from SecHub and/or PDS solutions.

Before a stage can be left and another is started, a check is done, if there is a need to wait for any processes to be finished. When a script of the stage times out in mean time, the framework will stop with a failure message.

If not explicit defined, the test framework automatically uses dedicated defaults for script steps inside the stage, but it is possible to change the defaults inside the configuration. Here is an example:

{
  "script" : {
    "path" : "./01-start-single-docker-compose.sh",
    "process" : {
        "timeOut" : { (1)
           "amount" : 2,  (2)
           "unit" : "minutes", (3)
        }
        "stageWaits" : true (4)
    }
  }
}

1 Defines the timeout before the process will be forcibly terminated. The default is 5 Minutes When a timeout happens, the system test will fail!

2 Accepted amount of time before timeout happens

3 Time unit, can be milliseconds, seconds, minutes, hours

When stageWaits is true the stage will wait for the process to be done. The default is false.

The test preparation stage will automatically wait for defined PDS solutions and SecHub server to be up and running - means:

You only need to setup stageWaits to true if you have written a special script which must be done (and does automatically end) before a stage shall be left.

In this case the stage will wait until the script has finished or times out.

You do not need to define stageWait in test preparation steps: For those steps the framework will always wait before the test is executed.

15.5.2. Auto configuration

15.5.2.1. Remote run

At a remote run, the configuration of the remote exissting SecHub and PDS environments will not be changed!

There is no auto configuration phase on a remote run. All elements (profiles, executors, project, etc. must all be configured before the test is run.

15.5.2.2. Local run

15.5.2.2.1. Projects

The defined projects will be created automatically. If a project exists with the defined name (e.g. when a system test is restarted locally) the existing project will be deleted!

15.5.2.2.2. Executor configurations

Every system test start will just create new executor configurations.

15.5.2.2.3. Profiles

The defined profiles inside test configuration model will be created and connected with the created executor configurations. If a profile does already exist with the defined project id, the existing one will be deleted.