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 2.4.1 - Build date: 2024-12-18 14:20 (UTCZ)
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 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 |
||
User |
A person who wants to execute scans by SecHub. |
|
Administrator |
A person who installs SecHub server and does maintenance of
target security products. Also responsible for onboarding of
projects and users. |
|
External Systems |
Another system which will call the REST API or the SecHub client. E.g. Build Servers like Jenkins. |
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
3.3. Technical 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. |
see |
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. |
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 |
|
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 , |
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
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.2. User administration
Usecases handling administration of users
7.5.1.3. Project administration
Usecases for project administration
7.5.1.4. User profile
User actions belonging to their profiles
7.5.1.5. Sechub execution
Execution of SecHub -either by CLI or direct with REST api call
7.5.1.6. Sign up
All these usecases are handling user sign up (part of user self registration process)
7.5.1.7. Job administration
Usecases about job administration
7.5.1.8. Technical
Usecases about technical operations being executed by sechub itself
7.5.1.9. Testing
Some use cases for testing
7.5.1.10. Configuration
Usecases for configuration parts
7.5.1.11. Encryption
Usecases for encryption parts
7.5.1.12. Other
All other use cases
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
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 |
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
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator accepts a persisted self registration entry by calling rest api |
2 |
Create user and send events |
SUPERADMIN |
3, 4 |
The service will create the user a one time token for api token generation and triggers asynchronous events. It will also remove the existing user signup because no longer necessary. |
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 |
SUPERADMIN |
2 |
All userids of sechub users are returned as json |
2 |
Service call |
SUPERADMIN |
All userids of sechub users are returned as json |
7.5.6. UC_005-User creates a new sechub job
A user wants to create a new sechub job.
This will not directly start the job. Please refer to User approves job. |
As a result the user will have created a new SecHub
job and have a job UUID as result.
After this the user is able to
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Persistence and result |
Persist a new job entry and return Job UUID |
7.5.7. UC_006-User uploads source code
A user wants to upload sourcecode for a former created sechub job.
The source code must be a valid zipfile.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find project and upload sourcecode as zipfile |
USER |
When project is found and user has access and job is initializing the sourcecode file will be uploaded |
7.5.8. UC_007-User approves sechub job
A user wants to approve a former created sechub job.
This means the user has done all necessary preparations - e.g. uploading source code for code scanning - and wants the job marked as ready for execution
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, 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). |
|
3 |
Runnable calls execution services |
4 |
The job execution runnable creates the execution context and calls dedicated execution services (preparation, analytics, product execution, storage and reporting) synchronously for the job. It is also responsible for cancelation and supsension of jobs. |
|
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
User wants to get the state of the current running job.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find project and fail or return job status |
7.5.11. UC_010-User downloads sechub job report
A user wants to download a SecHub
report for an executed job
by its given job UUID.
The report standard format is a human and machine readable JSON format. Additionally, there is the option to download the report as HTML file.
Both, the HTML and the JSON file have a reduced view of the scan results. Code snippets etc. can be found on the real security products.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get JSON report |
SUPERADMIN, USER |
3 |
|
2 |
REST API call to get HTML report |
SUPERADMIN, USER |
3 |
|
3 |
Resolve scan report result |
7.5.12. UC_011-User starts scan by client
Sechub has got it’s own client, written in go. The client is available for Linux and Windows and can be downloaded at https://github.com/mercedes-benz/sechub .
The client encapsulated and simplifies the necessary steps to do a scan to one single step only
It does automate following usecases:
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 |
SUPERADMIN, USER |
2, 3 |
|
2 |
upload sourcecode |
SUPERADMIN, USER |
2 |
|
2 |
upload binaries |
SUPERADMIN, USER |
3 |
|
3 |
approve job |
SUPERADMIN, USER |
4 |
|
4 |
get job status |
SUPERADMIN, USER |
4 |
|
4 |
download job report and traffic light |
SUPERADMIN, USER |
7.5.13. UC_012-User clicks link to get new api token
The user has to open the received email and click there on the contained link with a onetimetoken api which is another usecase.
This use case is either triggered by when a new user was initial registered or a new API token was requested by user.
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 |
SUPERADMIN |
2 |
Administrator creates a new project by calling rest api |
2 |
Create project |
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 |
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
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator does call rest API to assign user |
2 |
Update schedule authorization parts |
2 |
||
2 |
Assign user |
SUPERADMIN |
3 |
The service will add the user to the project. If user does not have ROLE_USER it will obtain it |
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
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator does call rest API to unassign user |
2 |
Update authorization parts |
2 |
||
2 |
Unassign user |
SUPERADMIN |
2 |
The service will remove the user to the project. If users has no longer access to projects ROLE_USER will be removed |
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 |
SUPERADMIN |
2 |
Json returned containing details about user and her/his projects |
2 |
Service fetches user details. |
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 |
SUPERADMIN |
2 |
User will be deleted |
2 |
Service deletes user. |
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 |
SUPERADMIN |
2 |
Rest api called to remove user signup |
2 |
Persistence |
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 |
SUPERADMIN |
2 |
Project will be deleted |
2 |
Service deletes projects. |
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 |
SUPERADMIN |
2 |
Json returned containing details about project |
2 |
Service fetches project details. |
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 |
SUPERADMIN |
2 |
White list will be updated |
2 |
Update project |
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 |
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
It shall be possible to achieve this by calling REST API and also by just visiting static sechub website and entering email address and post request by simple web form.
When user exists a new one time token will be created and sent to user per email - so same way as done when a new user signup is accepted by admin.
The user has to open the received email.
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 |
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 |
SUPERADMIN |
2 |
|
2 |
Collect all scan data |
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 |
SUPERADMIN |
2 |
User will be granted admin rights |
2 |
Service grants user admin rights. |
SUPERADMIN |
3, 4 |
The service will grant user admin rights 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 |
SUPERADMIN |
2 |
Admin rights will be revoked from admin |
2 |
Service revokes user admin rights. |
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 |
SUPERADMIN |
2 |
All userids of sechub administrators are returned as json |
2 |
Service call |
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
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator wants to stop (pause) scheduler job processing |
2 |
Service call |
SUPERADMIN |
2 |
Sends request to scheduler to send updates about current status. |
2 |
Service call |
SUPERADMIN |
3 |
Sends request to scheduler domain to disable scheduler job processing |
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
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator wants to start (unpause) scheduler job processing |
2 |
Service call |
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 |
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 |
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 |
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
User retrieves project mockdata - see define project mockdata
SecHub must be started with |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to define mock configuration byJSON data |
SUPERADMIN, USER |
2 |
|
2 |
Service call to store mock configuration |
7.5.37. UC_036-User retrieves mock data configuration for project
When other systems integrate sechub into their live cylce (this means not a build server integration,
but an integration from another product…)
they also want to integrate into their integration tests as well - so a special environment is
necessary an INT environment
.
When using commercial security products it can happen that integration tests will lead to additional
license costs. To prevent this the INT environment
can be setup to use mocked adapters. These
adapters will not communicate with the real security products but instead return mocked product
results. All logic, every behaviour inside SecHub is exactly the same except the communication with
the security product. This technique is used by SecHub for integration testing itself.
SecHub must be started with |
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.
{
"codeScan" : {
"result" : "RED"
},
"webScan" : {
"result" : "YELLOW"
},
"infraScan" : {
"result" : "GREEN"
}
}
Of course you can reduce mock to wanted parts only:
{
"codeScan" : {
"result" : "YELLOW"
}
}
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get JSON data |
SUPERADMIN, 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 |
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 |
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 fetches server runtime data
An administrator fetches the current SecHub server runtime data. Only administrators are allowed to do this because it contains the server version and knowing the exact server version makes it easier for penetration tester or attacker to attack the system.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API Call |
SUPERADMIN |
Administrator wants to fetch server runtime data. This data contains for example the server version |
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
Event overview - variant: crashed jvm with product result
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
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
Event overview - variant: crashed jvm with product result
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Triggeres job restart (hard) |
2 |
Restart job |
3 |
Will trigger event that job restart (hard) requested |
|
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) |
3 |
When job is found, a restart will be triggered. Existing batch jobs will be terminated |
|
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.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
A user wants to mark false positives either for a finished job or with project data not necessarily connected to a finished job.
To mark false positives using job data the job must have been executed, finished without failure and job NOT been deleted. The user will be able to mark former job results by their given id as false positives.
To mark false positives using project data no job must have been run, but it will help identify findings as false positives of course. The project data are not related to any job information.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to define false positives by JSON data containing identifiers for existing jobs or false positive project data |
SUPERADMIN, USER |
7.5.46. UC_045-User unmarks existing false positive definitons
A user wants to unmark existing false positives This means the false positives has been marked before.
This will NOT change any former job report where the false positive to unmark has been filtered! |
After next scan job the former false positive is no longer filtering the finding.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to remove existing false positive definition |
SUPERADMIN, USER |
7.5.47. UC_046-User fetches false positive configuration of project
A user wants to fetch false positive configuration of project.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to fetch existing false positive configuration of project |
SUPERADMIN, 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 |
SUPERADMIN |
2 |
Administrator adds a new product executor configuration by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator deletes an existing product executor configuration by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator fetches list of existing product executor configurations by calling REST API, will not contain setup information |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator fetches setup of an existing product executor configuration by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator updates setup for an existing product executor configuration by calling REST API |
2 |
Service call |
SUPERADMIN |
2 |
Service updates existing executor configuration |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator adds a new product execution profile by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator deletes an existing product execution profile by calling REST API |
2 |
Service call |
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 |
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 |
SUPERADMIN |
2 |
Administrator fetches setup of an existing product executor configuration by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator fetches lsit of all available execution profiles by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator adds profile relation to project by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
Administrator removes profile relation to project by calling REST API |
2 |
Service call |
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 |
SUPERADMIN |
2 |
MetaData will be updated |
2 |
Update project |
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 |
SUPERADMIN |
2 |
Administrator does call rest API to set new project owner |
2 |
Change project owner |
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 |
SUPERADMIN |
2 |
Changes project description. Json returned containing details about changed project |
2 |
Service changes project description. |
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 |
SUPERADMIN |
2 |
Admin does call REST API to change project access level |
2 |
Change access level |
SUPERADMIN |
3 |
The service will change the project access level inside administration domain and trigger a change event to inform recipients about the new situation. |
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 |
SUPERADMIN |
2 |
User emaill address will be changed |
2 |
Service updates user email address. |
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 |
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
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
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 |
3 |
deletes old job information |
|
3 |
Schedule cipher pool data cleanup |
Removes cipher pool data entries from database which are no longer used by any job |
7.5.70. UC_069-User uploads binaries
A user wants to upload binaries for a former created SecHub job.
The binaries must be inside a valid tar file.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find project and upload binaries as tar |
USER |
When project is found and user has access and job is initializing the binaries file will be uploaded |
7.5.71. UC_070-User downloads job report in SPDX format
A user wants to download a SPDX report for a finished SecHub
job
using the job UUID.
Only SPDX JSON is supported.
In case, there is no SPDX JSON result for a given job an error will be thrown.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get SPDX JSON report |
SUPERADMIN, 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 |
SUPERADMIN, 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 |
SUPERADMIN |
2 |
Json returned containing details about user and her/his projects |
2 |
Service fetches user details. |
SUPERADMIN |
The service will fetch user details for given user email address |
7.5.74. UC_073-Admin starts encryption rotation
An administrator starts encryption rotation.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Admin triggers rotation of encryption via REST |
2 |
Service call |
3 |
Triggers rotation of encryption via domain message |
|
3 |
Service call |
4 |
Forces new cipher pool entry creation and triggers encryption service pool refresh |
|
4 |
Service call |
5 |
Creates new cipher pool entry in database in own transaction |
|
5 |
Refresh encryption pool |
6 |
Encryption pool is refreshed (necessary because pool changed before this method call) |
|
6 |
Update encrypted data |
Encrypted data is updated (a direct pool refresh was triggered by admin action) |
7.5.75. UC_074-Scheduler encryption pool refresh
The scheduler refreshes its encryption pool data to handle new setup
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Init encryption pool |
3 |
Encryption pool is created on startup |
|
1 |
Encryption pool data refresh trigger |
2 |
Scheduler instance will check if encryption pool is in sync with the database definitions. If not, the instance will try to create new encryption pool object and provide the new setup. |
|
2 |
Refresh encryption pool |
3 |
Encryption pool is refreshed (if necessary) |
|
3 |
Update encrypted data |
Encrypted data is updated (all other cluster members) |
7.5.76. UC_075-Scheduler rotates data encryption
The scheduler checks for old encrypted data and will encrypt with latest cipher
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Update encrypted data |
Final update of encrypted job data. Will update all SecHub jobs having a pool id which is lower than latest from encryption pool |
7.5.77. UC_076-Admin fetches encryption status
An administrator fetches encryption status from all domains where encryption is used.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Service call |
1 |
Services collects encryption status from domains via event bus |
|
1 |
Rest call |
SUPERADMIN |
Admin fetches encryption status from domains via REST |
7.5.78. UC_077-SecHub does cleanup encryption
Secub does an ecnryption cleanup.
Inside relevant domains the encryption situation will be checked and old encryption setup, which is no longer necessary, will be dropped.
For example: When encryption was done with formerly via ENV variable
SECRET_1_AES_256
and the new one setup is using SECRET_2_AES_256
and
all jobs have been migrated to the new encryption, the cipher setup
using SECRET_1_AES_256
will become obsolete and will be automatically
removed. After the remove is done, there is no longer a need to
start the server with SECRET_1_AES_256
, but only with SECRET_2_AES_256
…
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Schedule cipher pool data cleanup |
Removes cipher pool data entries from database which are no longer used by any job |
7.5.79. UC_078-User unmarks existing false positive project data definitons
A user wants to unmark existing false positives This means the false positives has been marked before.
This will NOT change any former job report where the false positive to unmark has been filtered! |
After next scan job the former false positive is no longer filtering the finding.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to remove existing false positive project data definition by id |
SUPERADMIN, USER |
7.5.80. UC_079-System suspends running jobs on SIGTERM
When a SecHub instance is receiving a SIGTERM signal from OS, the server instance must block further job processing (on this instance) and suspend all of its running jobs. Because after some time the job will be resumed by another instance, this process will not stop any running PDS jobs.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduler terminates |
2 |
Scheduler instance is terminating. Will stop processing new jobs and inform job executor to suspend |
|
2 |
Scheduler job executor suspends current jobs |
3 |
Scheduler instance is terminating. Will mark current running jobs of this instance as SUSPENDED |
|
3 |
Scheduler job executor suspends current jobs |
4 |
Scheduler instance is terminating. Will mark current running jobs of this instance as SUSPENDED |
|
4 |
Scan job executor stops suspended jobs |
5 |
Scheduler instance has marked jobs as suspended. Will stop execution of scans of these jobs |
|
5 |
Scan job executable handles SUSPEND state |
6 |
Scan job executable stops execution because suspended |
|
6 |
Inform listeners |
7 |
Inform listeners about job suspension |
|
7 |
Administration handles suspended job |
Administration domain removes suspended job from its running job list |
7.5.81. UC_080-System resumes suspended jobs
SecHub jobs which have been suspended a minimum duration time will be restarted automatically.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Schedule suspended jobs |
2 |
Scheduler checks not only for new jobs but also for resumed ones. |
|
2 |
Resolve next job |
3 |
Resolves UUID of job which shall be executed at next time. If there is a suspended job and shall be resumed this job will be returned. Otherwise the selected schedule strategy will be used to determine next job uuid. Remark: A suspended job shall only be executed when the minium duration time has been reached. The time period can be configured and prevents side effects at deployments. |
|
3 |
Mark next job to execute |
4 |
When a suspended job is the next one, the job execution state will be changed to RESUMING |
|
4 |
Resume job |
The SecHub job will be resumed. This is done by triggering a soft restart request for the job. You can read Admin restarts a job for the steps which are
done at restart process. The steps are the same, except there is no audit logging
and the event is not triggered from |
7.5.82. UC_081-get assigned project data
User, Owner or Admin fetches a list containing information about assigned and/ or owned projects.
The Project data contains the following information:
-
Project ID
-
Owner
-
is owned
-
assigned users (can only be viewed by owner or admin)
A project user can see only projects he is assigned to. A project owner can see all projects he owns and the assigned users. A project admin can see assigned or owned projects and all assigned users.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest API call to get Projects with information |
OWNER, SUPERADMIN, USER |
Rest api call to get projects with details |
7.5.83. UC_082-Admin creates or updates a template
An administrator creates or updates a template
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to create or update template |
SUPERADMIN |
2 |
|
2 |
Service creates or updates template |
7.5.84. UC_083-Admin deletes a template
An administrator deletes a template. Will also remove any association between projects and this template
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to delete a template |
SUPERADMIN |
2 |
|
2 |
Service removes all assignments and deletes template completely |
7.5.85. UC_084-Admin fetches template
An administrator fetches template data by its id
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to fetch template |
SUPERADMIN |
2 |
|
2 |
Service fetches template |
7.5.86. UC_085-Admin fetches all template ids
An administrator fetches a list containing all templates ids
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to fetch template list |
SUPERADMIN |
2 |
|
2 |
Services fetches all template ids |
7.5.87. UC_086-Admin assigns template to project
An administrator assigns a template to a project
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Admin does call REST API to assign a template to project |
2 |
service assigns template to project |
SUPERADMIN |
3 |
The service will request the template assignment in domain 'scan' via synchronous event and updates mapping in domain 'administration' afterwards |
3 |
service assigns project to template in scan domain |
7.5.88. UC_087-Admin unassigns template from project
An administrator unassigns a template from a project
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Admin does call REST API to unassign a template from project |
2 |
service unassigns template from project |
SUPERADMIN |
3 |
The service will request the template unassignment in domain 'scan' via synchronous event and updates mapping in domain 'administration' afterwards |
3 |
service unassigns project from template in scan domain |
7.5.89. UC_088-Admin uploads an asset file
An administrator uploads a file for an asset. If the file already exists, it will be overriden.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to upload a file for an asset |
SUPERADMIN |
2 |
|
2 |
Service tries to upload file for asset |
Uploaded file will be stored in database and in storage |
7.5.90. UC_089-Admin downloads an asset file
An administrator downloads a file fom an asset.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to download a file for an asset |
SUPERADMIN |
2 |
|
2 |
Service downloads asset file from database |
7.5.91. UC_090-Admin fetches asset ids
An administrator fetches all available asset ids.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to fetch all availbale asset ids |
SUPERADMIN |
2 |
|
2 |
Service fetches all asset ids from database |
7.5.92. UC_091-Admin fetches asset details
An administrator fetches details about an asset. For example: the result will contain names but also checksum of files.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to fetch details about asset |
SUPERADMIN |
2 |
|
2 |
Service fetches asset details for given asset id |
7.5.93. UC_092-Admin deletes an asset file
An administrator deletes a file fom an asset.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to delete an asset file |
SUPERADMIN |
2 |
|
2 |
Services deletes file from asset |
7.5.94. UC_093-Admin deletes asset comletely
An administrator deletes an asset completely.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to delete complete asset |
SUPERADMIN |
2 |
|
2 |
Services deletes all asset parts |
7.6. Rest API documentation
7.6.1. Overview
7.6.1.1. Anonymous
All these usecases handling anonymous access.
7.6.1.2. User administration
Usecases handling administration of users
7.6.1.3. Project administration
Usecases for project administration
7.6.1.4. User profile
User actions belonging to their profiles
7.6.1.5. Sechub execution
Execution of SecHub -either by CLI or direct with REST api call
7.6.1.6. Sign up
All these usecases are handling user sign up (part of user self registration process)
7.6.1.7. Job administration
Usecases about job administration
7.6.1.8. Testing
Some use cases for testing
7.6.1.9. Configuration
Usecases for configuration parts
-
REST API for UC_049-Admin fetches executor configuration list
-
REST API for UC_051-Admin updates executor configuration setup
-
REST API for UC_057-Admin assigns execution profile to project
-
REST API for UC_058-Admin unassigns execution profile from project
-
REST API for UC_064-Admin fetches auto cleanup configuration
-
REST API for UC_065-Admin updates auto cleanup configuration
7.6.1.10. Encryption
Usecases for encryption parts
7.6.2. Check if the server is alive and running.
REST API for usecase UC_039-Check if the server is alive and running.
7.6.2.1. HEAD variant
Definition
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
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
Value | |
---|---|
Path |
/api/admin/users |
Method |
GET |
Status code |
200 OK |
Response fields
Path | Type | Description |
---|---|---|
|
|
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
REST API for usecase UC_015-Admin assigns user to project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/membership/{userId} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
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
REST API for usecase UC_016-Admin unassigns user from project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/membership/{userId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
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
Value | |
---|---|
Path |
/api/admin/user/{userId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The user id of user to show details for |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the user |
|
|
The email address of the user |
|
|
True, when this user is a super administrator |
|
|
The projects the user has access to |
|
|
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
Value | |
---|---|
Path |
/api/admin/user/{userId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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
REST API for usecase UC_021-Admin shows project details
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id to show details for |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the project |
|
|
A list of all users having access to the project |
|
|
Username of the owner of this project. An owner is the person in charge. |
|
|
A list of all whitelisted URIs. Only these ones can be scanned for the project! |
|
|
A list of all templates assigned to the project |
|
|
An JSON object containing metadata key-value pairs defined for this project. |
|
|
An arbitrary metadata key |
|
|
The project access level |
|
|
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"],"templateIds":[],"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
REST API for usecase UC_026-Admin downloads all details about a scan job
Definition
Value | |
---|---|
Path |
/api/admin/scan/download/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/scan/download/9fa80123-9818-499a-b9fc-0ca9aaadd100' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
7.6.10. Admin grants admin rights to user
REST API for usecase UC_027-Admin grants admin rights to user
Definition
Value | |
---|---|
Path |
/api/admin/user/{userId}/grant/superadmin |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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
REST API for usecase UC_028-Admin revokes admin rights from an admin
Definition
Value | |
---|---|
Path |
/api/admin/user/{userId}/revoke/superadmin |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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
Value | |
---|---|
Path |
/api/admin/admins |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
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
REST API for usecase UC_060-Admin changes owner of a project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/owner/{userId} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
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
REST API for usecase UC_063-Admin updates user email address
Definition
Value | |
---|---|
Path |
/api/admin/user/{userId}/email/{emailAddress} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The userId of the user whose email address will be changed |
|
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
REST API for usecase UC_072-Admin shows user details for email address
Definition
Value | |
---|---|
Path |
/api/admin/user-by-email/{emailAddress} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The email address of user to show details for |
Request headers
Name | Description |
---|---|
|
Basic authentication credentials |
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the user |
|
|
The mail address of the user |
|
|
True, when this user is a super administrator |
|
|
The projects the user has access to |
|
|
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
Value | |
---|---|
Path |
/api/admin/project |
Method |
POST |
Status code |
201 CREATED |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Name of the project to create. Is also used as a unique ID! |
|
|
The description of the project. |
|
|
Username of the owner of this project. An owner is the person in charge |
|
|
All URIs used now for whitelisting. Former parts will be replaced completely! |
|
|
An JSON object containing metadata key-value pairs defined for this project |
|
|
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
Value | |
---|---|
Path |
/api/admin/projects |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
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
Value | |
---|---|
Path |
/api/admin/project/{projectId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id 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
Value | |
---|---|
Path |
/api/admin/project/{projectId}/whitelist |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project for which whitelist shall be updated |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
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
REST API for usecase UC_025-Admin shows scan logs for project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/scan/logs |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
An array of scan log summary entries |
|
|
The user id of the user which executed the scan |
|
|
The timestamp when the scan was started |
|
|
The timestamp when the scan was ended |
|
|
A status field about scan situation |
|
|
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":"56761894-d5c0-4a7e-b799-da9a230e8874","executedBy":"spartakus","started":"2024-12-17T14:20:31.686696258","ended":"2024-12-18T14:20:31.68671901","status":"OK"}]
7.6.21. Update project metadata
REST API for usecase UC_059-Update project metadata
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/metadata |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project for which metadata shall be updated |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Metadata object. Contains key-value pairs. |
|
|
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
REST API for usecase UC_061-Admin changes project description
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id to change details for |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the project. |
|
|
A list of all users having access to the project. |
|
|
Username of the owner of this project. An owner is the person in charge. |
|
|
A list of all whitelisted URIs. Only these ones can be scanned for the project! |
|
|
A list of all templates assigned to the project |
|
|
An JSON object containing metadata key-value pairs defined for this project. |
|
|
An arbitrary metadata key |
|
|
The project access level |
|
|
The project access level |
|
|
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"],"templateIds":[],"metaData":{"key1":"value1"},"owner":"name1","description":"description","accessLevel":"full","whiteList":["http://www.sechub.example.org"]}
7.6.23. Admin changes project access level
REST API for usecase UC_062-Admin changes project access level
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/accesslevel/{projectAccessLevel} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
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)
7.6.24. get assigned project data
REST API for usecase UC_081-get assigned project data
Definition
Value | |
---|---|
Path |
/api/projects |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Project ID |
|
|
Name of owner of the Project |
|
|
If caller is owner of the project |
|
|
Optional: Assigned users (only viewable by owner or admin) |
Example
Curl request
$ curl 'https://sechub.example.com/api/projects' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
[{"projectId":"project1","owner":"user1","assignedUsers":["user1","user2"],"isOwned":true}]
7.6.25. User clicks link to get new api token
REST API for usecase UC_012-User clicks link to get new api token
Definition
Value | |
---|---|
Path |
/api/anonymous/apitoken/{oneTimeToken} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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.26. User creates a new sechub job
REST API for usecase UC_005-User creates a new sechub job
7.6.26.1. Code Scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Code scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Code scan sources from given file system folders |
|
|
Code scan sources from given file system files |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"61c45d37-8248-447a-bde6-32959701f733"}
7.6.26.2. Code Scan using data section variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Code scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Unique reference name |
|
|
Sources from given file system folders |
|
|
Sources from given file system files |
|
|
Unique reference name |
|
|
Binaries from given file system folders |
|
|
Binaries from given file system files |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"43037115-9512-49ca-a4c9-8cd854db18f9"}
7.6.26.3. Secret scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Secret scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Unique reference name |
|
|
Unique reference name |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"e978e13f-c716-4355-a9d4-598eb902362e"}
7.6.26.4. License scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
License scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Unique reference name |
|
|
Unique reference name |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"b3104bff-5a00-4486-bfc5-627bb42295ad"}
7.6.26.5. Infrastructure scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Infrastructure configuration block |
|
|
Infrastructure URIs to scan for |
|
|
Infrastructure IPs to scan for |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"9c5ee3b5-44bb-43fd-b431-2fb2508272fc"}
7.6.26.6. Web scan anonymous variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Duration of the scan as integer |
|
|
Unit of the duration. Possible values are: millisecond(s), second(s), minute(s), hour(s), day(s) |
|
|
Include URL sub-paths to scan. Example: /hidden |
|
|
Exclude URL sub-paths to scan. Example: /admin |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"7e08a4fa-d8e9-47ae-8757-589984fcac5f"}
7.6.26.7. Web scan with api definition variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Type of the API definition files that will be provided |
|
|
Reference to the data section containing the API definition files. Always use 'sources' with 'files' instead 'folders'. |
|
|
Specifies an URL to read the API definition from. |
Response fields
Path | Type | Description |
---|---|---|
|
|
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","apiDefinitionUrl":"https://www.example.org/api/v1/swagger/","use":["openApi-file-reference"]},"url":"https://www.example.org/"},"apiVersion":"1.0"}'
Response body
{"jobId":"644e40da-5f07-43a7-acb7-acf61c662935"}
7.6.26.8. Web scan with client certificate definition variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Password the client certificate file is protected with |
|
|
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 |
---|---|---|
|
|
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":"6933bc23-24b8-4806-8d8b-0f30209a53ee"}
7.6.26.9. Web Scan login basic variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Webscan login definition |
|
|
Login URL |
|
|
basic login definition |
|
|
username |
|
|
password |
Response fields
Path | Type | Description |
---|---|---|
|
|
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":"3a1e2b09-b280-4841-a84e-2cbef10b8c97"}
7.6.26.10. Web Scan login form scripted variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Webscan login definition |
|
|
Optional TOTP configuration as an additional authentication factor. |
|
|
The seed/secret for the TOTP generation. If TOTP is configured this parameter is mandatory. |
|
|
The time in seconds the generated TOTP is valid. In most cases nothing is specified and the default of '30' seconds is used. |
|
|
The length of the generated TOTP. In most cases nothing is specified and the default length '6' is used. |
|
|
The hash algorithm to generate the TOTP. In most cases nothing is specified and the default hash algorithm 'HMAC_SHA1' is used. Currently available values are: 'HMAC_SHA1', 'HMAC_SHA256', 'HMAC_SHA512' |
|
|
The encoding type of the 'seed'. The default value is 'AUTODETECT'. Currently available values are: 'BASE64', 'BASE32', 'HEX', 'PLAIN', 'AUTODETECT' |
|
|
Login URL |
|
|
form login definition |
|
|
script |
|
|
action type: username, password, input, click, wait |
|
|
css selector |
|
|
value |
|
|
description |
|
|
the time unit to wait: millisecond, second, minute, hour, day. |
Response fields
Path | Type | Description |
---|---|---|
|
|
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"}]}]}},"totp":{"seed":"example-seed","validityInSeconds":30,"tokenLength":6,"hashAlgorithm":"HMAC_SHA1","encodingType":"BASE32"}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'
Response body
{"jobId":"8d662bf3-b26f-448d-b280-2e87e5d9c6f3"}
7.6.26.11. Web Scan headers variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
List of HTTP headers. Can be used for authentication or anything else. |
|
|
Name of the defined HTTP header. |
|
|
Value of the defined HTTP header. Either specify the header value directly here or reference a data section with 'use' e.g. if the value is to big, but never specify both. |
|
|
Reference to the data section containing a file with the value for this header, e.g if the value is to big for the sechub configuration. Always use 'sources' with a single 'file' instead 'folders'. |
|
|
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 |
|
|
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 |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"url":"https://localhost/mywebapp","headers":[{"name":"api-token","value":"secret","onlyForUrls":["https://localhost/mywebapp/admin","https://localhost/mywebapp/<*>/profile","https://localhost/mywebapp/blog/<*>"],"sensitive":true,"use":["header-value-file-ref-for-big-tokens"]}]},"apiVersion":"1.0"}'
Response body
{"jobId":"81cbab4b-9e6e-4bc9-8d78-a0188a1af262"}
7.6.27. User uploads source code
REST API for usecase UC_006-User uploads source code
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID}/sourcecode |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where sourcecode shall be uploaded for |
|
The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub. |
Query parameters
Parameter | Description |
---|---|
|
A sha256 checksum for file upload validation |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job/1e1c0907-6f3f-4615-9758-2916563ba8f2/sourcecode?checkSum=checkSumValue' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-F 'file=PK
�<M test1.txtPK ?
�<M $ test1.txt
��IW� ��IW� ��IW� PK [ ' '
Response body
(empty)
7.6.28. User approves sechub job
REST API for usecase UC_007-User approves sechub job
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID}/approve |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where sechub job shall be approved |
|
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/6738b3a3-56b0-4597-95b2-8f09fb50e64a/approve' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.29. User checks sechub job state
REST API for usecase UC_009-User checks sechub job state
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where sechub job was started for |
|
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 |
---|---|---|
|
|
The job uuid |
|
|
Creation timestamp of job |
|
|
Start timestamp of job execution |
|
|
End timestamp of job execution |
|
|
Owner / initiator of job |
|
|
State of job |
|
|
Result of job |
|
|
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/2879e71b-6bf6-44d1-9b69-e60c3b080288' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"jobUUID":"2879e71b-6bf6-44d1-9b69-e60c3b080288","owner":"CREATOR1","created":"","started":"2024-12-18T14:05:29.794678032","ended":"2024-12-18T14:20:29.794707817","state":"ENDED","result":"OK","trafficLight":"GREEN"}
7.6.30. User downloads sechub job report
REST API for usecase UC_010-User downloads sechub job report
7.6.30.1. JSON variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/report/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/report/bdcf655e-5c21-436e-978b-9e217be8d322' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
7.6.30.2. HTML variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/report/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/report/5d0352c5-4779-4d15-ab8e-8da21d57d398' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/xhtml+xml'
7.6.31. User marks false positives
REST API for usecase UC_044-User marks false positives
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positives |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The projectId of the project where users adds false positives for |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
The type of the json content. Currently only accepted value is 'falsePositiveDataList' but we also still accept the deprecated type 'falsePositiveJobDataList'. |
|
|
Job data list containing false positive setup based on former jobs |
|
|
SecHub job uuid where finding was |
|
|
SecHub finding identifier - identifies problem inside the job which shall be markeda as a false positive. |
|
|
A comment describing why this is a false positive |
|
|
Project data list containing false positive setup for the project |
|
|
Identifier which is used to update or remove the respective false positive entry. |
|
|
A comment describing why this is a false positive. |
|
|
Defines a section for false positives which occur during webscans. |
|
|
Defines a url pattern for false positives which occur during webscans. Can be used with wildcards like '.host.com'. Each entry must contain more than just wildcards, '..' or '*' are not allowed. |
|
|
Defines a list of (HTTP) methods for false positives which occur during webscans. This is optional and if nothing is specified, the entry applies to all methods. |
|
|
Defines a CWE ID for false positives which occur during webscans. This is mandatory, but can be empty. If it is not specified it matches the findings with no CWE IDs. |
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":"falsePositiveDataList","jobData":[{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"an optional comment why this is a false positive..."}],"projectData":[{"id":"unique-identifier","webScan":{"cweId":564,"urlPattern":"https://*.example.com/api/*/search","methods":["GET","POST"]},"comment":"an optional comment for this false positive project entry"}]}'
Response body
(empty)
7.6.32. User unmarks existing false positive definitons
REST API for usecase UC_045-User unmarks existing false positive definitons
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positive/{jobUUID}/{findingId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
Job uuid |
|
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.33. User fetches false positive configuration of project
REST API for usecase UC_046-User fetches false positive configuration of project
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positives |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Job data list containing false positive setup based on former jobs |
|
|
User id of author who created false positive |
|
|
Creation timestamp |
|
|
Meta data for this false positive |
|
|
Scan type - e.g. codeScan |
|
|
Name of origin finding marked as false positive |
|
|
CWE (common weakness enumeration). For code scans this is always set. |
|
|
CVE (common vulnerability and exposures). For infra scans this is always set. |
|
|
OWASP At least this field must be set for web scans when no cwe identifier is defined. |
|
|
Severity of origin report entry marked as false positive |
|
|
Code part. Only available for scan type 'codeScan' |
|
|
entry point |
|
|
location of code |
|
|
relevant part of source vulnerability |
|
|
source code |
|
|
end point (sink) |
|
|
location of code |
|
|
relevant part of source vulnerability |
|
|
source code |
|
|
Job data parts, can be used as key to identify false positives |
|
|
SecHub job uuid where finding was |
|
|
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! |
|
|
A comment from author describing why this was marked as a false positive |
|
|
Project data list containing false positive setup for the project. |
|
|
Identifier which is used to update or remove the respective false positive entry. |
|
|
A comment describing why this is a false positive. |
|
|
Defines a section for false positives which occur during webscans. |
|
|
Defines a url pattern for false positives which occur during webscans. Can be used with wildcards like '.host.com'. Each entry must contain more than just wildcards, '..' or '*' are not allowed. |
|
|
Defines a list of (HTTP) methods for false positives which occur during webscans. This is optional and if nothing is specified, the entry applies to all methods. |
|
|
Defines a CWE ID for false positives which occur during webscans. This is mandatory, but can be empty. If it is not specified it matches the findings with no CWE IDs. |
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},"projectData":{"id":"unique-identifier","webScan":{"cweId":564,"urlPattern":"https://*.example.com/api/*/search","methods":["GET","POST"]},"comment":"an optional comment for this false positive project entry"},"created":"2020-06-12 11:53:15"}]}
7.6.34. User uploads binaries
REST API for usecase UC_069-User uploads binaries
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID}/binaries |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project for which the binaries are uploaded for |
|
The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub. |
Request headers
Name | Description |
---|---|
|
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/9b86d0ea-f044-4663-86fc-a0c59e2664a8/binaries' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-H 'x-file-size: 10240' \
-F 'file=test1.txt 0000664 0001750 0001750 00000000000 13353454574 012170 0 ustar albert albert ' \
-F 'checkSum=checkSumValue'
Response body
(empty)
7.6.35. User downloads job report in SPDX format
REST API for usecase UC_070-User downloads job report in SPDX format
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/report/spdx/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/report/spdx/57d1be13-f92a-4159-9ea8-56d601ed73d3' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
7.6.36. User unmarks existing false positive project data definitons
REST API for usecase UC_078-User unmarks existing false positive project data definitons
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positive/project-data/{id} |
Method |
DELETE |
Status code |
204 NO_CONTENT |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
Identifier which is used to remove the respective false positive entry. |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positive/project-data/unique-identifier' -i -u 'user:secret' -X DELETE
Response body
(empty)
7.6.37. User self registration
REST API for usecase UC_001-User self registration
Definition
Value | |
---|---|
Path |
/api/anonymous/signup |
Method |
POST |
Status code |
200 OK |
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Wanted userid, the userid must be lowercase only! |
|
|
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.38. Admin lists open user signups
REST API for usecase UC_002-Admin lists open user signups
Definition
Value | |
---|---|
Path |
/api/admin/signups |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
List of user signups |
|
|
The user id |
|
|
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.39. Admin applies self registration
REST API for usecase UC_003-Admin applies self registration
Definition
Value | |
---|---|
Path |
/api/admin/signup/accept/{userId} |
Method |
POST |
Status code |
201 CREATED |
Path parameters
Parameter | Description |
---|---|
|
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.40. Admin deletes user signup
REST API for usecase UC_019-Admin deletes user signup
Definition
Value | |
---|---|
Path |
/api/admin/signup/{userId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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.41. User requests new API token
REST API for usecase UC_024-User requests new API token
Definition
Value | |
---|---|
Path |
/api/anonymous/refresh/apitoken/{emailAddress} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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.42. Admin lists all running jobs
REST API for usecase UC_023-Admin lists all running jobs
Definition
Value | |
---|---|
Path |
/api/admin/jobs/running |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The uuid of the running job |
|
|
The name of the project the job is running for |
|
|
Owner of the job - means user which triggered it |
|
|
A status information |
|
|
Timestamp since when job has been started |
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":"12ae7889-fd46-44c0-a6f0-3da719174376","projectId":"project-name","owner":"owner-userid","status":"RUNNING","since":"2024-12-18T14:20:36.657777563"}]
7.6.43. Admin cancels a job
REST API for usecase UC_034-Admin cancels a job
Definition
Value | |
---|---|
Path |
/api/admin/jobs/cancel/{jobUUID} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/cancel/51a0803b-519f-4ff5-914d-2de214e3c8ab' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.44. Admin restarts a job
REST API for usecase UC_041-Admin restarts a job
Definition
Value | |
---|---|
Path |
/api/admin/jobs/restart/{jobUUID} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/restart/411bf48a-4b38-4de0-a8fc-094e90c1071b' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.45. Admin restarts a job (hard)
REST API for usecase UC_042-Admin restarts a job (hard)
Definition
Value | |
---|---|
Path |
/api/admin/jobs/restart-hard/{jobUUID} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/restart-hard/8d3f64db-a0b1-49ce-aad7-ec0c00eccd21' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.46. User defines mock data configuration for project
REST API for usecase UC_035-User defines mock data configuration for project
Definition
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.47. User retrieves mock data configuration for project
REST API for usecase UC_036-User retrieves mock data configuration for project
Definition
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.48. Admin updates mapping configuration
REST API for usecase UC_037-Admin updates mapping configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/mapping/{mappingId} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The mappingID, identifiying which mapping shall be updated |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
Pattern |
|
|
Replacement |
|
|
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.49. Admin fetches mapping configuration
REST API for usecase UC_038-Admin fetches mapping configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/mapping/{mappingId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The mapping Id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Pattern |
|
|
Replacement |
|
|
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.50. Admin creates an executor configuration
REST API for usecase UC_047-Admin creates an executor configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/executor |
Method |
POST |
Status code |
201 CREATED |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
A name for this configuration |
|
|
Executor product identifier |
|
|
Executor version |
|
|
Enabled state of executor, per default false |
|
|
Base URL to the product |
|
|
User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable |
|
|
Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable |
|
|
Job parameter key |
|
|
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 configuration 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
330dec38-f69a-48a9-85ac-e05fd3bc5835
7.6.51. Admin deletes executor configuration
REST API for usecase UC_048-Admin deletes executor configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/executor/{uuid} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The configuration uuid |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor/797b8c7a-d678-47ee-a82b-3d4c3bd9e298' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.52. Admin fetches executor configuration list
REST API for usecase UC_049-Admin fetches executor configuration list
Definition
Value | |
---|---|
Path |
/api/admin/config/executors |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Always |
|
|
The uuid of the configuration |
|
|
The configuration name |
|
|
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":"b069a976-7615-483b-ba01-228c9f439586","name":"example configuration","enabled":true}],"type":"executorConfigurationList"}
7.6.53. Admin fetches executor configuration
REST API for usecase UC_050-Admin fetches executor configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/executor/{uuid} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The configuration uuid |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The uuid of this configuration |
|
|
The name of this configuration |
|
|
Executor product identifier |
|
|
Executor version |
|
|
Enabled state of executor |
|
|
Base URL to the product |
|
|
User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable |
|
|
Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable |
|
|
Job parameter key |
|
|
Job parameter value |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor/0fa0f267-bcda-4af5-8718-2a21f5401c7e' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"uuid":"0fa0f267-bcda-4af5-8718-2a21f5401c7e","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}
7.6.54. Admin updates executor configuration setup
REST API for usecase UC_051-Admin updates executor configuration setup
Definition
Value | |
---|---|
Path |
/api/admin/config/executor/{uuid} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The configuration uuid |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The name of this configuration |
|
|
Executor product identifier |
|
|
Executor version |
|
|
Enabled state of executor, per default false |
|
|
Base URL to the product |
|
|
User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable |
|
|
Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable |
|
|
Job parameter key |
|
|
Job parameter value |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor/8eef81fa-6d9b-466f-91af-8dd5f484032c' -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.55. Admin creates an execution profile
REST API for usecase UC_052-Admin creates an execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
POST |
Status code |
201 CREATED |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
A short description for the profile |
|
|
Enabled state of profile, default is false |
|
|
Configurations can be linked at creation time as well - see update description |
|
|
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.56. Admin deletes execution profile
REST API for usecase UC_053-Admin deletes execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
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.57. Admin updates execution profile
REST API for usecase UC_054-Admin updates execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
A short description for the profile |
|
|
Enabled state of profile, default is false |
|
|
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":"5dce0528-5a02-44f7-91c2-da1ccde4c2bc","executorVersion":0,"enabled":false,"setup":{"credentials":{},"jobParameters":[]}}],"enabled":true}'
Response body
(empty)
7.6.58. Admin fetches execution profile
REST API for usecase UC_055-Admin fetches execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
A short description for the profile |
|
|
Enabled state of profile, default is false |
|
|
uuid of configuration |
|
|
name of configuration |
|
|
enabled state of this configuration |
|
|
executed product |
|
|
executor version |
|
|
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":[{"uuid":"5208b8bc-ecb3-415d-a084-fbb4c37f1dd8","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}],"projectIds":["project-1","project-2"]}
7.6.59. Admin fetches execution profile list
REST API for usecase UC_056-Admin fetches execution profile list
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profiles |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Always |
|
|
The profile id |
|
|
A profile description |
|
|
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.60. Admin assigns execution profile to project
REST API for usecase UC_057-Admin assigns execution profile to project
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId}/project/{projectId} |
Method |
POST |
Status code |
201 CREATED |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
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.61. Admin unassigns execution profile from project
REST API for usecase UC_058-Admin unassigns execution profile from project
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId}/project/{projectId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
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.62. Admin fetches auto cleanup configuration
REST API for usecase UC_064-Admin fetches auto cleanup configuration
Definition
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.63. Admin updates auto cleanup configuration
REST API for usecase UC_065-Admin updates auto cleanup configuration
Definition
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.64. Admin creates or updates a template
REST API for usecase UC_082-Admin creates or updates a template
Definition
Value | |
---|---|
Path |
/api/admin/template/{templateId} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The (unique) template id |
Request fields
Path | Type | Description |
---|---|---|
|
|
The template type. Must be be defined when a new template is created. An update will ignore changes of this property because the type is immutable! Currently supported types are: [Lcom.mercedesbenz.sechub.commons.model.template.TemplateType;@777f10f5 |
|
|
The asset id used by the template |
|
|
The variable name |
|
|
Defines if the variable is optional. The default is false |
|
|
Defines a simple validation segment. |
|
|
The minimum content length of this variable |
|
|
The maximum content length of this variable |
|
|
A regular expression which must match to accept the user input inside the variable |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/template/template1' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"type" : "WEBSCAN_LOGIN",
"variables" : [ {
"name" : "username",
"optional" : false,
"validation" : {
"minLength" : 3,
"maxLength" : 15,
"regularExpression" : "[a-zA-Z0-9_-].*"
}
} ],
"assetId" : "asset-id1"
}'
Response body
(empty)
7.6.65. Admin deletes a template
REST API for usecase UC_083-Admin deletes a template
Definition
Value | |
---|---|
Path |
/api/admin/template/{templateId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The (unique) template id |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/template/template1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.66. Admin fetches template
REST API for usecase UC_084-Admin fetches template
Definition
Value | |
---|---|
Path |
/api/admin/template/{templateId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The (unique) template id |
Response fields
Path | Type | Description |
---|---|---|
|
|
The template type. Currently supported types are: [Lcom.mercedesbenz.sechub.commons.model.template.TemplateType;@702d3fb4 |
|
|
The (unique) template id |
|
|
The asset id used by the template |
|
|
The variable name |
|
|
Defines if the variable is optional. The default is false |
|
|
Defines a simple validation segment. |
|
|
The minimum content length of this variable |
|
|
The maximum content length of this variable |
|
|
A regular expression which must match to accept the user input inside the variable |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/template/template1' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"id":"template1","type":"WEBSCAN_LOGIN","variables":[{"name":"username","optional":false,"validation":{"minLength":3,"maxLength":15,"regularExpression":"[a-zA-Z0-9_-].*"}}],"assetId":"asset-id1"}
7.6.67. Admin fetches all template ids
REST API for usecase UC_085-Admin fetches all template ids
Definition
Value | |
---|---|
Path |
/api/admin/templates |
Method |
GET |
Status code |
200 OK |
Response fields
Path | Type | Description |
---|---|---|
|
|
Array contains all existing template identifiers |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/templates' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
["template1","template2"]
7.6.68. Admin assigns template to project
REST API for usecase UC_086-Admin assigns template to project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/template/{templateId} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
The id of the template to assign to project |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/project/projectId1/template/template1' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.69. Admin unassigns template from project
REST API for usecase UC_087-Admin unassigns template from project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/template/{templateId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
The id of the template to unassign from project |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/project/projectId1/template/template1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.70. Admin uploads an asset file
REST API for usecase UC_088-Admin uploads an asset file
Definition
Value | |
---|---|
Path |
/api/admin/asset/{assetId}/file |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the asset to which the uploaded file belongs to |
Query parameters
Parameter | Description |
---|---|
|
A sha256 checksum for file upload validation |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/asset/asset-1/file?checkSum=c6965634c4ec8e4f5e72dffd36ea725860e8b485216260264a0973073805e422' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-F 'file=PK
�<M test1.txtPK ?
�<M $ test1.txt
��IW� ��IW� ��IW� PK [ ' '
Response body
(empty)
7.6.71. Admin downloads an asset file
REST API for usecase UC_089-Admin downloads an asset file
Definition
Value | |
---|---|
Path |
/api/admin/asset/{assetId}/file/{fileName} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The asset identifier |
|
The name of the file to download from asset |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/asset/asset-1/file/PRODUCT1.zip' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
7.6.72. Admin fetches asset ids
REST API for usecase UC_090-Admin fetches asset ids
Definition
Value | |
---|---|
Path |
/api/admin/asset/ids |
Method |
GET |
Status code |
200 OK |
Response fields
Path | Type | Description |
---|---|---|
|
|
Array contains all existing asset identifiers |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/asset/ids' -i -u 'user:secret' -X GET
Response body
["asset-1","asset-2"]
7.6.73. Admin fetches asset details
REST API for usecase UC_091-Admin fetches asset details
Definition
Value | |
---|---|
Path |
/api/admin/asset/{assetId}/details |
Method |
GET |
Status code |
200 OK |
Response fields
Path | Type | Description |
---|---|---|
|
|
The asset identifier |
|
|
Array containing data about files from asset |
|
|
Name of file |
|
|
Checksum for file |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/asset/asset-1/details' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"assetId":"asset-1","files":[{"fileName":"PRODUCT1.zip","checksum":"c6965634c4ec8e4f5e72dffd36ea725860e8b485216260264a0973073805e422"}]}
7.6.74. Admin deletes an asset file
REST API for usecase UC_092-Admin deletes an asset file
Definition
Value | |
---|---|
Path |
/api/admin/asset/{assetId}/file/{fileName} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The asset identifier |
|
The name of the file to delete inside the asset |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/asset/asset-1/file/PRODUCT1.zip' -i -u 'user:secret' -X DELETE
Response body
(empty)
7.6.75. Admin deletes asset comletely
REST API for usecase UC_093-Admin deletes asset comletely
Definition
Value | |
---|---|
Path |
/api/admin/asset/{assetId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The asset identifier for the asset which shall be deleted completely |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/asset/asset-1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.76. Admin starts encryption rotation
REST API for usecase UC_073-Admin starts encryption rotation
Definition
Value | |
---|---|
Path |
/api/admin/encryption/rotate |
Method |
POST |
Status code |
200 OK |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/encryption/rotate' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"algorithm" : "AES_GCM_SIV_256",
"passwordSourceType" : "ENVIRONMENT_VARIABLE",
"passwordSourceData" : "SECRET_1"
}'
Response body
(empty)
7.6.77. Admin fetches encryption status
REST API for usecase UC_076-Admin fetches encryption status
Definition
Value | |
---|---|
Path |
/api/admin/encryption/status |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The type description of the json content |
|
|
Name of the domain which will provide this encryption data elements |
|
|
Unique identifier |
|
|
Algorithm used for encryption |
|
|
Type of password source. Can be [NONE, ENVIRONMENT_VARIABLE] |
|
|
Data for password source. If type is ENVIRONMENT_VARIABLE then it is the the name of the environment variable. |
|
|
Map containing information about usage of this encryption |
|
|
Key value data |
|
|
Creation timestamp |
|
|
User id of admin who created the encryption entry |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/encryption/status' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"type":"encryptionStatus","domains":[{"name":"schedule","data":[{"id":"1","algorithm":"AES_GCM_SIV_256","passwordSource":{"type":"ENVIRONMENT_VARIABLE","data":"SECRET_1"},"usage":{"job.state.cancel_requested":4,"job.state.canceled":5,"job.state.ended":8,"job.state.initializing":1,"job.state.ready_to_start":2,"job.state.resuming":7,"job.state.started":3,"job.state.suspended":6},"createdFrom":"admin-username","created":"2024-08-01T09:26:00"}]}]}
7.6.78. Admin disables job processing in scheduler
REST API for usecase UC_030-Admin disables job processing in scheduler
Definition
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.79. Admin enables scheduler job processing
REST API for usecase UC_031-Admin enables scheduler job processing
Definition
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.80. Admin get scheduler status
REST API for usecase UC_032-Admin get scheduler status
Definition
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.81. Admin lists status information
REST API for usecase UC_033-Admin lists status information
Definition
Value | |
---|---|
Path |
/api/admin/status |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Status key identifier |
|
|
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.82. Admin fetches server runtime data
REST API for usecase UC_040-Admin fetches server runtime data
Definition
Value | |
---|---|
Path |
/api/admin/info/server |
Method |
GET |
Status code |
200 OK |
Response fields
Path | Type | Description |
---|---|---|
|
|
The sechub server version. |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/info/server' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"serverVersion":"0.12.3"}
7.6.83. User lists jobs for project
REST API for usecase UC_071-User lists jobs for project
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/jobs |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where job information shall be fetched for |
Query parameters
Parameter | Description |
---|---|
|
The wanted (maximum) size for the result set. When not defined, the default will be 1. |
|
The wanted page number. When not defined, the default will be 0. |
|
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. |
|
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 |
---|---|---|
|
|
The page number |
|
|
The total pages available |
|
|
The job uuid |
|
|
Creation timestamp of job |
|
|
Start timestamp of job execution |
|
|
End timestamp of job execution |
|
|
User who initiated the job |
|
|
Execution state of job |
|
|
Execution result of job |
|
|
Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF |
|
|
Meta data of job - but only contained in result, when query parameter |
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":"daead708-fd3d-4eb9-a682-023d81949bce","executedBy":"User1","created":"2024-12-18T14:03:29.990943124","started":"2024-12-18T14:05:29.990996303","ended":"2024-12-18T14:20:29.991009648","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
7.7.2.1. Overview
7.7.2.1.1. Diagram
7.7.2.1.2. List of all messages
7.7.2.2. Message ANALYZE_SCAN_RESULTS_AVAILABLE
7.7.2.3. Message AUTO_CLEANUP_CONFIGURATION_CHANGED
Use cases related to this message |
7.7.2.4. Message BINARY_UPLOAD_DONE
7.7.2.5. Message GET_ENCRYPTION_STATUS_SCHEDULE_DOMAIN
7.7.2.6. Message JOB_CANCELLATION_RUNNING
7.7.2.7. Message JOB_CREATED
7.7.2.8. Message JOB_DONE
Use cases related to this message |
7.7.2.9. Message JOB_EXECUTION_STARTING
Use cases related to this message |
7.7.2.10. Message JOB_FAILED
7.7.2.11. Message JOB_RESTART_CANCELED
Use cases related to this message |
7.7.2.12. Message JOB_RESTART_TRIGGERED
Use cases related to this message |
7.7.2.13. Message JOB_RESULTS_PURGED
Use cases related to this message |
7.7.2.14. Message JOB_RESULT_PURGE_DONE
7.7.2.15. Message JOB_RESULT_PURGE_FAILED
7.7.2.16. Message JOB_STARTED
Use cases related to this message |
7.7.2.17. Message JOB_SUSPENDED
7.7.2.18. Message MAPPING_CONFIGURATION_CHANGED
7.7.2.19. Message PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE
7.7.2.20. Message PROJECT_ACCESS_LEVEL_CHANGED
7.7.2.21. Message PROJECT_CREATED
7.7.2.22. Message PROJECT_DELETED
7.7.2.23. Message PROJECT_OWNER_CHANGED
7.7.2.24. Message PROJECT_WHITELIST_UPDATED
7.7.2.25. Message REQUEST_ASSIGN_TEMPLATE_TO_PROJECT
7.7.2.26. Message REQUEST_JOB_CANCELLATION
7.7.2.28. Message REQUEST_JOB_RESTART_HARD
Use cases related to this message |
7.7.2.29. Message REQUEST_PURGE_JOB_RESULTS
Use cases related to this message |
7.7.2.30. Message REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING
Use cases related to this message |
7.7.2.31. Message REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING
Use cases related to this message |
7.7.2.32. Message REQUEST_SCHEDULER_JOB_STATUS
Use cases related to this message |
7.7.2.33. Message REQUEST_SCHEDULER_STATUS_UPDATE
7.7.2.34. Message REQUEST_UNASSIGN_TEMPLATE_FROM_PROJECT
7.7.2.35. Message REQUEST_USER_ROLE_RECALCULATION
Use cases related to this message |
7.7.2.36. Message RESULT_ASSIGN_TEMPLATE_TO_PROJECT
7.7.2.37. Message RESULT_ENCRYPTION_STATUS_SCHEDULE_DOMAIN
7.7.2.38. Message RESULT_UNASSIGN_TEMPLATE_FROM_PROJECT
7.7.2.39. Message SCAN_DONE
7.7.2.40. Message SCAN_FAILED
7.7.2.41. Message SCAN_SUSPENDED
7.7.2.42. Message SCHEDULER_JOB_PROCESSING_DISABLED
Use cases related to this message |
7.7.2.43. Message SCHEDULER_JOB_PROCESSING_ENABLED
Use cases related to this message |
7.7.2.44. Message SCHEDULER_JOB_STATUS
7.7.2.45. Message SCHEDULER_STARTED
7.7.2.46. Message SCHEDULER_STATUS_UPDATE
7.7.2.47. Message SCHEDULE_ENCRYPTION_POOL_INITIALIZED
7.7.2.48. Message SOURCE_UPLOAD_DONE
7.7.2.49. Message START_ENCRYPTION_ROTATION
7.7.2.50. Message START_SCAN
Use cases related to this message |
7.7.2.51. Message UNSUPPORTED_OPERATION
7.7.2.52. Message USER_ADDED_TO_PROJECT
Use cases related to this message |
7.7.2.53. Message USER_API_TOKEN_CHANGED
7.7.2.54. Message USER_BECOMES_SUPERADMIN
7.7.2.56. Message USER_DELETED
7.7.2.57. Message USER_EMAIL_ADDRESS_CHANGED
7.7.2.58. Message USER_NEW_API_TOKEN_REQUESTED
Use cases related to this message |
7.7.2.59. Message USER_NO_LONGER_SUPERADMIN
7.7.2.60. Message USER_REMOVED_FROM_PROJECT
Use cases related to this message |
7.7.2.61. Message USER_ROLES_CHANGED
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.
Every product adapter must be provided and used by its own interface. Also the adapter project must provide:
-
Real adapter implementation
-
Additional mock variant
-
mock REST api calls etc.
-
returns a predefined set of an real output
-
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 |
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
8.2.1.1.2. PROD
As name offers, this profile is designed for production.
For production the profile |
8.2.1.1.3. DEV
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
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 |
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:
Key or variable name | 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. |
Key or variable name | Default | Description |
---|---|---|
sechub.user.onetimetoken.outdated.millis |
86400000 |
One time token time when outdating |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.checkmarx.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter check operation is called next. When -1 value is 1 minutes |
sechub.adapter.checkmarx.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.checkmarx.trustall |
false |
Turns off certification checks for this product only. Should only be used in test or development environments! |
Key or variable name | 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 |
Key or variable name | Default | Description |
---|---|---|
sechub.migration.flyway.autorepair |
true |
When enabled, flyway migration problems will be automatically repaired |
Key or variable name | 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! |
Key or variable name | 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! |
Key or variable name | 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 |
Key or variable name | Default | Description |
---|---|---|
sechub.user.onetimetoken.outdated.millis |
86400000 |
Time until the one time token expires |
Key or variable name | 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 |
Key or variable name | Default | Description |
---|---|---|
sechub.security.oauth2.jwt.jwk-set-uri |
null |
The URI to the JWK set of the identity provider. Required in 'JWT' mode. |
sechub.security.oauth2.mode |
null |
The OAuth2 mode to use for authentication. Must be either 'JWT' or 'OPAQUE_TOKEN'. |
sechub.security.oauth2.opaque-token.client-id |
null |
Client ID to use when authenticating against the identity provider. Required in 'OPAQUE_TOKEN' mode. |
sechub.security.oauth2.opaque-token.client-secret |
null |
Client secret to use when authenticating against the identity provider. Required in 'OPAQUE_TOKEN' mode. |
sechub.security.oauth2.opaque-token.introspection-uri |
null |
Opaque token introspection endpoint of the identity provider. Required in 'OPAQUE_TOKEN' mode. |
Key or variable name | Default | Description |
---|---|---|
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 |
Key or variable name | 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.resilience.encryption-out-of-sync.retry.max |
3 |
Amount of retries done when a PDS encryption out of sync problem happens |
sechub.adapter.pds.resilience.encryption-out-of-sync.retry.wait |
2000 |
Time to wait until retry is done when a PDS encryption out of sync problem happens |
Key or variable name | Default | Description |
---|---|---|
sechub.config.check.canceljob.delay |
60000 |
Define delay in milliseconds, for before next job cancellation check will be executed. |
sechub.config.scan.scanconfig.refresh.delay |
5000 |
Define delay (in milliseconds) for next job execution trigger after last executed. |
sechub.config.scan.scanconfig.refresh.initialdelay |
0 |
Define initial delay (in milliseconds) for scan config refresh check operation. |
sechub.report.sensitivedata.max.nonobfuscated.characters |
0 |
Define the amount of visible characters which are NOT obfuscated. |
Key or variable name | Default | Description |
---|---|---|
sechub.schedule.nextjob.suspend.miniumum-duration.milliseconds |
60000 |
The scheduler automatically restarts the next suspended jobs, regardless of the defined schedule strategy. This is done to get suspended jobs of another shut down instance back up and running as quickly as possible. To avoid suspended jobs being restarted too quickly, you can use this value to set the minimum time that must pass before the next suspended job can be restarted. The value is defined in milliseconds. The (previous) end date of the suspended job is used. For example, this value is important for K8s redeployment, because the servers that have not yet been updated should not immediately continue with the suspended jobs - they will also be shut down soon and would suspend the restarted jobs again… |
Key or variable name | Default | Description |
---|---|---|
sechub.config.trigger.healthcheck.enabled |
true |
When enabled each trigger will do an health check 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 |
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 |
sechub.server.upload.validate.zip |
true |
With |
sechub.upload.binaries.maximum.bytes |
52428800 |
Define the maximum amount of bytes accepted for uploading |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.checkmarx.resilience.badrequest.retry.max |
3 |
Maximum amount of possible retries for situations when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.badrequest.retry.wait |
2000 |
Time to wait until retry is done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.networkerror.retry.max |
100 |
Maximum amount of possible retries for situations when a network error happened on communication to Checkmarx server |
sechub.adapter.checkmarx.resilience.networkerror.retry.wait |
5000 |
Time to wait until retry is done when a network server happened on communication to Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.max |
1 |
Maximum amount of possible retries for situations when a 500 server internal error happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.wait |
5000 |
Time to wait until retry is done when a 500 server internal error happened on Checkmarx server |
sechub.project.joblist.page.max |
100 |
|
sechub.project.joblist.size.max |
100 |
Maximum limit for job information list entries per page |
sechub.schedule.encryption.refresh.accept-outdated.milliseconds |
1800000 |
The maximum amount of milliseconds an outdated encryption pool is still accepted in refresh phase |
sechub.server.baseurl |
Base url of SecHub server - e.g. https://sechub.example.org |
Key or variable name | Default | Description |
---|---|---|
sechub.security.diffiehellman.length |
Define diffie hellman key length, see https://github.com/mercedes-benz/sechub/issues/689 for details |
Key or variable name | Default | Description |
---|---|---|
sechub.server.debug |
false |
When debug flag is set, rest call reponse error messages do also contain stacktraces. |
Key or variable name | 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: |
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 |
Key or variable name | 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). |
Key or variable name | 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 |
Key or variable name | Default | Description |
---|---|---|
sechub.target.resolve.strategy.ip |
Strategy to decide target types by given IP. |
|
sechub.target.resolve.strategy.uri |
One ore more strategies to decide target types by given URI. |
8.2.4. Scheduling definitions
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. |
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. |
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. |
Fixed |
initial delay:${sechub.schedule.encryption.refresh.initialdelay:5000} fixed delay:${sechub.schedule.encryption.refresh.delay:300000} |
Defines the initial and also the fixed delay for the refresh interval. These values are also used for calculation of remaining run time of outdated encrytion pools (when refresh fails) |
8.2.5. Configuration properties for mocked adapters
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.mock.sanitycheck.enabled |
false |
See AbstractMockedAdapter.java |
Key or variable name | 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.
|
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
|
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
|
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 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 An example for production: |
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. Prepare (Remote Data Preparation)
Prepare
is not a scan product, but a developed wrapper application to prepare remote sources for scans.
It is used to download remote sources and upload them to the shared storage make them available to the scan products.
This allows the user to scan remote data without having to store it locally on a computer and upload it with the client.
The remote
section can be defined in the sechub configuration instead of the filesystem
.
Please note the PDS prepare can only be executed with a shared storage setup. These limitations are due to the fact, that the sechub server can not download sources from a PDS and copy them to another.
8.4.4. 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.5. 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.6. 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
|
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:
-
Domains do only communicate between each other via EventBus with explicit Domain Messages. (see also domain communication constraints )
-
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…) -
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:
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. Job restarts
The next diagram shows the involved classes and the program flow when PDS is used for communication - but if no PDS adapter is used for the product execution the behavior is similar: Each adapter is able to store meta data for the current job via callback but is also responsible to handle existing meta data on restarts.
The event REQUEST_RESTART_JOB
is also triggered when the batch trigger services
resumes suspended jobs.
It is always a good idea to use PDS instead of direct product handling (via dedicated adapters) because PDS (via the PDS adapter) provides relaunch /restart meta data handling out of the box! |
9.5. Deployment without scheduler stop
Before this concept, for new deployments of SecHub server instances, administrators had to stop the scheduler and wait for running jobs to finish. After no jobs were running any longer, the deployment was triggered and after this the scheduler was enabled again and job processing started again.
This works always, but has a catch: If there are many running jobs it can take a while until all of those running jobs are done. And also in the mean time no new jobs are started. This means that, if we have a great count of running jobs, the time gap between deployment and start of new jobs increases.
CI/CD builds or any other use of SecHub takes longer in the meantime, which can be unpleasant / a bad user experience.
9.5.1. Stop job processing when SIGTERM received
K8s and other systems will send a SIGTERM
signal to give application the possibility to shutdown
gracefully.
On a SIGTERM
signal a SecHub server instance temporarily suspends a job, allowing its PDS
instances to continue processing it in the background.
All running SecHub jobs on terminating instance will be interrupted, marked with execution state
SUSPENDED
and set ENDED
time stamp as shown in next figure:
See also UC-079
The next new SecHub server will resume the suspended job and proceeds with the results from the PDS instances (or wait for them if still not already available). |
9.5.2. Resume suspended jobs
The batch trigger service does trigger the resume operation which leads to REQUEST_RESTART_JOB
event
which restarts the job.
To prevent too fast restarts, the ENDED
timestamp of SecHub job will be inspected on suspended jobs
and only fetched as next job when the time gap is greater than a defined (configurable) time period.
See also UC-080
9.6. 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.6.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.6.2. Domain handling
9.6.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.6.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.7. PDS with SecHub
With the Product Delegation Server (PDS) the SecHub server can simply integrate different products in a very convenient, scalable and resilient way.
This documentation only gives an overview how and why SecHub uses PDS. Please look into the dedicated PDS documentation for architecture and also technical details! |
9.7.1. General
9.7.1.1. PDS In an nutshell
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 viaTLS
, 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.7.1.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.7.1.3. Communication between SecHub and PDS
The communication between SecHub server and PDS is very similar to the communication between SecHub client and SecHub server.
The PDS adapter
will do following steps from SecHub side - as a client of PDS:
-
creates a PDS job
-
(Optional: Only necessary when PDS does not resuse SecHub storage) uploads sources and/or binaries to PDS
-
approves PDS job
-
waits until PDS job has finished
-
downloads PDS report data
As shown in next figure:
9.7.2. Details about PDS
For more details please refer to the <<https://mercedes-benz.github.io/sechub/latest/sechub-product-delegation-server.html,PDS documentation>> available at
9.8. 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:
9.9. False-positive handling
SecHub must be able to handle false positives of used products.
9.9.1. General
9.9.1.1. How can false positives be handled across multiple security products?
9.9.1.1.1. Problem
-
Missing API
Most commercial security products are able to mark false positives, but maybe not every tool has a dedicated API for this feature. In addition, many FOSS security tools do not support false positive handling.
9.9.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.9.1.2. Different kinds of false-positive filtering
Some people prefer code/API-centric way to define false positives, some prefer a WebUI.
9.9.1.2.1. API centric
Defining false positives is done by declaring false positive information in a JSON
file
-
by referencing job results from former SecHub job UUID and the corresponding finding entry (by id) and/or
-
by specifying a project data section where specific patterns that match false positive findings are declared
and post it to the SecHub server REST API.
The |
The Each entry can be updated or removed by the given |
Example JSON using job results
{
"apiVersion": "1.0", (1)
"type": "falsePositiveDataList", (2)
"jobData": [ (3)
{
"jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd", (4)
"findingId": 1, (5)
"comment": "Can be ignored because not in deployment" (6)
},
{
"jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd",
"findingId": 15
}
]
}
1 | apiVersion (mandatory) - API version |
2 | type (mandatory) - must be falsePositiveDataList |
3 | jobData - List of job data that is used to mark a single finding as a false positive |
4 | jobData.jobUUID (mandatory) SecHub Job-UUID of the report where the finding was |
5 | jobData.findingId (mandatory) Finding ID which shall be marked as false positive |
6 | jobData.comment (optional) A comment describing the reason why this is a false positive |
Example JSON using project data
{
"apiVersion": "1.0", (1)
"type": "falsePositiveDataList", (2)
"projectData": [ (3)
{
"id": "unique-id", (4)
"comment": "It was verified that there is no SQL-injection",
"webScan": { (5)
"cweId": 89, (6)
"urlPattern": "https://*.example.com/rest/products/search?*", (7)
"methods": [ "GET", "DELETE" ] (8)
}
}
]
}
1 | apiVersion (mandatory) - API version |
2 | type (mandatory) - must be falsePositiveDataList |
3 | projectData - List that can be used to mark more than a single finding as a false positive. Currently only available for web scans. |
4 | projectData.id that identifies this entry. If the same id is used again,
the existing false positive entry will be overwritten. The id is also mandatory to unmark this entry. |
5 | projectData.webScan (optional) section can be used to define false positive patterns for web scans (DAST). It provides more possibilities to the user than above jobData. |
6 | projectData.webScan.cweId is used to mark a certain type of finding as false positive.When handling web scan project data this will be treated as a mandatory field. Please insert here the cweId from the original report. If there was no cweId in the original report, then it must be omitted or set to zero "cweId": 0 . |
7 | projectData.webScan.urlPattern (mandatory) specifies an URL pattern to identify a false positive.
Asterisks can be used as wildcards e.g. if you have different environments like DEV, INT, PROD or you have variable parts like in API calls or query paramaters https://.example.com/rest//search?* . |
8 | projectData.webScan.methods (optional) Can be used to further restrict the false positive matching, to specific request methods protocols, like GET, POST, etc. |
Important information on the wildcard approach in projectData
, regarding web scans:
- To be marked as a false positive a finding must match the given cweId
and the urlPattern
- Wildcards (*
) can be used inside urlPattern
.
- Wildcards match anything until the next NON-wildcard character.
- Multiple wildcards can be used in one urlPattern
.
- An optional list of (HTTP) methods can be specified to limit the false positive entry to certain methods
, e.g if you specify "methods": [ "GET", "DELETE" ]
like in the example above that means even if the cweId
and the urlPattern
are matching, if the finding was found with a POST
request it would not be a false positive. When leaving methods
out, this false positive entry apply to any method.
- An urlPattern
which contains only wildcards (*
) is not allowed.
9.9.1.2.2. Web UI
Just uses the API centric approach (by using given REST API,) over UI.
9.9.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 |
9.9.2. Code scan
9.9.2.1. API centric
see general concept
9.9.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 |
9.9.2.2. Web UI
see general concept
9.9.2.3. Code centric
This approach is currently not enabled/full supported! Details:
|
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 E.g. |
9.9.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.9.3. Web scan
9.9.3.1. Code centric
Not possible
9.9.3.2. API centric
see general concept
9.9.3.3. Web UI
see general concept
9.9.4. Infra scan
9.9.4.1. Code centric
Not possible
9.9.4.2. API centric
see general concept
The identification of similarity is done here by
For infrastructure scans a false positive detection is currently not implemented. |
9.9.4.3. Web UI
see general concept
9.10. 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.10.1. Overview
9.10.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.10.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.10.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.10.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.11. 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.11.1. Product messages inside product result
Every product can add custom messages which shall be available to user.
9.11.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.
9.11.1.2. Read and delivery of report data to end user
SerecoProductExecutor
collects all SecHub messages from other job results and combines them
inside its own data as SerecoAnnotation
. The annotations will be inspected on report creation
by SerecoResultTransformer
.
Further details for report creation can be found at report data flow.
9.11.2. Report data flow
9.11.2.1. Report model
Here a reduced class model of the report data model:
9.11.2.2. Creation of ScanReport entities
Here a graphical overview how the report data is created by the ScanService
and
finally written as ScanReport
entity into the database:
9.11.2.3. Read and delivery of report data to end user
When the user downloads the report, the result inside the persisted scan report entity will be used.
9.12. Job status
After a SecHub job has been created, it has a status which will change at the different process steps. Some of these steps are described here.
9.12.1. Job status fetching
9.12.2. Job status data flow
9.12.2.1. Job execution done, final Job status update
9.13. SecHub job cancellation
An administrator is able to cancel a running SecHub job. This is done across different domains and there are multiple events involved. The next diagram shall bring an overview.
9.14. Auto cleanup
To prevent full hard drives there is an option to automatically remove old data.
It also cleans up old encryption settings when it comes to encryption rotation.
See also |
9.14.1. Configuration
Administrators can configure the auto cleanup configuration by uploading a json configuration via REST (see REST API for UC_065-Admin updates auto cleanup configuration ).
{
"cleanupTime" : {
"unit" : "months", (1)
"amount" : 3 (2)
}
}
1 | The time unit to use. Can be
|
2 | Amount of time. When 0 is defined, the auto cleanup is deactivated, all other positive values are time
unit related. Negative values are not allowed. |
9.14.2. Execution
The execution is automatically done by SecHub.
9.14.3. Cleaned data
All data which is older than the defined time period is removed from:
-
Scan product results
-
Scan project log
-
Schedule job entries
-
Administration job information
Scan report data is currently NOT deleted. So it can be used for statistics. In a later feature there will be specialized statistic tables - when this has been implemented, the auto cleanup will be extended to drop old scan report data as well. |
9.15. PDS solutions
It is easy to integrate security products, even command line tools without a network API, into
SecHub
via PDS
(Product delegation server).
A PDS solution is a ready-made package for SecHub in which a PDS and the necessary security products are already pre-installed and can be used directly without additional adjustments.
The PDS solutions can be found at https://github.com/mercedes-benz/sechub/tree/develop/sechub-pds-solutions. |
9.15.1. Checkmarx PDS solution
The checkmarx PDS solution uses sechub-wrapper-checkmarx
which is a standalone Spring Boot application.
If started in non production mode, the data will be mocked when inside IDE.
9.15.2. PDS code scan executor Configuration
Job parameter | Type | Description |
---|---|---|
pds.checkmarx.user |
Mandatory |
The user name used to communicate with Checkmarx. You can use env:$YOUR_USER_VARIABLENAME to use environment variables instead of real credentials. |
pds.checkmarx.password |
Mandatory |
The password used to communicate with Checkmarx. You can use env:$YOUR_PWD_VARIABLENAME to use environment variables instead of real credentials. |
pds.checkmarx.baseurl |
Mandatory |
The base URL of the Checkmarx server. |
pds.checkmarx.engine.configuration.name |
Optional |
The engine to use - when empty, the default engine will be used. |
pds.checkmarx.always.fullscan.enabled |
Optional |
When 'true', Checkmarx will do a full scan and not a delta scan. |
pds.checkmarx.result.check.period.milliseconds |
Optional |
The time period in milliseconds when the next check for Checkmarx resuls will be done. An example: If you define |
pds.checkmarx.result.check.timeout.minutes |
Optional |
The maximum time in minutes when the checkmarx communication does time out and the connection will be terminated. |
pds.checkmarx.mocking.enabled |
Optional |
When 'true' than, instead of the real Checkmarx adapter, a mock adapter will be used. This is only necessary for tests. |
checkmarx.newproject.teamid.mapping |
Mandatory |
Can be either defined directly as job parameter (json mapping), or we can send it automatically by reusing an existing SecHub mapping. As an example: 'pds.config.use.sechub.mappings=checkmarx.newproject.teamid.mapping,checkmarx.newproject.presetid.mapping' |
checkmarx.newproject.presetid.mapping |
Optional |
If not the default preset Id shall be used, it can be either defined directly as job paramter (json mapping), or we can send it automatically by reusing an existing SecHub mapping. As an example: 'pds.config.use.sechub.mappings=checkmarx.newproject.teamid.mapping,checkmarx.newproject.presetid.mapping' |
pds.checkmarx.resilience.badrequest.max.retries |
Optional |
Maximum amounts of retries for bad request handling |
pds.checkmarx.resilience.badrequest.retry.wait.milliseconds |
Optional |
Time in milliseconds to wait before next retry when a bad request happend |
pds.checkmarx.resilience.servererror.max.retries |
Optional |
Maximum amounts of retries for internal server error handling |
pds.checkmarx.resilience.servererror.retry.wait.milliseconds |
Optional |
Time in milliseconds to wait before next retry when an internal server error happend |
pds.checkmarx.resilience.networkerror.max.retries |
Optional |
Maximum amounts of retries for network error handling |
pds.checkmarx.resilience.networkerror.retry.wait.milliseconds |
Optional |
Time in milliseconds to wait before next retry when a network error happend |
9.16. Analytics
SecHub can be configured to analyze a scan situation at the beginning to improve runtime behavior or to create statistic data. This is done before all other scans.
As usual, different products can be used to provide the analytic data. The analytic scan products can be configured as any other product by defining a executor configuration and add it to a execution profile which can be assigned to SecHub projects. |
9.17. Statistics
For statistic data handling exists an own domain statistic
. The data is collected in
dedicated statistic SQL tables.
Statistic data is NOT auto cleaned. |
9.18. Data encryption
9.18.1. General
We want
-
Data consistency
-
It shall not be possible that we loose data by encryption in any way.
It must be ensured that the servers are always able to read and write data.
-
-
Full automated cipher rotation
There is no need for manual interaction - means it is not necessary to create any cron jobs or something else to convert non encrypted data to encrypted data or to rotate a password or to use a new encryption method. -
Data protection /Privacy policy
-
Even for administrators it shall not be possible to fetch the information directly
(of course a person who knows the encryption password and has access to the database will always be able to calculate values - but we separate here between administration and operation inside this concept, so protection is fully possible) -
The data must not be accidentally made available in decrypted form - for example through a REST call in which the data object is passed along unencrypted.
-
-
Easy encryption administration
-
It shall be possible for an administrator to configure a new cipher entry via REST
-
-
Secure storage of encryption passwords
-
Encryption passwords are always provided via environment entries, we store always the environment variable name to use inside the database but never plain values!
-
9.18.2. Server startup
A SecHub server will stop on startup phase when one of the entries inside the cipher pool cannot be handled by this server.
This ensures that every new started server is able to handle all of them / is always readable.
9.18.3. Administration
9.18.3.1. Encryption rotation
An administrator is able to start encryption rotation via REST. This will
-
use new encryption setup for all new data
-
automatically convert existing encrypted data with new encryption setup in background
9.18.3.2. Encryption status
An administrator is able to fetch encryption status from SecHub server. All domains which are doing data encryption add their current status information into result.
9.18.3.3. Cleanup old encryption setup
Auto Cleanup automatically removes old information. This means that old encrypted information that cannot be updated for some reason may eventually disappear and old encryption configurations are then no longer needed and can be removed.
To fully automate this, after the respective Auto Cleanup, the domains are always checked for encryption configurations that are no longer used and these are then automatically removed (except for the most recent encryption configuration).
If you have setup auto cleanup to 0 days, the auto cleanup is disabled completely and unused encryption setup will also not be removed. |
9.18.4. Scheduler
Inside the schedule domain, the sensitive information is the sechub job configuration.
9.18.4.1. Database
9.18.4.1.1. Table
We store the cipher information inside table: SCHEDULE_CIPHER_POOL_DATA
.
Why in schedule domain and only there? Because it is the responsible domain for the storage. All other
domains may NEVER persist this information (for |
Here an an overview of the table (names can be different in database):
id | algorithm | password_source_type | password_source_data | encoding | test_text | test_initial_vector | test_encrypted | creation_timestamp | created_from |
---|---|---|---|---|---|---|---|---|---|
0 |
NO_ENCRYPTION |
PLAIN_TEXT |
PLAIN |
no-encryption |
no-encryption |
2024-06-24_10:00:01 |
null |
||
1 |
AES_GCM_SIV_128 |
ENVIRONMENT_VARIABLE |
SECHUB_CRYPTO_P0 |
PLAIN |
SecHub |
easdfa313334 |
53d$125666eeffeded |
2024-06-24_10:05:34 |
Admin1 |
2 |
AES_GCM_SIV_256 |
ENVIRONMENT_VARIABLE |
SECHUB_CRYPTO_P1 |
PLAIN |
Apfel |
fxadsfeec33s |
13x313412124$rfewd |
2024-06-24_11:02:14 |
Admin2 |
algorithm
Algorithm to use in encryption - currently we provide:
-
NONE (means not encrypted!)
-
AES_GCM_SIV_128
-
AES_GCM_SIV_256
password_source_type
Currently supported password source types are
-
ENVIRONMENT_VARIABLE
Here we provide environment variables, the password source data is the name of the environment variable -
NONE
No password - only allowed forNONE
algorithm
We separated source type and source data to be able to provide additional source - e.g. a password fault for the future.
password_source_data
Depends on the source
-
If source is
env
than this is the name of the environment variable which holds the secret
9.18.4.1.2. Usage inside rows
Inside the encrypted rows we will persist the pool id together with an initial vector
initial vector
Some algorithm like AES_GCM_SIV
do need an initial vector to encrypt secure. The value here is
auto generated by SecHub and is dependent on the algorithm.
SecHub will always auto generate a dedicate value when it comes to encryption and the vector will be stored together with the encrypted data. If the initial vector is changed, the row cannot be decrypted, even when the secret key is known!
9.18.4.2. Constraints on scheduling
The only situation we need to access the encrypted job configuration is the point, when it comes to job execution. At all other situations it does not matter if the configuration can be decrypted or not.
This means that it may not be possible that an scheduler instance executes a job which is not supported by the current encryption pool!
9.18.5. Handling server updates
9.18.5.1. SecHub server 1.x to 2.x
Old server versions do not have the encryption field inside the scheduler job table or the cipher pool table.
Our SQL migration scripts will initialize scheduler cipher pool table on creation time with a
NONE
entry (pool id = 0). This is encryption setup (meaning no encryption) will be added
to all existing jobs.
We want to have zero downtime and rolling updates with k8s and SecHub. To provide this,
it must be ensured, that there is no old server running which creates new jobs with
plain text configurations while update is running. To prevent such a situation
the column name inside schedule_sechub_job
have been renamed from configuration
to unencrypted_configuration
.
If there appears any race conditions, old servers would no longer be able to write data and a
SQL error would happen.
9.18.6. Handling server downgrade
9.18.6.1. SecHub server 2.x to 1.x
For a downgrade from SecHub server V2.x to V1.x it is necessary to ensure, that all data is
encrypted with NONE
cipher type (can be done by encryption rotation). When ensured that everything
is "encrypted" with this cipher type, the old server version can be deployed/used and migration
is automatically done as usual.
9.18.7. Handling sensitive data at runtime
JVM crash dumps contain string information. Classes containing sensitive information shall store such information inside sealed objects.
9.18.8. Handling metadata from job configuration
The SecHub configuration is encrypted, because it can contain sensitive data. E.g. when defining a remote data section.
There exists a REST endpoint which gives users the possiblity to fetch job information, together with the meta data defined inside the SecHub configuration.
To obtain this information, the configuration will be decrypted temporary at runtime and the meta data are resolved and returned.
Because meta data shall not contain any sensitive information, this will not be audit logged.
9.18.9. Diagrams
9.18.9.1. Usage of encryption commons
9.18.9.2. Encryption rotation overview
10. Design Decisions
11. Quality Requirements
11.1. Quality Tree
11.2. Quality Scenarios
12. Risks and Technical Debts
12.1. Domain message system
In domain communication constraints is described that we use a very simple DDD approach by using a simple observer pattern inside JVMs.
12.1.1. Handling of lost messages on a JVM crash /pod crash
This currently not solved. When JVM/Pod crushes, the job is in state running and will not resurrect.
12.1.2. Clustering
12.1.2.1. Handling of domain requests for one member only
At current situation there is no double processing of domain messages inside
sechub
server clusters because every instance of an sechub
server sends its
domain requests only inside its JVM.
So we must not care about situations where multiple cluster members would handle domain requests in a multiple way…
If we would switch to a solution like
KAFKA this must be considered: Events may (normally) only processed at one
cluster member! This could be a critical task if we change domain messaging.
Normally most of the events shall be processed only at one cluster member.
|
12.1.2.2. Handling of domain requests for complete cluster
Currently this cannot be done by a domain message. We must provide those central information inside database. An example: When we got 3 running instances of SecHub and we want to inform that scheduling shall no longer processed, we have to inform every instance. But the reduced domain message system works only inside one JVM. So we must provide this by our cluster wide shared DB.
12.2. Prevent lost SecHub jobs on updates
Jobs are running inside a dedicated JVM. When JVM crashes, the job will not resurrect and become a "zombie".
To prevent such a situation on a rolling update of SecHub administrators must disable scheduler job processing before doing the update. See https://github.com/mercedes-benz/sechub/issues/12
13. Glossary
Term | Definition |
---|---|
Adapter |
In scope of SecHub the term "adapter" is used for product adapters. They represent |
Executor |
An executor (or product executor) handles the complete communication with a product via an adapter. The executor is repsonsible for resilience and writes the results from adapter into SecHub database. |
K8s |
Kubernetes, also known as K8s, is an open-source system for automating deployment, scaling, and management of containerized applications. |
Helm |
"…Helm is the best way to find, share, and use software built for Kubernetes. …" |
Mapping |
The mapping feature inside SecHub is a generic pattern replacement approach. Via a REST API
administrators can define the mappings with regular expression patterns and dedicate values/
replacements. |
PDS |
Is an acronym for "Product delegation server". This kind of server represents a
very easy way to integrate any security product into SecHub - no matter if it is
a command line tool or has REST API or anything else. |
PDS-Solution |
PDS is a very generic server which can execute anything. The |
SecHub |
SecHub itself - it is an acronym for "Security Hub" and represents a security
orchestration tool. |
SecHub configuration file |
Is the JSON configuration file used by a user to start a new SecHub job. |
Wrapper |
A wrapper or "wrapper application" is a standalone application used inside a PDS-solution when it comes to a more sophisticated way of product communication. Normally such an application is written in Java and uses some common SecHub libraries and has more logic inside. Example are the Checkmarx wrapper and the OWASP Zap wrapper. |