About SecHub

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

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

So you still need an existing security infrastructure behind SecHub !

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

You can get more information about from SecHub web page .

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

About documentation

This documentation is part of SecHub.

Key Value Information

LICENSE

MIT License

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

Documentation version: Server 1.6.0 - Build date: 20240226101315

This architecture documentation is based on arc42 template.

About arc42

arc42, the Template for documentation of software and system architecture.

By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.

Template Revision: 7.0 EN (based on asciidoc), January 2017

© We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.


1. Introduction and Goals

1.1. About

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

  • underlying business goals, essential features and functional requirements for the system,

  • quality goals for the architecture,

  • relevant stakeholders and their expectations

1.2. What is SecHub?

SecHub is an easy to use security scan integration for developers to provide security tooling as a SecDevOps service. It can be used by build servers and other tools.

Independent from security products:

The user - for example a developer who uses SecHub for build integration - has no intention which security product is being used to determine security leaks.

So security products used by SecHub server instance(s) can change on time but usage and configuration of SecHub will not change at all!

1.3. Requirements Overview

1.3.1. Non functional requirements

1.3.1.1. Scalable

SecHub server must be able to scale vertically and horizontally.

SecHub itself is build to be ready for usage inside Kubernetes clusters, so main bottle neck will normally not be SecHub but maybe used security products.
1.3.1.2. High available

SecHub server must be able to handle new job requests at any time so at least jobs must must be accepted and added to queue.

1.3.1.3. Resilient
  • Security product connection failure
    One failing security product shall not lead in a non working SecHub "state" but produce a dedicated entry in scan results!

  • The system shall be still working on errors

1.3.1.4. Stable
  • API and configuration syntax are stable and do NOT change in a breaking way

1.3.1.5. Acceptable

SecHub shall be accepted by developers. So it must be easy to use, to embed and also …​ just work!

1.3.2. Functional requirements

  • One single and easy to use API / client to secure

  • Easy to integrate new security products

More and also more detailed functional requirements can be found in issue tracker system

1.4. Quality Goals

  • Documentation shall be always up-to-date

  • …​ TBD

1.5. Stakeholders

Role/Name Contact Expectations

Product Owner

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

User

A person who wants to execute scans by SecHub.
Will expect: easy to use, "It works", not too much false positives

Administrator

A person who installs SecHub server and does maintenance of target security products. Also responsible for onboarding of projects and users.
Will expect: simple installation, easy to configure, reliable, easy to maintain

External Systems

Another system which will call the REST API or the SecHub client. E.g. Build Servers like Jenkins.
Will expect: Always available

2. Architecture Constraints

2.1. About

2.1.1. Content

Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

2.1.2. Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

2.1.3. Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

2.2. Domain communication

Direct communication between different domains may not appear - to avoid the "big ball of mud", even when we have no real micro-service landscape at the moment and SecHub is a self-contained-system.

For more information please refer to Domain Driven Design

2.2.1. DB constraints

As long as there is no really need there will be only ONE database instance across the SecHub system!!!!!

Even when the spring boot application is a single one and shares a database every domain has only access to dedicated tables and does not share its tables across other domains! This includes relation ships between tables as well.

This is to prevent the database becoming part of a "hidden shared kernel" /"central bottleneck". If we decide to transform sechub-server from self-contained-system into single separate deployment units we can achieve this without too much effort/impact.

Domain Table Description

SCHEDULE

SCHEDULE_SECHUBJOB

Represents a SecHub Job instance

SCAN

SCAN_RESULT

Contains the collected scan result from all scan product. Shall represent entity ScanResult

SCAN

SCAN_DATA

Does contain (intermediate) information from job scans etc.

…​

…​

…​

For more information please refer to Domain Driven Design

3. System Scope and Context

3.1. About

3.1.1. Content

System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).

3.1.2. Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

3.2. Business Context

3.2.1. Overview

Diagram
Figure 1. Overview business context

3.3. Technical Context

Diagram
Figure 2. Overview business context

3.3.1. Web scanner

A scanner used for automated penetration testing on given sites

We support currently:

  • Netsparker

3.3.2. Code scanner

A scanner used for automated static code analysis

We support currently:

  • Checkmarx

3.3.3. Infrastructure scanner

A scanner used for automated penetration testing on given infrastructure

We support currently:

  • Nessus

We got the problem that Nessus has terminated their REST API and only supports a REST API when ordering another product. So currently it’s difficulat to support NESSUS directly.

4. Solution Strategy

4.1. About

4.1.1. Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture. These include

  • technology decisions

  • decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern

  • decisions on how to achieve key quality goals

  • relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

4.1.2. Motivation

These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules.

4.1.3. Form

Keep the explanation of these key decisions short.

Motivate what you have decided and why you decided that way, based upon your problem statement, the quality goals and key constraints.

4.1.4. Solutions

Quality Goal Scenario Solution approach Link to details

Server development shall be easy to maintain and developers shall have experience with the language and frameworks

All

Spring Boot, Java

Users shall have a convenient and simple way to start scans

All

We provide not only a REST API but provide a convenient CLI client which just needs a JSON config file

Client shall be small, fast and usable on many platforms without much effort to install

All

Go client

Developers shall be able to test and develop server parts without an existing infrastructure (means no security products installed etc)

Development

Mock profile and also Mocked Adapters for every supported product

Developers shall be able to write adapters without starting server

Development

Adapters are "dumb" and can be started as simple java application.

For corporate continous-integration scans we need a scalable solution which can be clustered

Cluster installation

With SpringBoot and DDD we ensure we can run server components inside Kubernetes

People or smaller companies shall be able to install SecHub without Kubernetes

Single installation

Server software will be always startable as a simple jar as well (done by Spring Boot Jar)

Developers shall be able to start SecHub without Kubernetes

Development

Server software will be always startable as a simple jar as well (done by Spring Boot Jar)

SecHub sserver integration tests shall be possible without available products, PostgreSQL or Kubernetes

Development

Server software will be always startable as a simple jar as well (done by Spring Boot Jar), we provide also different profiles for normal database (postgres) and in memory DB (h2), we provide a profile for mocked products

We need a reliable database which is mature, stable and good documented

Cluster installation, Single installation, Development

We will provide postgres

We must avoid "big ball of mud" in development and also be able to separate server parts to smaller deployments easily in future (when needed)

Development

Domain driven design is choosen to support this. On the other side we do not want to have a large event bus system (e.g. KAFKA), because not really necessary at the beginning (and maybe never).

So as a KISS approach we provide a self contained system but in conjunction with a very simple DDD implementation:
We create and use a wrapper API for events, start with implementation by simple Observer pattern inside same JVM, so can be replaced later by something else (e.g. a KAFKA implementation). Direct communication between different domains is forbidden, only events are allowed. This is tested by automated tests.

see DomainMessageService.java

We want to have many integration tests which are easy to read, maintain, make fun to write, have reduced test code and using server nearly as done in production.

It shall be possible to execute the integration tests to mocked or even to real products. Changes in server structure or even in code, shall does not enforce changes to tests, but only to test framework implementation.

Development

We implement a specialized integration-test framework which provides a DSL like, fluent API which is able to test again a running test server instance. We implement spring profiles for real-products and mocked-products and a integration-test profile as well on server side.

We want to have an agile, living documentation, which is matching to source code and a diff can be easily done by GIT

Development

We use AsciiDoc and checkin documenteation together inside one GIT repository

see https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

We want to have a way to provide special scan configurations in a dynamic way

Deployment

We provide a JSON based scan configuration where different provider meta information can be defined. Dedicated providers can use this information and handle dynamic configuration - e.g. based on name of SecHub project.

see https://github.com/mercedes-benz/sechub/issues/127 ,ScanMappingConfigurationService class or description inside technical documentation.

5. About

5.1. Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, datas structures, …) as well as their dependencies (relationships, associations, …)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

5.2. Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

5.3. Form

The building block view is a hierarchial collection of black boxes and white boxes and their descriptions.

6. Building Block View

6.1. SecHub Overall System

Overview Diagram

Diagram
Figure 3. Overview sechub overall

7. Runtime View

7.1. About

7.2. Content

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

  • important use cases or features: how do building blocks execute them?

  • interactions at critical external interfaces: how do building blocks cooperate with users and neighbouring systems?

  • operation and administration: launch, start-up, stop

  • error and exception scenarios

The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevancy. It is not important to describe a large number of scenarios. You should rather document a representative selection.

7.3. Motivation

You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakholders that are less willing or able to read and understand the static models (building block view, deployment view).

7.4. Form

There are many notations for describing scenarios, e.g.

  • numbered list of steps (in natural language)

  • activity diagrams or flow charts

  • sequence diagrams

  • BPMN or EPCs (event process chains)

  • state machines

  • …​

7.5. Use cases

7.5.1. Overview about usecase groups

7.5.1.1. Anonymous

All these usecases handling anonymous access.

7.5.1.4. User profile

User actions belonging to their profiles

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

Event overview

"Overview of events happening at usecase UC_SIGNUP

Involved messages

Steps

Nr Title Role(s) Next Description

1

Rest API call

2

Rest api called to register user. Normally done by user itself

2

Persistence

3

Valid self registration input will be persisted to database.

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.

4

Email to admin

A notification is send per email to admins that a new user signup has been created and waits for acceptance.

7.5.3. UC_002-Admin lists open user signups

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

All self registrations are returned as json

7.5.4. UC_003-Admin applies self registration

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

Event overview

"Overview of events happening at usecase UC_ADMIN_ACCEPTS_SIGNUP

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator accepts a persisted self registration entry by calling rest api

2

Create user and send events

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

3

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

4

Give user access

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

7.5.5. UC_004-Admin lists all users

An administrator downloads a json file containing all user ids

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

All userids of sechub users are returned as json

2

Service call

ROLE_SUPERADMIN

All userids of sechub users are returned as json

7.5.6. UC_005-User creates 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

Steps

Nr Title Role(s) Next Description

1

Authenticated REST call

ROLE_SUPERADMIN, ROLE_USER

2

2

Persistence and result

Persist a new job entry and return Job UUID

7.5.7. UC_006-User uploads source code

The source code must be a valid zipfile.

Steps

Nr Title Role(s) Next Description

1

Authenticated REST call

ROLE_SUPERADMIN, ROLE_USER

2

2

Try to find project and upload sourcecode as zipfile

ROLE_USER

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

7.5.8. UC_007-User approves 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

Steps

Nr Title Role(s) Next Description

1

Authenticated REST call

ROLE_SUPERADMIN, ROLE_USER

2

2

Try to find job annd update execution state

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

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

Steps

Nr Title Role(s) Next Description

1

Scheduling

2

Fetches next schedule job from queue and trigger execution.

2

Execution

3, 4

Triggers job execution - done parallel, but with synchronous domain communication (to wait for result).

4

Store admin job info

5

Fetches event about started job and store info in admin domain.

5

Update admin job info

Deletes store info in admin domain when job is done.

7.5.10. UC_009-User checks sechub job state

Steps

Nr Title Role(s) Next Description

1

Authenticated REST call

ROLE_SUPERADMIN, ROLE_USER

2

2

Try to find project and fail or return job status

7.5.11. UC_010-User downloads sechub job report

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.

Steps

Nr Title Role(s) Next Description

1

REST API call to get JSON report

ROLE_SUPERADMIN, ROLE_USER

3

2

REST API call to get HTML report

ROLE_SUPERADMIN, ROLE_USER

3

3

Resolve scan report result

7.5.12. UC_011-User starts scan by client

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

It does automate following usecases:

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.

Steps

Nr Title Role(s) Next Description

1

create new job

ROLE_SUPERADMIN, ROLE_USER

2, 3

2

upload binaries

ROLE_SUPERADMIN, ROLE_USER

2

2

upload sourcecode

ROLE_SUPERADMIN, ROLE_USER

3

3

approve job

ROLE_SUPERADMIN, ROLE_USER

4

4

download job report and traffic light

ROLE_SUPERADMIN, ROLE_USER

4

4

get job status

ROLE_SUPERADMIN, ROLE_USER

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

Steps

Nr Title Role(s) Next Description

1

Rest call

2

User opens url by browser

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 …​

3

Update auth data

4

Inform user about api token change done

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator creates a new project by calling rest api

2

Create project

ROLE_SUPERADMIN

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

7.5.15. UC_014-Admin lists all projects

An administrator downloads a json file containing all project ids

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

All project ids of sechub are returned as json

7.5.16. UC_015-Admin assigns user to project

An administrator assigns an user to an existing sechub project.

Event overview

"Overview of events happening at usecase UC_ADMIN_ASSIGNS_USER_TO_PROJECT

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator does call rest API to assign user

2

Assign user

ROLE_SUPERADMIN

2

The service will add the user to the project. If user does not have ROLE_USER it will obtain it

2

Update schedule authorization parts

3

3

Update scan authorization parts

4

4

Roles changed in auth

Authorization layer adds ROLE_USER

7.5.17. UC_016-Admin unassigns user from project

An administrator unassigns an user from a sechub project.

Event overview

"Overview of events happening at usecase UC_ADMIN_UNASSIGNS_USER_FROM_PROJECT

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator does call rest API to unassign user

2

Update authorization parts

2

2

Unassign user

ROLE_SUPERADMIN

2

The service will remove the user to the project. If users has no longer access to projects ROLE_USER will be removed

2

Update authorization parts

4

4

Roles changed in auth

Authorization layer removes ROLE_USER

7.5.18. UC_017-Admin shows user details

An administrator downloads a json file containing json containing user details

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Json returned containing details about user and her/his projects

2

Service fetches user details.

ROLE_SUPERADMIN

The service will fetch user details for given user id

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

User will be deleted

2

Service deletes user.

ROLE_SUPERADMIN

3, 4

The service will delete the user with dependencies and triggers asynchronous events

3

revoke user from schedule access

3

3

revoke user from schedule access

4

4

Delete user access

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

5

Inform user that the account has been deleted by administrator

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

Steps

Nr Title Role(s) Next Description

1

Rest API call

ROLE_SUPERADMIN

2

Rest api called to remove user signup

2

Persistence

ROLE_SUPERADMIN

Existing signup will be deleted

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Project will be deleted

2

Service deletes projects.

ROLE_SUPERADMIN

3, 4, 5, 6, 7

The service will delete the project with dependencies and triggers asynchronous events

3

Inform sechub admins that project has been deleted

4

4

Inform project owner that the project has been deleted

5

5

Inform users that the project has been deleted

6

6

Update authorization parts - remove entries for deleted project

7

7

revoke any scan access from project

8

8

delete all project scan data

7.5.22. UC_021-Admin shows project details

An administrator downloads a json file containing json with project details

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Json returned containing details about project

2

Service fetches project details.

ROLE_SUPERADMIN

The service will fetch project details

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

White list will be updated

2

Update project

ROLE_SUPERADMIN

The service will update the Project whitelist.

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator lists all running jobs by calling rest api

2

Fetchjob information from database

Fetches stored job information from administration database.

7.5.25. UC_024-User requests new API token

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.

Steps

Nr Title Role(s) Next Description

1

Rest API call

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

7.5.26. UC_025-Admin shows scan logs for project

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

Steps

Nr Title Role(s) Next Description

1

REST API call to get JSON list

ROLE_SUPERADMIN

2

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

Steps

Nr Title Role(s) Next Description

1

REST API call to zip file containing full scan data

ROLE_SUPERADMIN

2

2

Collect all scan data

ROLE_SUPERADMIN

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

User will be granted admin rights

2

Service grants user admin rights.

ROLE_SUPERADMIN

3, 4

The service will grant user admin righs and triggers asynchronous events

3

Inform user that he/she became administrator

4

4

Inform SecHub admins that another user became administrator

7.5.29. UC_028-Admin revokes admin rights from an admin

An administrator revokes existing admin rights from another administrator.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Admin rights will be revoked from admin

2

Service revokes user admin rights.

ROLE_SUPERADMIN

3, 4

The service will revoke user admin righs and triggers asynchronous events

3

Inform user about loosing administrator rights

4

4

Inform SecHub admins that another admin is no longer admin

7.5.30. UC_029-Admin lists all admins

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

All userids of sechub administrators are returned as json

2

Service call

ROLE_SUPERADMIN

All userids of sechub administrators are returned as json

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

Event overview

"Overview of events happening at usecase UC_ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator wants to stop (pause) scheduler job processing

2

Service call

ROLE_SUPERADMIN

2

Sends request to scheduler domain to disable scheduler job processing

2

Service call

ROLE_SUPERADMIN

3

Sends request to scheduler to send updates about current status.

3

Disable processing

4

Disables job processing inside scheduler database

4

Inform SecHub admins that scheduler job processing has been disabled

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

Event overview

"Overview of events happening at usecase UC_ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator wants to start (unpause) scheduler job processing

2

Service call

ROLE_SUPERADMIN

3

Sends request to scheduler domain to enable scheduler job processing

3

Enable processing

4

Enables job processing inside scheduler database

4

Inform SecHub admins that scheduler job processing has been enabled

7.5.33. UC_032-Admin get scheduler status

An administrator wants to update information about scheduler status

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

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

7.5.34. UC_033-Admin lists status information

An administrator fetches current known status information about sechub

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

Administrator wants to list status information about sechub

7.5.35. UC_034-Admin cancels a job

Administrator does cancel a job by its Job UUID

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Triggers job cancellation request, owners of project will be informed

2

Cancel job

3

Will trigger event that job cancel requested

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

4

Inform user that her/his job has been canceled

7.5.36. UC_035-User defines mock data configuration for project

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

Steps

Nr Title Role(s) Next Description

1

REST API call to define mock configuration byJSON data

ROLE_SUPERADMIN, ROLE_USER

2

2

Service call to store mock configuration

7.5.37. UC_036-User retrieves mock data configuration for project

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"
  }
}

Steps

Nr Title Role(s) Next Description

1

REST API call to get JSON data

ROLE_SUPERADMIN, ROLE_USER

2

2

Service call to get JSON data

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator wants to update a mapping configuration

2

Service call

3

Services updates data in database and sends event

3

Event handler

4

Receives mapping configuration change event

4

Service call

5

Updates scan mapping in DB

5

Trigger service

6

Checks periodically for updates in scan configuration

6

Service call

Checks if current mappings in DB lead to a new scan configuration.

7.5.39. UC_038-Admin fetches mapping configuration

An administrator fetches mapping configuration by its ID.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator wants to fetch a mapping configuration

2

Service call

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

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

Steps

Nr Title Role(s) Next Description

1

REST API call

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

7.5.41. UC_040-Admin checks server version

An administrator checks the current SecHub server version. Only administrators are able to check the server version, because knowing the exact server version makes it easier for penetration tester or attacker to attack the system.

Steps

Nr Title Role(s) Next Description

1

REST API Call

ROLE_SUPERADMIN

Administrator wants to get the server version of SecHub

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

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Triggeres job restart (soft)

2

Restart job

3

Will trigger event that job restart (soft) requested

3

Inform sechub admins when job restart was canceled

4

4

Inform sechub admins when job has been restarted

5

5

Inform sechub admins when job results have been purged

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

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Triggeres job restart (hard)

2

Restart job

3

Will trigger event that job restart (hard) requested

3

Inform sechub admins when job restart was canceled

3

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

3

Try to rstart job (hard)

4

When job is found, a restart will be triggered. Existing batch jobs will be terminated

4

Inform sechub admins when job has been restarted

5

5

Inform sechub admins when job results have been purged

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

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

2

Inform sechub admins that new scheduler job has been started

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

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

Steps

Nr Title Role(s) Next Description

1

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

ROLE_SUPERADMIN, ROLE_USER

7.5.46. UC_045-User unmarks existing false positive definitons

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.

Steps

Nr Title Role(s) Next Description

1

REST API call to remove existing false positive definition

ROLE_SUPERADMIN, ROLE_USER

7.5.47. UC_046-User fetches false positive configuration of project

Steps

Nr Title Role(s) Next Description

1

REST API call to fetch existing false positive configuration of project

ROLE_SUPERADMIN, ROLE_USER

7.5.48. UC_047-Admin creates an executor configuration

An administrator creates an executor a new configuration entry.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator adds a new product executor configuration by calling REST API

2

Service call

ROLE_SUPERADMIN

Service creates a new product executor configuration

7.5.49. UC_048-Admin deletes executor configuration

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator deletes an existing product executor configuration by calling REST API

2

Service call

ROLE_SUPERADMIN

Service deletes an existing product executor configuration by its UUID

7.5.50. UC_049-Admin fetches executor configuration list

An administrator fetches executor configuration list which contains all executor configurations

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

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

2

Service call

ROLE_SUPERADMIN

Service fetches data and creates a list containing all executor configurations

7.5.51. UC_050-Admin fetches executor configuration

An administrator fetches one explicit executor configuration by its uuid.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

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

2

Service call

ROLE_SUPERADMIN

Service reads setup information for an existing product executor configuration

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

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

2

Service call

ROLE_SUPERADMIN

2

Service updates existing executor configuration

2

Service call

ROLE_SUPERADMIN

Service updates existing executor configuration

7.5.53. UC_052-Admin creates an execution profile

An administrator creates an execution profile

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator adds a new product execution profile by calling REST API

2

Service call

ROLE_SUPERADMIN

Service creates a new product executor configuration

7.5.54. UC_053-Admin deletes execution profile

An administrator deletes execution profile

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator deletes an existing product execution profile by calling REST API

2

Service call

ROLE_SUPERADMIN

Service deletes an existing product execution profile by its profile id

7.5.55. UC_054-Admin updates execution profile

An administrator updateds dedicated execution profile

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

Administrator updates existing profile by calling REST API

7.5.56. UC_055-Admin fetches execution profile

An administrator fetches details about an execution profile

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

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

2

Service call

ROLE_SUPERADMIN

Service reads setup information for an existing product executor configuration

7.5.57. UC_056-Admin fetches execution profile list

An administrator fetches execution profile list

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

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

2

Service call

ROLE_SUPERADMIN

Service fetches data and creates a list containing all executor profiles

7.5.58. UC_057-Admin assigns execution profile to project

An administrator assigns an execution profile to an existing project

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator adds profile relation to project by calling REST API

2

Service call

ROLE_SUPERADMIN

Services creates a new association between project id and profile

7.5.59. UC_058-Admin unassigns execution profile from project

An administrator unassigns an execution profile from a projects.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator removes profile relation to project by calling REST API

2

Service call

ROLE_SUPERADMIN

Services deletes an existing association between project id and profile

7.5.60. UC_059-Update project metadata

Administrator updates project meta data inside SecHub.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

MetaData will be updated

2

Update project

ROLE_SUPERADMIN

The service will update the Project metadata.

7.5.61. UC_060-Admin changes owner of a project

An administrator changes the owner of an existing sechub project.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator does call rest API to set new project owner

2

Change project owner

ROLE_SUPERADMIN

4

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.

4

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

7.5.62. UC_061-Admin changes project description

An administrator changes the project description

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Changes project description. Json returned containing details about changed project

2

Service changes project description.

ROLE_SUPERADMIN

The service will change project description.

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

7.5.63.2. Conststraints
7.5.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

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

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Admin does call REST API to change project access level

2

Change access level

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

3

Event handler

4

Receives change project access level event

4

Event handler

Receives change project access level event

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

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

User emaill address will be changed

2

Service updates user email address.

ROLE_SUPERADMIN

3

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

3

Inform user that the email address has been changed

7.5.65. UC_064-Admin fetches auto cleanup configuration

An administrator feches current auto cleanup configuration.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator fetches auto cleanup configuration

2

Fetches auto cleanup config

Fetches auto cleanup configuration from database

7.5.66. UC_065-Admin updates auto cleanup configuration

An administrator changes auto cleanup configuration.

Event overview

"Overview of events happening at usecase UC_ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Administrator changes auto cleanup configuration

2

Updates auto cleanup config

3, 4, 5

Updates auto cleanup configuration as JSON in database and sends event

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

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

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

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

Steps

Nr Title Role(s) Next Description

1

Scheduling

2

Checks for parts to auto clean.

2

Delete old data

deletes old job information

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

Steps

Nr Title Role(s) Next Description

1

Scheduling

2

Checks for parts to auto clean.

2

Delete old data

deletes old job information

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

Steps

Nr Title Role(s) Next Description

1

Scheduling

2

Checks for parts to auto clean.

2

Delete old data

deletes old job information

7.5.70. UC_069-User uploads binaries

The binaries must be inside a valid tar file.

Steps

Nr Title Role(s) Next Description

1

Authenticated REST call

ROLE_SUPERADMIN, ROLE_USER

2

2

Try to find project and upload binaries as tar

ROLE_USER

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

7.5.71. UC_070-User downloads job report in SPDX format

Only SPDX JSON is supported.

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

Steps

Nr Title Role(s) Next Description

1

REST API call to get SPDX JSON report

ROLE_SUPERADMIN, ROLE_USER

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

Steps

Nr Title Role(s) Next Description

1

get pageable list of jobs in project

ROLE_SUPERADMIN, ROLE_USER

2

2

Assert access by service and fetch job information for user

7.5.73. UC_072-Admin shows user details for email address

An administrator fetches user details for an email address.

Steps

Nr Title Role(s) Next Description

1

Rest call

ROLE_SUPERADMIN

2

Json returned containing details about user and her/his projects

2

Service fetches user details.

ROLE_SUPERADMIN

The service will fetch user details for given user email address

7.6. Rest API documentation

7.6.1. Overview

7.6.1.1. Anonymous

All these usecases handling anonymous access.

7.6.1.4. User profile

User actions belonging to their profiles

7.6.2. Check if the server is alive and running.

7.6.2.1. HEAD variant

Definition

Table 1. 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)

7.6.2.2. GET variant

Definition

Table 2. 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)

7.6.3. Admin lists all users

REST API for usecase UC_004-Admin lists all users

Definition

Table 3. 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"]

7.6.4. Admin assigns user to project

Definition

Table 4. General request information
Value

Path

/api/admin/project/{projectId}/membership/{userId}

Method

POST

Status code

200 OK

Path parameters

Table 5. 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)

7.6.5. Admin unassigns user from project

Definition

Table 6. General request information
Value

Path

/api/admin/project/{projectId}/membership/{userId}

Method

DELETE

Status code

200 OK

Path parameters

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

7.6.6. Admin shows user details

REST API for usecase UC_017-Admin shows user details

Definition

Table 8. General request information
Value

Path

/api/admin/user/{userId}

Method

GET

Status code

200 OK

Path parameters

Table 9. 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":[]}

7.6.7. Admin deletes a user

REST API for usecase UC_018-Admin deletes a user

Definition

Table 10. General request information
Value

Path

/api/admin/user/{userId}

Method

DELETE

Status code

200 OK

Path parameters

Table 11. 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)

7.6.8. Admin shows project details

Definition

Table 12. General request information
Value

Path

/api/admin/project/{projectId}

Method

GET

Status code

200 OK

Path parameters

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

7.6.9. Admin downloads all details about a scan job

Definition

Table 14. General request information
Value

Path

/api/admin/scan/download/{jobUUID}

Method

GET

Status code

200 OK

Path parameters

Table 15. 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/63e99443-25d3-4314-a8aa-4769acb6cda9' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

7.6.10. Admin grants admin rights to user

Definition

Table 16. General request information
Value

Path

/api/admin/user/{userId}/grant/superadmin

Method

POST

Status code

200 OK

Path parameters

Table 17. 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)

7.6.11. Admin revokes admin rights from an admin

Definition

Table 18. General request information
Value

Path

/api/admin/user/{userId}/revoke/superadmin

Method

POST

Status code

200 OK

Path parameters

Table 19. 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)

7.6.12. Admin lists all admins

REST API for usecase UC_029-Admin lists all admins

Definition

Table 20. 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"]

7.6.13. Admin changes owner of a project

Definition

Table 21. General request information
Value

Path

/api/admin/project/{projectId}/owner/{userId}

Method

POST

Status code

200 OK

Path parameters

Table 22. 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)

7.6.14. Admin updates user email address

Definition

Table 23. General request information
Value

Path

/api/admin/user/{userId}/email/{emailAddress}

Method

PUT

Status code

200 OK

Path parameters

Table 24. 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)

7.6.15. Admin shows user details for email address

Definition

Table 25. General request information
Value

Path

/api/admin/user-by-email/{emailAddress}

Method

GET

Status code

200 OK

Path parameters

Table 26. 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":[]}

7.6.16. Admin creates a project

REST API for usecase UC_013-Admin creates a project

Definition

Table 27. 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)

7.6.17. Admin lists all projects

REST API for usecase UC_014-Admin lists all projects

Definition

Table 28. 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"]

7.6.18. Admin deletes a project

REST API for usecase UC_020-Admin deletes a project

Definition

Table 29. General request information
Value

Path

/api/admin/project/{projectId}

Method

DELETE

Status code

200 OK

Path parameters

Table 30. 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)

7.6.19. Update project whitelist

REST API for usecase UC_022-Update project whitelist

Definition

Table 31. General request information
Value

Path

/api/admin/project/{projectId}/whitelist

Method

POST

Status code

200 OK

Path parameters

Table 32. 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)

7.6.20. Admin shows scan logs for project

Definition

Table 33. General request information
Value

Path

/api/admin/project/{projectId}/scan/logs

Method

GET

Status code

200 OK

Path parameters

Table 34. 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":"a6676e74-40b4-4d67-bd74-9664672d5511","executedBy":"spartakus","started":"2024-02-25T10:13:25.558163068","ended":"2024-02-26T10:13:25.558207992","status":"OK"}]

7.6.21. Update project metadata

REST API for usecase UC_059-Update project metadata

Definition

Table 35. General request information
Value

Path

/api/admin/project/{projectId}/metadata

Method

POST

Status code

200 OK

Path parameters

Table 36. 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)

7.6.22. Admin changes project description

Definition

Table 37. General request information
Value

Path

/api/admin/project/{projectId}

Method

POST

Status code

200 OK

Path parameters

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

7.6.23. Admin changes project access level

Definition

Table 39. General request information
Value

Path

/api/admin/project/{projectId}/accesslevel/{projectAccessLevel}

Method

POST

Status code

200 OK

Path parameters

Table 40. 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)

Definition

Table 41. General request information
Value

Path

/api/anonymous/apitoken/{oneTimeToken}

Method

GET

Status code

200 OK

Path parameters

Table 42. 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)

7.6.25. User creates a new sechub job

7.6.25.1. Code Scan variant

Definition

Table 43. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 44. 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":"e845b27e-8a88-4698-9e48-dc0d2c08921f"}
7.6.25.2. Code Scan using data section variant

Definition

Table 45. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 46. 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":"0ac228d8-586a-4165-aac9-e56635fbd03f"}
7.6.25.3. Secret scan variant

Definition

Table 47. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 48. 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":"93bf29e9-9190-4110-921f-de61e322cc59"}
7.6.25.4. License scan variant

Definition

Table 49. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 50. 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":"a9164fd3-4791-4132-92f0-1c14daed7fc4"}
7.6.25.5. Infrastructure scan variant

Definition

Table 51. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 52. 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":"d535c54b-5fd3-4da6-a601-9e19530a3f9a"}
7.6.25.6. Web scan anonymous variant

Definition

Table 53. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 54. 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":"3f63b1f2-571a-4b1a-afd7-b3fedcc3d574"}
7.6.25.7. Web scan with api definition variant

Definition

Table 55. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 56. 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":"ce0dbba0-8df4-4683-b981-39b198fc2ea1"}
7.6.25.8. Web scan with client certificate definition variant

Definition

Table 57. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 58. 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":"9835a031-f1ae-45da-a5cc-61dc8411985e"}
7.6.25.9. Web Scan login basic variant

Definition

Table 59. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 60. 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

Login URL

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":"3c7bf60c-d8c8-4567-ae79-ec198ee2b30b"}
7.6.25.10. Web Scan login form scripted variant

Definition

Table 61. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 62. 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

Login URL

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":"94675c44-8489-42f6-9c08-054c675151bb"}
7.6.25.11. Web Scan headers variant

Definition

Table 63. General request information
Value

Path

/api/project/{projectId}/job

Method

POST

Status code

200 OK

Path parameters

Table 64. 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.

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}]},"apiVersion":"1.0"}'

Response body

{"jobId":"0553c3e8-b73c-4d09-819d-156ff757150d"}

7.6.26. User uploads source code

REST API for usecase UC_006-User uploads source code

Definition

Table 65. General request information
Value

Path

/api/project/{projectId}/job/{jobUUID}/sourcecode

Method

POST

Status code

200 OK

Path parameters

Table 66. 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 parameters

Parameter Description

checkSum

A sha256 checksum for file upload validation

Request headers

Name Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/ae4350a9-054c-48d7-9ab6-258150fb51fd/sourcecode' -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          [   '     ' \
    -F 'checkSum=mychecksum'

Response body
(empty)

7.6.27. User approves sechub job

REST API for usecase UC_007-User approves sechub job

Definition

Table 67. General request information
Value

Path

/api/project/{projectId}/job/{jobUUID}/approve

Method

PUT

Status code

200 OK

Path parameters

Table 68. 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/0d345759-b607-408d-92f5-2d98d3dc2966/approve' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

7.6.28. User checks sechub job state

Definition

Table 69. General request information
Value

Path

/api/project/{projectId}/job/{jobUUID}

Method

GET

Status code

200 OK

Path parameters

Table 70. 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/5f903b1c-f896-4b02-b926-aa4feff6652a' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"jobUUID":"5f903b1c-f896-4b02-b926-aa4feff6652a","owner":"CREATOR1","created":"","started":"2024-02-26T09:58:38.162853936","ended":"2024-02-26T10:13:38.162883451","state":"ENDED","result":"OK","trafficLight":"GREEN"}

7.6.29. User downloads sechub job report

7.6.29.1. JSON variant

Definition

Table 71. General request information
Value

Path

/api/project/{projectId}/report/{jobUUID}

Method

GET

Status code

200 OK

Path parameters

Table 72. 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/6b5dbd67-7fcd-4381-a69e-d1af8246cfde' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'
7.6.29.2. HTML variant

Definition

Table 73. General request information
Value

Path

/api/project/{projectId}/report/{jobUUID}

Method

GET

Status code

200 OK

Path parameters

Table 74. 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/30f54abf-8545-45a5-aacb-df304d14ccc1' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/xhtml+xml'

7.6.30. User marks false positives for finished sechub job

Definition

Table 75. General request information
Value

Path

/api/project/{projectId}/false-positives

Method

PUT

Status code

200 OK

Path parameters

Table 76. 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)

7.6.31. User unmarks existing false positive definitons

Definition

Table 77. General request information
Value

Path

/api/project/{projectId}/false-positive/{jobUUID}/{findingId}

Method

DELETE

Status code

200 OK

Path parameters

Table 78. 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)

7.6.32. User fetches false positive configuration of project

Definition

Table 79. General request information
Value

Path

/api/project/{projectId}/false-positives

Method

GET

Status code

200 OK

Path parameters

Table 80. 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

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!

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

7.6.33. User uploads binaries

REST API for usecase UC_069-User uploads binaries

Definition

Table 81. General request information
Value

Path

/api/project/{projectId}/job/{jobUUID}/binaries

Method

POST

Status code

200 OK

Path parameters

Table 82. 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 parameters

Parameter Description

checkSum

A sha256 checksum for file upload validation

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/58b082ed-2ae6-4108-99ce-1be64937d256/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=mychecksum'

Response body
(empty)

7.6.34. User downloads job report in SPDX format

Definition

Table 83. General request information
Value

Path

/api/project/{projectId}/report/spdx/{jobUUID}

Method

GET

Status code

200 OK

Path parameters

Table 84. 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/5ce45cdd-fe68-4946-bc73-3fd902d34476' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

7.6.35. User self registration

REST API for usecase UC_001-User self registration

Definition

Table 85. 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)

7.6.36. Admin lists open user signups

Definition

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

7.6.37. Admin applies self registration

Definition

Table 87. General request information
Value

Path

/api/admin/signup/accept/{userId}

Method

POST

Status code

201 CREATED

Path parameters

Table 88. 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)

7.6.38. Admin deletes user signup

REST API for usecase UC_019-Admin deletes user signup

Definition

Table 89. General request information
Value

Path

/api/admin/signup/{userId}

Method

DELETE

Status code

200 OK

Path parameters

Table 90. 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)

7.6.39. User requests new API token

Definition

Table 91. General request information
Value

Path

/api/anonymous/refresh/apitoken/{emailAddress}

Method

POST

Status code

200 OK

Path parameters

Table 92. 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)

7.6.40. Admin lists all running jobs

Definition

Table 93. 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":"38522d11-e2b8-4d0d-9f72-da239ef53166","projectId":"project-name","owner":"owner-userid","status":"RUNNING","since":"2024-02-26T10:13:31.451656924","configuration":"{ config data }"}]

7.6.41. Admin cancels a job

REST API for usecase UC_034-Admin cancels a job

Definition

Table 94. General request information
Value

Path

/api/admin/jobs/cancel/{jobUUID}

Method

POST

Status code

200 OK

Path parameters

Table 95. 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/34ce768a-9243-414a-bd2f-ae0a3a661670' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

7.6.42. Admin restarts a job

REST API for usecase UC_041-Admin restarts a job

Definition

Table 96. General request information
Value

Path

/api/admin/jobs/restart/{jobUUID}

Method

POST

Status code

200 OK

Path parameters

Table 97. 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/251fbe5a-f4e8-4501-9b4b-243cac5c37b8' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

7.6.43. Admin restarts a job (hard)

Definition

Table 98. General request information
Value

Path

/api/admin/jobs/restart-hard/{jobUUID}

Method

POST

Status code

200 OK

Path parameters

Table 99. 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/b448dda6-31f0-4174-a282-3961d90df5ac' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

7.6.44. User defines mock data configuration for project

Definition

Table 100. 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)

7.6.45. User retrieves mock data configuration for project

Definition

Table 101. 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"}}

7.6.46. Admin updates mapping configuration

Definition

Table 102. General request information
Value

Path

/api/admin/config/mapping/{mappingId}

Method

PUT

Status code

200 OK

Path parameters

Table 103. 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)

7.6.47. Admin fetches mapping configuration

Definition

Table 104. General request information
Value

Path

/api/admin/config/mapping/{mappingId}

Method

GET

Status code

200 OK

Path parameters

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

7.6.48. Admin creates an executor configuration

Definition

Table 106. 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

c084eeba-77c1-41fc-804c-bb29e41c25d4

7.6.49. Admin deletes executor configuration

Definition

Table 107. General request information
Value

Path

/api/admin/config/executor/{uuid}

Method

DELETE

Status code

200 OK

Path parameters

Table 108. 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/97b061a1-bde3-4317-b022-4ba2eb99d2c2' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

7.6.50. Admin fetches executor configuration list

Definition

Table 109. 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":"a33f5b9c-f605-498c-bf16-ecac4819ed03","name":"example configuration","enabled":true}],"type":"executorConfigurationList"}

7.6.51. Admin fetches executor configuration

Definition

Table 110. General request information
Value

Path

/api/admin/config/executor/{uuid}

Method

GET

Status code

200 OK

Path parameters

Table 111. 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/e0c7cc07-9dc1-4b54-bcc6-a2397dd00f98' -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":"e0c7cc07-9dc1-4b54-bcc6-a2397dd00f98"}

7.6.52. Admin updates executor configuration setup

Definition

Table 112. General request information
Value

Path

/api/admin/config/executor/{uuid}

Method

PUT

Status code

200 OK

Path parameters

Table 113. 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/e5f8b425-6406-4715-8ef8-6e2b7e61a671' -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)

7.6.53. Admin creates an execution profile

Definition

Table 114. General request information
Value

Path

/api/admin/config/execution/profile/{profileId}

Method

POST

Status code

201 CREATED

Path parameters

Table 115. 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)

7.6.54. Admin deletes execution profile

Definition

Table 116. General request information
Value

Path

/api/admin/config/execution/profile/{profileId}

Method

DELETE

Status code

200 OK

Path parameters

Table 117. 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)

7.6.55. Admin updates execution profile

Definition

Table 118. General request information
Value

Path

/api/admin/config/execution/profile/{profileId}

Method

PUT

Status code

200 OK

Path parameters

Table 119. 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":"09dd01f1-6fe8-4e68-a686-df7adf8fcae0","executorVersion":0,"enabled":false,"setup":{"credentials":{},"jobParameters":[]}}],"enabled":true}'

Response body
(empty)

7.6.56. Admin fetches execution profile

Definition

Table 120. General request information
Value

Path

/api/admin/config/execution/profile/{profileId}

Method

GET

Status code

200 OK

Path parameters

Table 121. 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":"0b8b3069-a27b-4e11-92e1-c05227f48297"}],"projectIds":["project-1","project-2"]}

7.6.57. Admin fetches execution profile list

Definition

Table 122. 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"}

7.6.58. Admin assigns execution profile to project

Definition

Table 123. General request information
Value

Path

/api/admin/config/execution/profile/{profileId}/project/{projectId}

Method

POST

Status code

201 CREATED

Path parameters

Table 124. 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)

7.6.59. Admin unassigns execution profile from project

Definition

Table 125. General request information
Value

Path

/api/admin/config/execution/profile/{profileId}/project/{projectId}

Method

DELETE

Status code

200 OK

Path parameters

Table 126. 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)

7.6.60. Admin fetches auto cleanup configuration

Definition

Table 127. 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}}

7.6.61. Admin updates auto cleanup configuration

Definition

Table 128. 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)

7.6.62. Admin disables job processing in scheduler

Definition

Table 129. 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)

7.6.63. Admin enables scheduler job processing

Definition

Table 130. 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)

7.6.64. Admin get scheduler status

Definition

Table 131. 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)

7.6.65. Admin lists status information

Definition

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

7.6.66. Admin checks server version

Definition

Table 133. General request information
Value

Path

/api/admin/info/version

Method

GET

Status code

200 OK

Request headers

Name Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/info/version' -i -u 'user:secret' -X GET \
    -H 'Content-Type: text/plain;charset=UTF-8'

Response body

0.12.3

7.6.67. User lists jobs for project

Definition

Table 134. General request information
Value

Path

/api/project/{projectId}/jobs

Method

GET

Status code

200 OK

Path parameters

Table 135. https://localhost:8081/api/project/{projectId}/jobs
Parameter Description

projectId

The id of the project where job information shall be fetched for

Request parameters

Parameter Description

size

The wanted (maximum) size for the result set. When not defined, the default will be 1.

page

The wanted page number. When not defined, the default will be 0.

metadata.labels.*

An optional dynamic query parameter to filter jobs by labels. The syntax is 'metadata.labels.${labelKey}=${labelValue}'.

It is possible to query for multiple labels (up to 10 ). The filter works as an AND combination: Only jobs having all wanted label key value combinations are returned.

withMetaData

An optional parameter to define if meta data shall be fetched as well. When not defined, the default will be false.

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":"a93a36eb-b427-433f-8097-317e9a150d49","executedBy":"User1","created":"2024-02-26T09:56:38.22404833","started":"2024-02-26T09:58:38.224073927","ended":"2024-02-26T10:13:38.224083625","executionState":"ENDED","trafficLight":"GREEN","executionResult":"OK","metaData":{"labels":{"stage":"test"}}}]}

7.7. Domain Driven Design

We use domain driven design, but communication is done very simple - for more details read the concept.

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

7.7.2. Domain communication and actions

Domainsextern.clientssechub.domain.schedulesechub.domain.scansechub.adapterextern.security.productsStartSecHubScanSchedulerRestControllerProductExecutor(s)SecHubJobBatchTriggerServicefetchesnextSecHubJobCRONbasedstartsnewbatchjobSecHubJobUUIDBatchJobBuildercreatesBatchJob (Spring)dependingonJobconfigurationBatchJobSecHubJobReportBuilderServiceexecutesupdatestatesProductSecHubJobStatusServiceCheckSecHubScanStateSecHubJobUUIDGetSecHubScanReportSecHubJobUUIDexecutesScanServiceProductExecutionStoreServiceProductAdaptercallsProductResultReportusesSecHubResultServicecallssavesreadsreportproductresultsomecouldreadreadsSchedulerServicecreates +schedulesaSecHubJobReportRestControllerReportProviderServicereadsTrafficLightCalculatoruses
Figure 4. Domain communication and actions
7.7.2.2. Message ANALYZE_SCAN_RESULTS_AVAILABLE
Sequence diagram of messaging ANALYZE_SCAN_RESULTS_AVAILABLE
7.7.2.3. Message AUTO_CLEANUP_CONFIGURATION_CHANGED
Sequence diagram of messaging AUTO_CLEANUP_CONFIGURATION_CHANGED

Use cases related to this message

7.7.2.4. Message BINARY_UPLOAD_DONE
Sequence diagram of messaging BINARY_UPLOAD_DONE
7.7.2.5. Message JOB_CANCELLATION_RUNNING
Sequence diagram of messaging JOB_CANCELLATION_RUNNING
7.7.2.6. Message JOB_CREATED
Sequence diagram of messaging JOB_CREATED
7.7.2.7. Message JOB_DONE
Sequence diagram of messaging JOB_DONE
7.7.2.8. Message JOB_EXECUTION_STARTING
Sequence diagram of messaging JOB_EXECUTION_STARTING
7.7.2.9. Message JOB_FAILED
Sequence diagram of messaging JOB_FAILED
7.7.2.10. Message JOB_RESTART_CANCELED
Sequence diagram of messaging JOB_RESTART_CANCELED
7.7.2.11. Message JOB_RESTART_TRIGGERED
Sequence diagram of messaging JOB_RESTART_TRIGGERED
7.7.2.12. Message JOB_RESULTS_PURGED
Sequence diagram of messaging JOB_RESULTS_PURGED

Use cases related to this message

7.7.2.13. Message JOB_RESULT_PURGE_DONE
Sequence diagram of messaging JOB_RESULT_PURGE_DONE
7.7.2.14. Message JOB_RESULT_PURGE_FAILED
Sequence diagram of messaging JOB_RESULT_PURGE_FAILED
7.7.2.15. Message JOB_STARTED
Sequence diagram of messaging JOB_STARTED
7.7.2.16. Message MAPPING_CONFIGURATION_CHANGED
Sequence diagram of messaging MAPPING_CONFIGURATION_CHANGED
7.7.2.17. Message PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE
Sequence diagram of messaging PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE
7.7.2.18. Message PROJECT_ACCESS_LEVEL_CHANGED
Sequence diagram of messaging PROJECT_ACCESS_LEVEL_CHANGED
7.7.2.19. Message PROJECT_CREATED
Sequence diagram of messaging PROJECT_CREATED
7.7.2.20. Message PROJECT_DELETED
Sequence diagram of messaging PROJECT_DELETED
7.7.2.21. Message PROJECT_OWNER_CHANGED
Sequence diagram of messaging PROJECT_OWNER_CHANGED
7.7.2.22. Message PROJECT_WHITELIST_UPDATED
Sequence diagram of messaging PROJECT_WHITELIST_UPDATED
7.7.2.23. Message REQUEST_JOB_CANCELLATION
Sequence diagram of messaging REQUEST_JOB_CANCELLATION
7.7.2.24. Message REQUEST_JOB_RESTART
Sequence diagram of messaging REQUEST_JOB_RESTART

Use cases related to this message

7.7.2.25. Message REQUEST_JOB_RESTART_HARD
Sequence diagram of messaging REQUEST_JOB_RESTART_HARD

Use cases related to this message

7.7.2.26. Message REQUEST_PURGE_JOB_RESULTS
Sequence diagram of messaging REQUEST_PURGE_JOB_RESULTS

Use cases related to this message

7.7.2.27. Message REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING
Sequence diagram of messaging REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING

Use cases related to this message

7.7.2.28. Message REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING
Sequence diagram of messaging REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING

Use cases related to this message

7.7.2.29. Message REQUEST_SCHEDULER_JOB_STATUS
Sequence diagram of messaging REQUEST_SCHEDULER_JOB_STATUS
7.7.2.30. Message REQUEST_SCHEDULER_STATUS_UPDATE
Sequence diagram of messaging REQUEST_SCHEDULER_STATUS_UPDATE
7.7.2.31. Message REQUEST_USER_ROLE_RECALCULATION
Sequence diagram of messaging REQUEST_USER_ROLE_RECALCULATION
7.7.2.32. Message SCAN_DONE
Sequence diagram of messaging SCAN_DONE
7.7.2.33. Message SCAN_FAILED
Sequence diagram of messaging SCAN_FAILED
7.7.2.34. Message SCHEDULER_JOB_PROCESSING_DISABLED
Sequence diagram of messaging SCHEDULER_JOB_PROCESSING_DISABLED

Use cases related to this message

7.7.2.35. Message SCHEDULER_JOB_PROCESSING_ENABLED
Sequence diagram of messaging SCHEDULER_JOB_PROCESSING_ENABLED

Use cases related to this message

7.7.2.36. Message SCHEDULER_JOB_STATUS
Sequence diagram of messaging SCHEDULER_JOB_STATUS
7.7.2.37. Message SCHEDULER_STARTED
Sequence diagram of messaging SCHEDULER_STARTED
7.7.2.38. Message SCHEDULER_STATUS_UPDATE
Sequence diagram of messaging SCHEDULER_STATUS_UPDATE
7.7.2.39. Message SOURCE_UPLOAD_DONE
Sequence diagram of messaging SOURCE_UPLOAD_DONE
7.7.2.40. Message START_SCAN
Sequence diagram of messaging START_SCAN
7.7.2.41. Message UNSUPPORTED_OPERATION
Sequence diagram of messaging UNSUPPORTED_OPERATION
7.7.2.42. Message USER_ADDED_TO_PROJECT
Sequence diagram of messaging USER_ADDED_TO_PROJECT

Use cases related to this message

7.7.2.43. Message USER_API_TOKEN_CHANGED
Sequence diagram of messaging USER_API_TOKEN_CHANGED
7.7.2.44. Message USER_BECOMES_SUPERADMIN
Sequence diagram of messaging USER_BECOMES_SUPERADMIN
7.7.2.45. Message USER_CREATED
Sequence diagram of messaging USER_CREATED

Use cases related to this message

7.7.2.46. Message USER_DELETED
Sequence diagram of messaging USER_DELETED
7.7.2.47. Message USER_EMAIL_ADDRESS_CHANGED
Sequence diagram of messaging USER_EMAIL_ADDRESS_CHANGED
7.7.2.48. Message USER_NEW_API_TOKEN_REQUESTED
Sequence diagram of messaging USER_NEW_API_TOKEN_REQUESTED

Use cases related to this message

7.7.2.49. Message USER_NO_LONGER_SUPERADMIN
Sequence diagram of messaging USER_NO_LONGER_SUPERADMIN
7.7.2.50. Message USER_REMOVED_FROM_PROJECT
Sequence diagram of messaging USER_REMOVED_FROM_PROJECT

Use cases related to this message

7.7.2.51. Message USER_ROLES_CHANGED
Sequence diagram of messaging USER_ROLES_CHANGED
7.7.2.52. Message USER_SIGNUP_REQUESTED
Sequence diagram of messaging USER_SIGNUP_REQUESTED

Use cases related to this message

7.8. Calling Security Products

7.8.1. Product adapter

A Product adapter is "stupid" and does NOT know anything about SecHub.

It only knows a product and is able to provide methods for access. That’s all. In most cases there exists also a simple test application which can be used to play around with the product. So we got rapid response if product adapter works well.

AdapterAdapterConfigAdapterContextAbstractAdaptercreatesandchangesusesknowsAbstractAdapterContextAbstractAdapterConfigBuilderAbstractAdapterConfigAbstractSpringRestTemplateAdaptercansetupProductXYConfigBuilderProductXYConfigsetup +createsProductXYContextknowsProductXYAdapterusescreaetsCallerusesbuildertocreateconfiguseswithconfig
Figure 5. Adapter Big picture

Every product adapter must be provided and used by its own interface. Also the adapter project must provide:

  1. Real adapter implementation

  2. Additional mock variant

    1. mock REST api calls etc.

    2. returns a predefined set of an real output

    3. maybe has possibilities to change the behaviour on runtime

By the mock variant it is possible to - test the complete szenario in a very fast way…​ - test configuration values from SecHub are passed through adapter

7.8.1.1. Implementation of new adapters

Only green highlighted classes in former image above needs to be implmemented to get a new adapter running.

The abstract implementation does have the most technical parts already inside, so implementing a new adapter should be very easy and developers can concentrate on adapter business logic.

For example the handling of proxies or self signed certificates is already managed there. Please look into existing adapters for more information / inspiration.

7.8.2. Product executor

A Product executor does know SecHub and has access to database etc. It uses a Product adapter inside!

7.8.3. Product executors and results

The scan service and the report builder service are using different product executors to create ProductResult table entries.
Each product executor will persist its state - so even SERECO will persist its full content as report result as well! This was made to store all information - for retry mechanism in future and also for easier debugging etc. When failures on last step are occurring (and e.g. we got a succesful scan(s) by other (product(s) which took 3 hours…​.) we can retry the full step - or, at least interesting for debugging/analyzing.

7.8.4. Product executor versus product execution service

The service does execute and handle different product executors.

7.9. Network target handling

For some security products it’s necessary to differ between intranet and internet scan targets. This is represented by the class NetworkTarget.

Some products are not able to handle different network targets when not being installed twice, some can do this by a product specific identifier. SecHub must be able to automatically call the correct product installation in such cases.

To handle this always the same way some framework mechanism was introduced, see next chapter.

7.9.1. Automatic Network Target info resolving

The class AbstractProductExecutor is the single base class for mostly all product executors and does automatically provide network target handling for scan types webScan and infraScan.

The abstract executor will create a ProductExecutorData object at runtime let child implementations customize it and then prepare all necessary steps before giving it again to the child implementation for final execution.

For automated target handling the customization of ProductExecutorData must set a NetworkTargetProductServerDataProvider and a NetworkTargetLocationProvider.

For PDS the network target type will be injected to the PDS caller scripts automatically via environment variable PDS_SCAN_TARGET_TYPE. Also PDS instances have the possibility to forbid a target type - so for different target types we can define two different PDS executor configurations.

Class diagram of target and install setup architecture

8. Deployment View

8.1. SecHub infrastructure setup

8.2. Spring boot

8.2.1. SecHub Spring Profiles

SecHub provides multiple Spring profiles

8.2.1.1. Server
8.2.1.1.1. Overview
Diagram
Figure 6. Spring profiles and their explicit/implicit included parts
8.2.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.

Diagram
Figure 7. Spring profile prod and its explicit/implicit included parts
8.2.1.1.3. DEV
Diagram
Figure 8. 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

8.2.1.1.4. Integration-Test
Diagram
Figure 9. 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).

8.2.2. Database configuration

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

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

Table 136. 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 137. Scope 'anonymous'
Key Default Description

sechub.user.onetimetoken.outdated.millis

86400000

One time token time when outdating

Table 138. Scope 'checkmarx'
Key Default Description

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

3

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

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

2000

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

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

1

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

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

5000

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

sechub.adapter.checkmarx.scanresultcheck.period.minutes

-1

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

sechub.adapter.checkmarx.scanresultcheck.timeout.minutes

-1

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

sechub.adapter.checkmarx.trustall

false

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

Table 139. 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 140. Scope 'migration'
Key Default Description

sechub.migration.flyway.autorepair

true

When enabled, flyway migration problems will be automatically repaired

Table 141. 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 142. 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 143. 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 144. Scope 'new'
Key Default Description

sechub.user.onetimetoken.outdated.millis

86400000

Time until the one time token expires

Table 145. 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 146. 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 147. 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 148. Scope 'scan'
Key Default Description

sechub.config.check.canceljob.delay

60000

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

sechub.config.scan.scanconfig.refresh.delay

5000

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

sechub.config.scan.scanconfig.refresh.initialdelay

0

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

Table 149. Scope 'scheduler'
Key Default Description

sechub.config.trigger.healthcheck.enabled

true

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

sechub.config.trigger.nextjob.delay

10000

Define delay for next job execution trigger after last executed.

sechub.config.trigger.nextjob.initialdelay

5000

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

sechub.config.trigger.nextjob.maxwaitretry

300

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

sechub.config.trigger.nextjob.retries

5

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

sechub.scheduler.strategy.id

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

sechub.server.upload.validate.checksum

true

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

sechub.server.upload.validate.zip

true

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

sechub.upload.binaries.maximum.bytes

52428800

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

Table 150. Scope 'sec'
Key Default Description

sechub.project.joblist.page.max

100

sechub.project.joblist.size.max

100

Maximum limit for job information list entries per page

sechub.server.baseurl

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

Table 151. 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 152. Scope 'server'
Key Default Description

sechub.server.debug

false

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

Table 153. 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 154. 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 155. 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

8.2.4. Scheduling definitions

Table 157. 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 158. 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.

8.2.5. Configuration properties for mocked adapters

Table 159. Scope 'abstract'
Key Default Description

sechub.adapter.mock.sanitycheck.enabled

false

See AbstractMockedAdapter.java

Table 160. 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

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

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

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.

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

class: com.mercedesbenz.sechub.SecHubServerApplication

-Dspring.profiles.active=demomode
8.3.1.2. Launch in DEV mode

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

class: com.mercedesbenz.sechub.SecHubServerApplication

-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).
8.3.1.3. Launch in INTEGRATION TEST mode

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

class: com.mercedesbenz.sechub.SecHubServerApplication

-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)
8.3.1.4. Launch in PROD mode

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

class: com.mercedesbenz.sechub.SecHubServerApplication

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

8.4. Security product integrations

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

8.4.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…​

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

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

8.4.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/

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

8.4.5. Nessus

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

8.5. Kubernetes

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

8.6. Docker-Compose

Change into the product’s folder and issue:

docker-compose up
Please also see the README file in the respective folder.

9. Cross-cutting Concepts

9.1. Security tools

9.1.1. Modules and module groups

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

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

9.2. Domain Driven Design

To have loose coupling we decided to have an simple DDD approach (see https://en.wikipedia.org/wiki/Domain-driven_design). To avoid too much complexity but keep the domains clearly separated following was done:

  1. Domains do only communicate between each other via EventBus with explicit Domain Messages. (see also domain communication constraints )

  2. Every domain has got it’s own data pool. We currently use only ONE database. But every domain has got it’s own Tables! The tables names starting with a string describing domain (for example AUTH_USER would represent user data for domain authorization…​)

  3. The "Event Bus" is currently - SecHub is a self contained system at the moment - just a simple Spring injection based publish/subscribe system done simply by implementing Observer pattern.
    If it becomes necessary to separate SecHub into different deployment units we must use a "real" event bus - e.g. KAFKA and do some refactorings.

Developers are able to define meta information inside code to obtain full generated messaging diagrams.

See Technical documentation for details about documentation generation and how to use annotations to establish results.

9.3. Resilience

We do currently not use Hystrix or another framework to handle resilience, but use a simple own approach:

Diagram

A resilient action executor can be used to execute a dedicated action. Implementation of ResilienctConsultant will give dedicated proposals how to handle an error.

There are currently two different ways:

  • Retry
    In this case the failed action will be retried some times before the exception is thrown

  • Fall through
    Here the failure is recognized as a situation which will be happen very often because a fix will take some time and so to fail fast for a given time period instead of blocking

9.4. Mappings

SecHub needed a way to configure simple configuration values and also provide a mapping from project names to adapter specific values (see Scan config )

9.4.1. Structure

To provide this in a very generic way SecHub does use the mappings means a simple setup of

  • pattern
    (simple key or a regular expression)

  • replacement
    (just the value)

  • comment (describes what this mapping is used for - just for information)

9.4.2. Domain handling

9.4.2.1. Global mappings

The Administration domain will know every global mapping (e.g. scan configuration) and provide the corresponding REST API for administrators.

Changes of global mappings will be sent from administration domain to other domains via event bus and a message with ID: MAPPING_CONFIGURATION_CHANGED.

Dedicated message handlers inside other domains will recognize wanted parts and store information when necessary.

9.4.2.2. Product executor parameter mappings

This will not lead to any domain event. The product executors will inspect the mapping information always again before a job has been started. The mapping data is stored inside executor configurations, which is always available inside a job execution, so there is no need of any domain events.

9.5. Product delegation server

9.5.1. General

There are many open source clients available having no server component inside so lacking:

  • REST access

  • queuing

  • status requests

  • scalable

  • … more

So when we want to adapt them in SecHub style (the product does the work and we ask for result) we need to provide a ProductDelegationServer (in short form PDS).

PDS is

  • a spring boot application which uses a network DB for providing cluster possibility

  • a complete standalone application without runtime dependencies to SecHub server (or its shared kernel)

  • provides REST access

  • a very simple priviledge model with just two users (tech user + admin user), basic auth via TLS, credentials are simply defined by environment entries on startup

  • provides jobs, queing, monitoring etc.

  • can execute single files (e.g. a bash script), where job parameters are available as environment variables at runtime

  • a standard way to integrate any product into SecHub in a scalable and easy way

9.5.2. Handling of resources

  • PDS server provides auto unzipping of uploaded resources when configured - see PDS server configuration file

  • When a PDS job fails or is done the resources inside job workspace location are automatically removed

9.5.3. Big picture

Diagram

9.5.4. Storage and sharing

PDS needs - like SecHub - the possiblity to store job data in a central storage location when operating inside a cluster (it’s not clear which cluster member uploads job data and which one does execute the job and need the data at exectuion time).

PDS does use the already existing sechub-storage-* libraries which provide storage mechanism for S3 and for shared volumes.

The next examples explain the different situations appearing for a PDS cluster executing product "XYZ", but of course this applies to multiple clusters for different products as well

For non clustered environment "shared volumes" can also be local file system paths like /opt/storage/pds/XYZ

When talking about a NFS or a shared volume here, this is always meant to be a file system path. It’s important to mount a NFS at a local file path for the PDS server when using a shared volume. URLs are NOT supported - only file paths. So you must mount your network file storage to a local file location!

For example: a base path for a shared volume could look like: /media/mounted-storage/

9.5.4.1. Shared S3 storage

In the next example PDS and SecHub are using the same S3 bucket to store files uploaded by the user.

We have two different scenarios here:

  • Product executor configuration pds.config.use.sechub.storage is true
    In this case the way is exactly as shown in next picture:

    • The user uploads job data for a SecHub job and it is stored at shared S3 bucket (blue lines).

    • When SecHub job is starting it will create a PDS job but does not upload any additional data.

    • When PDS job is starting the PDS server will fetch workspace files from existing SecHub job data (red lines).

    • The storage path location is for PDS and SecHub ${sharedS3Bucket}/jobstorage/${secHubJobUUID}/

Diagram
  • Product executor configuration pds.config.use.sechub.storage is NOT true
    In this case the way is NOT like in picture before, but more like in Different S3 storages. Read there for more details - it’s the same - except there are not 2 different S3 buckets but only one.

9.5.4.2. Different S3 storages

In the next example PDS and SecHub are using different S3 buckets as storage.

We have two different scenarios here:

  • Product executor configuration pds.config.use.sechub.storage is NOT true
    In this case the way is exactly as shown in next picture:

    • The user uploads job data for a SecHub job and it is stored at shared S3 bucket (blue lines).

    • The storage path location for SecHub is ${sechubS3Bucket}/jobstorage/${secHubJobUUID}/

    • When SecHub job is starting it will create and initialize a PDS job by uploading all existing job data by PDS rest API. This will store job data at PDS storage. (green lines).

    • When PDS job is starting, the PDS server will fetch workspace files from its PDS job data (red lines).

    • The storage path location for PDS is ${pdsS3Bucket}/pds/${pdsProductIdentifier}/${pdsJobUUID}/

Diagram
  • Product executor configuration pds.config.use.sechub.storage is true

This will NOT WORK! The job storage will not be found and an error will be thrown at job execution time.
9.5.4.3. Same shared volume (NFS)

In the next example PDS server and SecHub are using same shared volume as storage.

We have two different scenarios here:

  • Product executor configuration pds.config.use.sechub.storage is true
    In this case the way is exactly as shown in next picture:

    • The user uploads job data for a SecHub job and it is stored at shared volume (blue lines).

    • When SecHub job is starting it will create a PDS job but does not upload any additional data.

    • When PDS job is starting the PDS server will fetch workspace files from existing SecHub job data (red lines).

    • The storage path location is for PDS and SecHub ${sharedVolumeBasePath}/jobstorage/${secHubJobUUID}/

Diagram
  • Product executor configuration pds.config.use.sechub.storage is NOT true
    In this case the way is NOT like in picture before, but more like in Different shared volumes. Read there for more details - it’s the same - except there are not 2 different NFS but only one.

9.5.4.4. Different shared volumes (NFS)

In the next example PDS and SecHub are using different shared volumes as storage.

We have two different scenarios here:

  • Product executor configuration pds.config.use.sechub.storage is NOT true
    In this case the way is exactly as shown in next picture:

    • The user uploads job data for a SecHub job and it is stored at SecHub shared volume (blue lines).

    • The storage path location for SecHub is ${sechubSharedVolumeBasePath}/jobstorage/${secHubJobUUID}/

    • When SecHub job is starting it will create and initialize a PDS job by uploading all existing job data by PDS rest API. This will store job data at PDS storage. (green lines).

    • When PDS job is starting, the PDS server will fetch workspace files from its PDS job data (red lines).

    • The storage path location for PDS is ${pdsSharedVolumeBasePath}/pds/${pdsProductIdentifier}/${pdsJobUUID}/

Diagram
  • Product executor configuration pds.config.use.sechub.storage is true

This will NOT WORK! The job storage will not be found and an error will be thrown at job execution time.
9.5.4.5. Mixing S3 and shared volume (NFS)

This example is only mentioned for the sake of completeness: It is the same as before described for different S3 and different shared volumes: pds.config.use.sechub.storage cannot be used in this case.

When not reusing SecHub storage, this scenario does work also well. In the next picture, SecHub itself would use a S3 storage and he PDS instances for product XYZ would use a NFS to store job data. But of course it could be also the other way.

Diagram

9.5.5. Process execution

PDS instances are executing so called caller scripts by spanning a new process. At this time dedicated environment variables are automatically injected and available inside the scripts.

When implementing a new PDS product integration you should always start with a normal, executable script (e.g. bash).

So you can simply call your script standalone and when it works you just have to create the PDS configuration file and make the script callable.

9.5.5.1. How PDS provides output and error stream content of running jobs in clustered environments

We use error.txt and output.txt inside the workspace location of a running PDS job.

The PDS job process does not store the files on a shared volume or S3 bucket but on the local file system (like done for uploaded source files for example).

So we can easily write those text content from the files to our database when the OS process (executing PDS caller script) has finished or failed, because at this time we have direct access to the files.

But when an administrator wants to get the current output for a running job / operation this becomes tricky in a clustered environment, because the process stream data is only available on the machine where the job is executed. Using a loadbalancer we do not know which machine will be used for the REST operation.

So it becomes necessary, that the executing cluster member will store the error and output text data in database to provide this cluster wide.

On the other hand it shall not slow down or block the execution machine because of permanent updates inside the DB. If an admin wants to check the output or error stream content of a running job, the information shall be gathered on demand. But when the job has finished (no matter if canceled, done or failed) the information will always be written to DB.

The next figure gives an overview about the workflow to achieve this goal:

Overview diagram about stream content fetching in cluster
9.5.5.2. How PDS handles meta data

When communication of PDS with the used product is stateful and is a long running operation, it can be useful to store such state/meta data.

One use case is the restart possibility for a SecHub job. Another one are debugging or trace information.

Most times PDS solutions do not need to store special meta data information: When the PDS job starts a CLI tool, the result or the failure will just be returned to the SecHub side.

If it shall be done again (because of on failure) just a new PDS job will be started.

If a PDS job has meta data this means it should be restarted

A PDS launcher script has no access to the PDS database! If meta data shall be read or written, we just have the workspace file metadata.txt. Inside this file the product relevant meta data of the job run must be available, see next diagram for details:

Diagram
9.5.5.2.1. Checkmarx PDS solution adapter meta data handling

The PDS solution for Checkmarx does reuse the already existing CheckmarxAdapter class. A sechub-wrapper-checkmarx gradle project was introduced which contains a simple spring boot CLI application which uses the adapter for communication. The adapter callback is not directly reading or writing to the database but uses the metadata.txt file from the PDS workspace.

Look at next figure for more details:

Diagram
9.5.5.3. How PDS handles storage data

The PDS does automatically fetch uploaded files from shared storage temporary into its local filesystem. After the scan has been done, the temporary local files will be automatically deleted.

9.5.5.3.1. Source code fetching

Source code is always contained in a file called sourcecode.zip. When a PDS starts a new job, it will fetch the complete ZIP file from storage to it’s local storage at

${PDSJobWorkspaceLocation}/upload/sourcecode.zip.

Afterwards the relevant sources will be automatically extracted by inspecting the archive data structure.

9.5.5.3.2. Binaries fetching

Binaries are always contained in a file called binaries.tar. When a PDS starts a new job and the scan does references a binary data section, it will fetch the complete TAR file from storage to it’s local storage at

${WorkspaceLocation}/upload/binaries.tar.

Afterwards the relevant binaries will be automatically extracted by inspecting the archive data structure.

9.5.5.3.3. Data structure inside TAR and ZIP files

The data structure inside TAR and ZIP files contains data configuration parts inside data folder.

Before we introduced the possibility to define referenceable data inside a SecHub configuration, we already provided a fileSystem element inside code scan configuration.

For source scans this a more convenient way and we wanted to keep this possiblity - also for backward compatibility with existing SecHub configuration files.

So this is the reason, why data is contained inside _data_ folder and there is still content inside the root folder as well.

Only source code scan configuration files may be located inside the root folder!

${content} (1)
__data__/unique-name-1/${content} (2)
__data__/unique-name-2/${content} (3)
...
1 code scan embedded file system data
2 content of a data configuration with name "unique-name-1"
3 content of a data configuration with name "unique-name-2"

Here an example:

Example JSON data definition to show resulting TAR and ZIP structures
{
  "data": {
    "sources": [ (1)
      {
        "name": "reference-name-sources-1", (2)
        "fileSystem": {
          "files": [
            "somewhere/file1.txt",
            "somewhere/file2.txt"
          ],
          "folders": [
            "somewhere/subfolder1",
            "somewhere/subfolder2"
          ]
        },
        "excludes": [
          "**/mytestcode/**",
          "**/documentation/**"
        ],
        "additionalFilenameExtensions": [
          ".cplusplus",
          ".py9"
        ]
      }
    ],
    "binaries": [ (3)
      {
        "name": "reference-name-binaries-1", (4)
        "fileSystem": {
          "files": [
            "somewhere/file1.dll",
            "somewhere/file2.a"
          ],
          "folders": [
            "somewhere/bin/subfolder1",
            "somewhere/bin/subfolder2"
          ]
        }
      },
      {
        "name": "reference-name-binaries-2", (5)
        "fileSystem": {
          "files": [
            "somewhere-else/file1.dll",
            "somewhere-else/file2.a"
          ],
          "folders": [
            "somewhere-else/bin/subfolder1",
            "somewhere-else/bin/subfolder2"
          ]
        }
      }
    ]
  }
}
1 source definition - these structure parts are inside the sourcecode.zip file
2 Name of one source data configuration
3 binaries definition - these structure parts are inside the binaries.tar file
4 Name of the first binaries data configuration
5 Name of the second binaries data configuration

The example json configuration defines following content structure inside the upload files:

ZIP file content for sources
__data__/
    reference-name-sources-1/ (2)
                  somewhere/
                     file1.txt
                     file2.txt
                     subfolder1/
                        example-content.py9
                     subfolder2/
                        example-content.cplusplus
                        example-content.txt

The example json configuration would lead to a TAR file containing:

TAR file content for binaries
__data__/
    reference-name-binaries-1/(4)
                  somewhere/
                     file1.dll
                     file2.a
                     subfolder1/
                        example-content.bin
                     subfolder2/
                        example-content.img
    reference-name-binaries-2/(5)
                  somewhere-else/
                     file1.dll
                     file2.a
                     subfolder1/
                        example-content.bin
                     subfolder2/
                        example-content.img
9.5.5.3.4. Automated Extraction of relevant parts

Only files and folders which are available for the configured scan type will be automatically extracted!
The artificial path element _data_ and the reference name will not be contained in extracted folders.

Please read the SecHub technical documentation for more details about the data configuration. You will find it described at https://mercedes-benz.github.io/sechub.

Automated extraction of source code

Let’s assume PDS has fetched sourcezip.zip which contains following structure:

ZIP file example content
__data__/
    license-sources/
            somewhere/
                     file1a.txt
                     subfolder1/
                        file1b.txt
            file2.txt
    other-sources/
            file3.txt

and a SecHub configuration file like this:

{
    // .. assume data section and other parts are configured correctly ..

    "licenseScan": {
        "use" : ["license-sources"]
    },
    "codeScan": {
        "use" : ["other-sources"]
    }
}

In the example the SecHub configuration has a license scan configured which references license-sources data configuration and a code scan which references other-sources. The PDS for license scanning will only extract license-sources:

Output of automated ZIP file extraction by PDS
${PDSJobWorkspaceLocation}/upload/unzipped/sourcecode
                                       somewhere/
                                            file1a.txt
                                            subfolder1/
                                               file1b.txt
                                       file2.txt

file3.txt was not extracted, because it is not available for the license scan.

Automated extraction of binaries

Let’s assume PDS has fetched binaries.tar which contains following structure:

TAR file example content
__data__/
    license-binaries/
            somewhere/
                     file1a.bin
                     subfolder1/
                        file1b.bin
            file2.bin
    other-binaries/
            file3.bin

and a SecHub configuration file like this:

{
    // .. assume data section and other parts are configured correctly ..

    "licenseScan": {
        "use" : ["license-binaries"]
    },
    "codeScan": {
        "use" : ["other-binaries"]
    }
}

In the example the SecHub configuration has a license scan configured which references license-binaries data configuration and a code scan which references other-binaries. The PDS for license scanning will only extract license-binaries:

Output of automated ZIP file extraction by PDS
${PDSJobWorkspaceLocation}/upload/extracted/binaries
                                       somewhere/
                                            file1a.bin
                                            subfolder1/
                                               file1b.bin
                                       file2.bin
9.5.5.4. How PDS handles user messages

Inside a PDS workspace a special messages folder exists. The launcher script can create there dedicated user message files by creating simple text files (see PDS_JOB_USER_MESSAGES_FOLDER for details) . After the job has been done (or failed), all files located at this folder are collected and stored as a JSON representing a SecHubMessageList inside the PDS Job. Those SecHub messages can be fetched by technical user via REST API.

Diagram
Figure 10. PDS user message handling
9.5.5.5. How PDS handles execution events

9.5.6. PDS events

Sometimes it is necessary that the PDS inform the script about changes. This can be done by execution events.

9.5.6.1. Overview

The product adapter is able to read and write events into a dedicated folder inside the workspace. This is utilized by the PDSWorkspaceService class.

As an example for an event the PDS cancel service calls are additionally shown (grey)
Diagram
Figure 11. Storing PDS events
9.5.6.2. Handling events in launcher script

The launcher scripts (or in started wrapper applications by these scripts) have the environment variable PDS_JOB_EVENTS_FOLDER injected.

The launcher part must inspect the folder periodically for new

Most PDS solutions do not need to inspect for events. It depends on the situation if there is any special event treatment necessary.

An example:
Inside a OWASP ZAP PDS solution, the launcher script/the wrapper could inspect if a cancel_requested.json has been created. If so, the current running owasp zap session could be stopped automatically (otherwise the ZAP scan will still proceed…​)

9.5.6.3. How PDS product executors configure the PDS adapter

The different PDS product executors have different config builders which inherit from different abstract base classes (e.g. AbstractCodeScanAdapterConfigBuilder). We have no multi inheritance in Java, but we do also not want to implement the setup logic (which is complicated) for every PDS product executor again.

There is a specialized adapter configuration strategy for PDS standard setup: PDSAdapterConfigurationStrategy.

9.5.6.4. Overview
Diagram

9.5.7. SecHub integration

9.5.7.1. Executors and Adapters
9.5.7.1.1. Executors

With PDS there is a default REST API available.

For different scanTypyes there will be dedicated PDSExecutors (PDSWebScanExecutor, PDSInfraScanExecutor, etc., etc.)

9.5.7.1.2. Adapters

The Adapter will always be the same, but filled with other necessary parameters.

So there will be no need to write any adapter or executor when using PDS!

9.6. HowTo integrate a new product via PDS

Having new security product XYZ but being a command line tool, we

  • create an environment (e.g. a docker container) where all your needed parts are integrated. E.g. bash shell, tools, the product and its dependencies etc.

  • create an executable starter script (e.g. bash) which

    • calls the product

    • does system out/err to standard pipes

    • writes the product result report to relative path ./output/result.txt

  • create a PSD configuration file and fill with necessary data, see PDS server configuration file

  • start wanted amount of ProductDelegationServer instances with dedicated configuration setup to have a clustered, server ready execution of CLI security products. If you want your PDS to be started inside a cluster you have to setup load balancing etc. by your own. For example: When using Kubernetes you normally would do this by just defining a Service pointing to your PODs.

  • test via developer admin UI if the servers are working:

    • create test job, remember PDS job uuid

    • upload data

    • mark job as ready to start

    • check job state

    • fetch result and inspect

  • when former test was successful

    • Define executor on SecHub server side - will be implemented with #148

    • When your product uses sereco general report format your are done- will be implemented with #283 otherwise SERECO must have a logic to import custom format for the PRODUCT - means needs an implementatiion

  • test via SecHub client by starting a new SecHub job which shall use the product and verify results

9.7. Archive extraction

The data structure concept does need an automated archive extraction. The main java class is ArchiveSupport.

The next figure gives an overview about the involved classes:

Diagram

9.8. False-positive handling

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

9.8.1. General

9.8.1.1. How can false positives be handled across multiple security products?
9.8.1.1.1. Problem
  1. 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.

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

9.8.1.2. Different kinds of false-positive filtering

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

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

9.8.1.2.2. Web UI

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

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

9.8.2. Code scan

9.8.2.1. API centric
9.8.2.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!

9.8.2.2. Web UI
9.8.2.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

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

9.8.3. Web scan

9.8.3.1. Code centric

Not possible

9.8.3.2. API centric
9.8.3.3. Web UI

9.8.4. Infra scan

9.8.4.1. Code centric

Not possible

9.8.4.2. API centric

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.

9.8.4.3. Web UI

9.9. Product execution profiles and executor configuration

To have the possibility of using dedicated security products for different projects, to disable/enable products on demand without server restart or just to test new products in one evaluation project but not for all other projects a runtime configuration is necessary.

This is provided by execution profiles and and executor configurations.

9.9.1. Overview

Diagram
Figure 12. Overview profiles and configurations

9.9.2. Executor configuration

An executor configuration represents a runtime configuration for product executors. The configuration has an enabled state. So it is possible to enable/disable product execution.

9.9.3. Execution profile

An execution profile can contain multiple executor configurations. The configurations can be shared between multiple profiles. E.g. a config with name "pds-gosec-1" can be used in profiles "profileA" and also "profileB" at the same time.

Additionally a profile can be assigned to a project (but technically we assign a projectId to a profile, because in domain scan we only know projectIds but no the Project entity…​).

The profile has also an enabled state - like executors.

9.9.4. How execution process uses profiles and configurations

ScanService is called by SecHub batch operation from scheduler and contains the project id for the project to scan for.

When it comes to execution, ProductExectionStoreService fetches all enabled profiles related to the given project id and executes all enabled product executors for the wanted scan job - e.g. code scan product executors

9.9.4.1. Results handling done by configured report executor or fallback

All of the results returned by the dedicated product executors are stored in database. After this has been done, the configured report product executor(s) is (are) executed (if none has been defined in at least one profile, the fallback will automatically use Sereco product executor version 1, which is embedded)

9.10. Product results

Product results can be either from security products or from reporting products.

For a job different security products can be executed, depending on the execution configuration. After this the results will be stored in database as dedicated ProductResult entries.

Afterwards reporting products will be executed to collect the former stored reports and merge them together. The report product merge result will be stored as a ProductResult as well in database for the job.

When no report collector is configured/available the embedded report product Sereco ("SecHub report collector") will be used .

9.10.1. Product messages inside product result

Every product can add custom messages which shall be available to user.

9.10.1.1. Storing product messages

The product adapter fetches the information from the product and delivers it to the product executor, who stores the SecHub messages inside the ProductResult entity.

Diagram
Figure 13. Storing product messages