About SecHub
SecHub is an acronym for Security Hub
and is first of
all one API to scan for different security problems. Users of SecHub do not
care about which exact product is doing the real scan on server side, but only
configure their wanted aim.
SecHub does NOT provide a security infrastructure but does orchestrate different security products/tools. So you still need an existing security infrastructure behind SecHub ! |
It was designed to be very easy to integrate into any existing build pipeline / contionus integration (CI) and helps to provide SecDevOps.
You can get more information about from SecHub web page . The project is hosted at https://github.com/mercedes-benz/sechub |
About documentation
This documentation is part of SecHub
.
Key | Value | Information |
---|---|---|
LICENSE |
MIT License |
Please look at https://github.com/mercedes-benz/sechub/blob/master/LICENSE |
Documentation version: Server 1.8.0 - Build date: 20240315161105
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.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 |
ROLE_SUPERADMIN |
All self registrations are returned as json |
7.5.4. UC_003-Admin applies self registration
In this usecase the administrator will accept the self registration done by an user.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator accepts a persisted self registration entry by calling rest api |
2 |
Create user and send events |
ROLE_SUPERADMIN |
3, 4 |
The service will create the user a one time token for api token generation and triggers asynchronous events. It will also remove the existing user signup because no longer necessary. |
3 |
Email to user |
A notification is send per email to user that a new api token was requested. The mail contains a link for getting the secure API token |
||
4 |
Give user access |
Authorization layer is informed about new user and gives access to sechub. But without any project information |
7.5.5. UC_004-Admin lists all users
An administrator downloads a json file containing all user ids
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
All userids of sechub users are returned as json |
2 |
Service call |
ROLE_SUPERADMIN |
All userids of sechub users are returned as json |
7.5.6. UC_005-User creates a new sechub job
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 |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Persistence and result |
Persist a new job entry and return Job UUID |
7.5.7. UC_006-User uploads source code
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 |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Try to find project and upload sourcecode as zipfile |
ROLE_USER |
When project is found and user has access and job is initializing the sourcecode file will be uploaded |
7.5.8. UC_007-User approves sechub job
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 |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Try to find job annd update execution state |
When job is found and user has access job will be marked as ready for execution |
7.5.9. UC_008-Sechub scheduler starts job
Scheduler service starts next SchedulerJob
. Before a user has only created and approved a job which was lead only to database persistence of JobData.
The work itself is triggered/executed here by asynchronous batch operation.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Fetches next schedule job from queue and trigger execution. |
|
2 |
Execution |
3, 4 |
Triggers job execution - done parallel, but with synchronous domain communication (to wait for result). |
|
4 |
Store admin job info |
5 |
Fetches event about started job and store info in admin domain. |
|
5 |
Update admin job info |
Deletes store info in admin domain when job is done. |
7.5.10. UC_009-User checks sechub job state
User wants to get the state of the current running job.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Try to find project and fail or return job status |
7.5.11. UC_010-User downloads sechub job report
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 |
ROLE_SUPERADMIN, ROLE_USER |
3 |
|
2 |
REST API call to get HTML report |
ROLE_SUPERADMIN, ROLE_USER |
3 |
|
3 |
Resolve scan report result |
7.5.12. UC_011-User starts scan by client
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 |
ROLE_SUPERADMIN, ROLE_USER |
2, 3 |
|
2 |
upload sourcecode |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
upload binaries |
ROLE_SUPERADMIN, ROLE_USER |
3 |
|
3 |
approve job |
ROLE_SUPERADMIN, ROLE_USER |
4 |
|
4 |
get job status |
ROLE_SUPERADMIN, ROLE_USER |
4 |
|
4 |
download job report and traffic light |
ROLE_SUPERADMIN, ROLE_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 |
ROLE_SUPERADMIN |
2 |
Administrator creates a new project by calling rest api |
2 |
Create project |
ROLE_SUPERADMIN |
The service will create the project when not already existing with such name. |
7.5.15. UC_014-Admin lists all projects
An administrator downloads a json file containing all project ids
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
All project ids of sechub are returned as json |
7.5.16. UC_015-Admin assigns user to project
An administrator assigns an user to an existing sechub project.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator does call rest API to assign user |
2 |
Update schedule authorization parts |
2 |
||
2 |
Assign user |
ROLE_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 |
ROLE_SUPERADMIN |
2 |
Administrator does call rest API to unassign user |
2 |
Update authorization parts |
2 |
||
2 |
Update authorization parts |
2 |
||
2 |
Unassign user |
ROLE_SUPERADMIN |
4 |
The service will remove the user to the project. If users has no longer access to projects ROLE_USER will be removed |
4 |
Roles changed in auth |
Authorization layer removes ROLE_USER |
7.5.18. UC_017-Admin shows user details
An administrator downloads a json file containing json containing user details
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Json returned containing details about user and her/his projects |
2 |
Service fetches user details. |
ROLE_SUPERADMIN |
The service will fetch user details for given user id |
7.5.19. UC_018-Admin deletes a user
An administrator deletes an user. All associations etc. are removed as well.
If the user is still a project owner the delete will not work and an error message will appear that this is not acceptable and that the ownership must be moved before User delete is possible. |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
User will be deleted |
2 |
Service deletes user. |
ROLE_SUPERADMIN |
3, 4 |
The service will delete the user with dependencies and triggers asynchronous events |
3 |
revoke user from schedule access |
3 |
||
3 |
revoke user from schedule access |
4 |
||
4 |
Delete user access |
Authorization layer is informed about user deltete and removes access to sechub. But without any project information |
||
5 |
Inform user that the account has been deleted by administrator |
7.5.20. UC_019-Admin deletes user signup
In this usecase the administrator will not accept the self registration done by an user but delete the entry.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest API call |
ROLE_SUPERADMIN |
2 |
Rest api called to remove user signup |
2 |
Persistence |
ROLE_SUPERADMIN |
Existing signup will be deleted |
7.5.21. UC_020-Admin deletes a project
Administrator deletes a project from SecHub
.
A Project is the main entry point for every SecHub
operation and deleting this will result in:
-
Terminate all running jobs for this project
-
Remove project administration setup
-
User to project association
-
All existing project report results
Albert Tregnaghi, 2018-08-03: This is currently not full implemented! |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Project will be deleted |
2 |
Service deletes projects. |
ROLE_SUPERADMIN |
3, 4, 5, 6, 7 |
The service will delete the project with dependencies and triggers asynchronous events |
3 |
Inform sechub admins that project has been deleted |
4 |
||
4 |
Inform project owner that the project has been deleted |
5 |
||
5 |
Inform users that the project has been deleted |
6 |
||
6 |
Update authorization parts - remove entries for deleted project |
7 |
||
7 |
revoke any scan access from project |
8 |
||
8 |
delete all project scan data |
7.5.22. UC_021-Admin shows project details
An administrator downloads a json file containing json with project details
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Json returned containing details about project |
2 |
Service fetches project details. |
ROLE_SUPERADMIN |
The service will fetch project details |
7.5.23. UC_022-Update project whitelist
Administrator creates a project inside SecHub
.
A Project is the main entry point for every SecHub
operation!
For example a user must have a project assigned to be able to scan on it!
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
White list will be updated |
2 |
Update project |
ROLE_SUPERADMIN |
The service will update the Project whitelist. |
7.5.24. UC_023-Admin lists all running jobs
Administrator lists all running jobs inside SecHub
.
The list entries do contain
-
jobUUID
-
project id
-
owner of job (id of user who executed job)
-
status
-
since time stamp
-
configuration
These entries are only available at running jobs
This is an important action to get info about current treshold in sechub.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator lists all running jobs by calling rest api |
2 |
Fetchjob information from database |
Fetches stored job information from administration database. |
7.5.25. UC_024-User requests new API token
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 |
ROLE_SUPERADMIN |
2 |
7.5.27. UC_026-Admin downloads all details about a scan job
An administrator downloads a ZIP file containing full details of a scan. Main reason for this use case is for debugging when there are problems with security products. Another reason is for developers to adopt new security products easier.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to zip file containing full scan data |
ROLE_SUPERADMIN |
2 |
|
2 |
Collect all scan data |
ROLE_SUPERADMIN |
7.5.28. UC_027-Admin grants admin rights to user
An administrator grants admin rights to another user. So this user will become also an administrator.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
User will be granted admin rights |
2 |
Service grants user admin rights. |
ROLE_SUPERADMIN |
3, 4 |
The service will grant user admin righs and triggers asynchronous events |
3 |
Inform user that he/she became administrator |
4 |
||
4 |
Inform SecHub admins that another user became administrator |
7.5.29. UC_028-Admin revokes admin rights from an admin
An administrator revokes existing admin rights from another administrator.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Admin rights will be revoked from admin |
2 |
Service revokes user admin rights. |
ROLE_SUPERADMIN |
3, 4 |
The service will revoke user admin righs and triggers asynchronous events |
3 |
Inform user about loosing administrator rights |
4 |
||
4 |
Inform SecHub admins that another admin is no longer admin |
7.5.30. UC_029-Admin lists all admins
An administrator downloads a json file containing all names of SecHub admins
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
All userids of sechub administrators are returned as json |
2 |
Service call |
ROLE_SUPERADMIN |
All userids of sechub administrators are returned as json |
7.5.31. UC_030-Admin disables job processing in scheduler
An administrator disables scheduler job processing. This can be a preparation for system wide update - when scheduling is stoped, user can ask for new SecHub Jobs etc. But as long as scheduler is stopped nothing is executed - so JVMs/PODs can be updated in cluster
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator wants to stop (pause) scheduler job processing |
2 |
Service call |
ROLE_SUPERADMIN |
2 |
Sends request to scheduler to send updates about current status. |
2 |
Service call |
ROLE_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 |
ROLE_SUPERADMIN |
2 |
Administrator wants to start (unpause) scheduler job processing |
2 |
Service call |
ROLE_SUPERADMIN |
3 |
Sends request to scheduler domain to enable scheduler job processing |
3 |
Enable processing |
4 |
Enables job processing inside scheduler database |
|
4 |
Inform SecHub admins that scheduler job processing has been enabled |
7.5.33. UC_032-Admin get scheduler status
An administrator wants to update information about scheduler status
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
Administrator wants to trigger a refresh of scheduler status. Will update information about running, waiting and all jobs in scheduler etc. etc. |
7.5.34. UC_033-Admin lists status information
An administrator fetches current known status information about sechub
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
Administrator wants to list status information about sechub |
7.5.35. UC_034-Admin cancels a job
Administrator does cancel a job by its Job UUID
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Triggers job cancellation request, owners of project will be informed |
2 |
Cancel job |
3 |
Will trigger event that job cancel requested |
|
3 |
Try to find job and mark as being canceled |
4 |
When job is found and user has access the state will be updated and marked as canceled |
|
4 |
Inform user that her/his job has been canceled |
7.5.36. UC_035-User defines mock data configuration for project
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 |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Service call to store mock configuration |
7.5.37. UC_036-User retrieves mock data configuration for project
When 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 |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Service call to get JSON data |
7.5.38. UC_037-Admin updates mapping configuration
An administrator changes mapping configuration. Mappings represents a generic mechanism to replace a given string, matched by configured regular expression pattern with a replacement string. Some of the mappings are used for adapter behaviour.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator wants to update a mapping configuration |
2 |
Service call |
3 |
Services updates data in database and sends event |
|
3 |
Event handler |
4 |
Receives mapping configuration change event |
|
4 |
Service call |
5 |
Updates scan mapping in DB |
|
5 |
Trigger service |
6 |
Checks periodically for updates in scan configuration |
|
6 |
Service call |
Checks if current mappings in DB lead to a new scan configuration. |
7.5.39. UC_038-Admin fetches mapping configuration
An administrator fetches mapping configuration by its ID.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator wants to fetch a mapping configuration |
2 |
Service call |
Services fetches data from database, if not set an empty mapping data result will be returned |
7.5.40. UC_039-Check if the server is alive and running.
An anonymous user or system wants to know if the server is alive and running.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call |
An anonymous user checks if the server is alive and running using the REST API |
7.5.41. UC_040-Admin 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 |
ROLE_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 |
ROLE_SUPERADMIN |
2 |
Triggeres job restart (soft) |
2 |
Restart job |
3 |
Will trigger event that job restart (soft) requested |
|
3 |
Inform sechub admins when job restart was canceled |
4 |
||
4 |
Inform sechub admins when job has been restarted |
5 |
||
5 |
Inform sechub admins when job results have been purged |
7.5.43. UC_042-Admin restarts a job (hard)
Administrator restarts job the hard way , means it is possible to restart a running (not finished) job and destroy all former results.
It is very similar to related use case admin restarts job, but with difference that all former product results and also adapter meta data is removed. |
We do NOT allow restarts of former finished jobs because finalization does destroy interim data - e.g. uploaded source code etc. - and is no longer restartable. Also we cannot ensure that a client has not already downloaded the existing results, so we we keep them as is! The term "hard" is only because we destroy former meta data and product results! So the restart is like from "scratch". |
The restart will
-
first of all write an audit log enry
-
be canceled, when job does not exist in scheduler
-
be canceled, when execution already finished
-
delete all former product results and also adapter meta data
-
check for running batch jobs with SecHub job UUID.
If there are existing batch operations, those will be stopped -
new scan will be restarted immediately without scheduling, will not try to reuse existing results because such information was formerly deleted
Event overview - variant: accidently restart because job has already finished
Event overview - variant: crashed jvm with product result
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Triggeres job restart (hard) |
2 |
Restart job |
3 |
Will trigger event that job restart (hard) requested |
|
3 |
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 for finished sechub job
A user wants to mark false positives for a finished job. This means the job has been executed, has finished without failure and job is NOT deleted.
The user will be able to mark former job results by their given id as false positives.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to define false positives by JSON data containing identifiers for existing job |
ROLE_SUPERADMIN, ROLE_USER |
7.5.46. UC_045-User unmarks existing false positive definitons
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 |
ROLE_SUPERADMIN, ROLE_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 |
ROLE_SUPERADMIN, ROLE_USER |
7.5.48. UC_047-Admin creates an executor configuration
An administrator creates an executor a new configuration entry.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator adds a new product executor configuration by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service creates a new product executor configuration |
7.5.49. UC_048-Admin deletes executor configuration
An administrator deletes an executor by removing the configuration entry identified by its uuid
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator deletes an existing product executor configuration by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service deletes an existing product executor configuration by its UUID |
7.5.50. UC_049-Admin fetches executor configuration list
An administrator fetches executor configuration list which contains all executor configurations
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator fetches lsit of existing product executor configurations by calling REST API, will not contain setup information |
2 |
Service call |
ROLE_SUPERADMIN |
Service fetches data and creates a list containing all executor configurations |
7.5.51. UC_050-Admin fetches executor configuration
An administrator fetches one explicit executor configuration by its uuid.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator fetches setup of an existing product executor configuration by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service reads setup information for an existing product executor configuration |
7.5.52. UC_051-Admin updates executor configuration setup
An administrator updateds dedicated executor configuration. The update does change description, enabled state and also used executors, but Will NOT change any associations between profile and projects.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator updates setup for an existing product executor configuration by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
2 |
Service updates existing executor configuration |
2 |
Service call |
ROLE_SUPERADMIN |
Service updates existing executor configuration |
7.5.53. UC_052-Admin creates an execution profile
An administrator creates an execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator adds a new product execution profile by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service creates a new product executor configuration |
7.5.54. UC_053-Admin deletes execution profile
An administrator deletes execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator deletes an existing product execution profile by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service deletes an existing product execution profile by its profile id |
7.5.55. UC_054-Admin updates execution profile
An administrator updateds dedicated execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
Administrator updates existing profile by calling REST API |
7.5.56. UC_055-Admin fetches execution profile
An administrator fetches details about an execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator fetches setup of an existing product executor configuration by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service reads setup information for an existing product executor configuration |
7.5.57. UC_056-Admin fetches execution profile list
An administrator fetches execution profile list
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator fetches lsit of all available execution profiles by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Service fetches data and creates a list containing all executor profiles |
7.5.58. UC_057-Admin assigns execution profile to project
An administrator assigns an execution profile to an existing project
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator adds profile relation to project by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Services creates a new association between project id and profile |
7.5.59. UC_058-Admin unassigns execution profile from project
An administrator unassigns an execution profile from a projects.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator removes profile relation to project by calling REST API |
2 |
Service call |
ROLE_SUPERADMIN |
Services deletes an existing association between project id and profile |
7.5.60. UC_059-Update project metadata
Administrator updates project meta data inside SecHub
.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
MetaData will be updated |
2 |
Update project |
ROLE_SUPERADMIN |
The service will update the Project metadata. |
7.5.61. UC_060-Admin changes owner of a project
An administrator changes the owner of an existing sechub project.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator does call rest API to set new project owner |
2 |
Change project owner |
ROLE_SUPERADMIN |
4 |
The service will set the user as the owner of the project. If user does not have ROLE_OWNER it will obtain it. The old owner will loose project ownership. |
4 |
Inform new and previous project owners that the project owner ship has changed |
7.5.62. UC_061-Admin changes project description
An administrator changes the project description
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Changes project description. Json returned containing details about changed project |
2 |
Service changes project description. |
ROLE_SUPERADMIN |
The service will change project description. |
7.5.63. UC_062-Admin changes project access level
An administrator is able to change the access level of a project.
Project access levels do constraint possible user operations for a project - e.g. restrict to read only operations. The details of different restrictions are described below.
A project access level none will make it also for administrators
impossible to fetch reports from the project. Only
special administrator REST API calls are not restricted.
|
7.5.63.1. Levels
-
full
no restrictions -
read_only
users can download their reports, get job status, but cannot trigger any project jobs -
none
users have no access to reports, jobs and cannot trigger any jobs for the project
7.5.63.2. Conststraints
7.5.63.2.1. Full
When a project has access level full
any read or write user operation
is possible:
-
a new scan can be triggered, so user can
-
create job
-
approve job
-
upload job data
-
-
scheduling is active for the project new jobs are processed
-
user can check status for a job in their project
-
user can download their former reports
7.5.63.2.2. Read only
When a project has access level read_only
only read user operations
are possible:
-
a new scan is not possible, HTTP 403: Forbidden will be sent for
-
create job
-
approve job
-
upload job data
-
-
running jobs are still running
-
already scheduled jobs will be scheduled
-
user are still able to check status for a job in their project
-
user can still download their former reports
7.5.63.2.3. None
When a project has access level none
no user operation is possible:
-
a new scan is not possible, HTTP 403: Forbidden will be sent for
-
create job
-
approve job
-
upload job data
-
-
running jobs are still running
-
already scheduled jobs will be scheduled
-
user are NOT able to check status for a job in their project, HTTP 403: Forbidden will be sent
-
user can NOT download their former reports, HTTP 403: Forbidden will be sent
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Admin does call REST API to change project access level |
2 |
Change access level |
ROLE_SUPERADMIN |
3 |
The service will change the project access level inside administration domain and trigger a change event to inform recipients about the new situation. |
3 |
Event handler |
4 |
Receives change project access level event |
|
4 |
Event handler |
Receives change project access level event |
7.5.64. UC_063-Admin updates user email address
An administrator update the email address of an user. After the change an email will be sent to the old email-address to inform the user about the change. In addition, a new mail to the new email address will be sent as well.
When the new email address is the same as before, the action will be rejected. |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
User emaill address will be changed |
2 |
Service updates user email address. |
ROLE_SUPERADMIN |
3 |
The service will update the user email address and also trigger events. |
3 |
Inform user that the email address has been changed |
7.5.65. UC_064-Admin fetches auto cleanup configuration
An administrator feches current auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator fetches auto cleanup configuration |
2 |
Fetches auto cleanup config |
Fetches auto cleanup configuration from database |
7.5.66. UC_065-Admin updates auto cleanup configuration
An administrator changes auto cleanup configuration.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Administrator changes auto cleanup configuration |
2 |
Updates auto cleanup config |
3, 4, 5 |
Updates auto cleanup configuration as JSON in database and sends event |
|
3 |
Administration domain receives auto cleanup event |
4 |
Received event in administration domain about auto cleanup configuration change. Stores data, so available for next auto clean execution |
|
4 |
Schedule domain receives auto cleanup event |
5 |
Received event in schedule domain about auto cleanup configuration change. Stores data, so available for next auto clean execution |
|
5 |
Scan domain receives auto cleanup event |
Received event in scan domain about auto cleanup configuration change. Stores data, so available for next auto clean execution |
7.5.67. UC_066-Sechub administration domain auto cleanup
The administration domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Checks for parts to auto clean. |
|
2 |
Delete old data |
deletes old job information |
7.5.68. UC_067-Sechub scan domain auto cleanup
The scan domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Checks for parts to auto clean. |
|
2 |
Delete old data |
deletes old job information |
7.5.69. UC_068-Sechub schedule domain auto cleanup
The schedule domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Checks for parts to auto clean. |
|
2 |
Delete old data |
deletes old job information |
7.5.70. UC_069-User uploads binaries
A user wants to upload binearies 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 |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Try to find project and upload binaries as tar |
ROLE_USER |
When project is found and user has access and job is initializing the binaries file will be uploaded |
7.5.71. UC_070-User downloads job report in SPDX format
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 |
ROLE_SUPERADMIN, ROLE_USER |
7.5.72. UC_071-User lists jobs for project
User fetches a list containing information about jobs of a SecHub project. Per default only the last created job is returned, but it is possible to define a limit and fetch more than one. In this case the returned entries are ordered by creation date.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
get pageable list of jobs in project |
ROLE_SUPERADMIN, ROLE_USER |
2 |
|
2 |
Assert access by service and fetch job information for user |
7.5.73. UC_072-Admin shows user details for email address
An administrator fetches user details for an email address.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
ROLE_SUPERADMIN |
2 |
Json returned containing details about user and her/his projects |
2 |
Service fetches user details. |
ROLE_SUPERADMIN |
The service will fetch user details for given user email address |
7.6. Rest API documentation
7.6.1. Overview
7.6.1.1. Anonymous
All these usecases handling anonymous access.
7.6.1.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.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. 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.2.2. 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.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 id for project |
|
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 id for project |
|
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 id for project 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! |
|
|
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"],"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/eba45184-9eb9-4a3d-a606-a6470c745943' -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 id for project |
|
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 id for project to delete |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/project/projectId1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.19. Update project whitelist
REST API for usecase UC_022-Update project whitelist
Definition
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":"9694a037-d091-45ee-b8c7-dad84af653e3","executedBy":"spartakus","started":"2024-03-14T16:11:15.379967538","ended":"2024-03-15T16:11:15.380002534","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 id for project 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! |
|
|
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 POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"description" : "new description"
}'
Response body
{"projectId":"projectId1","users":["name1","name2"],"metaData":{"key1":"value1"},"owner":"name1","description":"description","accessLevel":"full","whiteList":["http://www.sechub.example.org"]}
7.6.23. Admin changes project access level
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 id for project |
|
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. 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.25. User creates a new sechub job
REST API for usecase UC_005-User creates a new sechub job
7.6.25.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":"9e8c4ff3-aa6b-428d-9af9-c388e7095905"}
7.6.25.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":"9342bee3-37fe-4892-b855-c5e5097b73c6"}
7.6.25.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":"1769cd18-4515-45f6-a3df-b11483aa5613"}
7.6.25.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":"f358a3d5-a871-4505-b337-41690fc952c0"}
7.6.25.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":"6a253b19-6499-48f1-a3e3-457dda69c4bd"}
7.6.25.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":"91d19d7c-6265-4612-8604-593b352da3ab"}
7.6.25.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'. |
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","use":["openApi-file-reference"]},"url":"https://localhost/mywebapp/login"},"apiVersion":"1.0"}'
Response body
{"jobId":"db2ad95d-fe39-4d2c-9080-4a26ffeaa275"}
7.6.25.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":"031a7a67-5db7-40bb-815b-4f601e8dacba"}
7.6.25.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":"8907996f-f1fd-403d-9e67-e7286aaeebdb"}
7.6.25.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 |
|
|
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"}]}]}}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'
Response body
{"jobId":"a02188ba-2dc8-45e8-a51f-993624a2123c"}
7.6.25.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":"8f0195c2-d82d-4bfa-9d19-9cd259ce5b7e"}
7.6.26. 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. |
Request 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/984b92a8-b02c-410a-8201-ac9e4647e5ff/sourcecode' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-F 'file=PK
�<M test1.txtPK ?
�<M $ test1.txt
��IW� ��IW� ��IW� PK [ ' ' \
-F 'checkSum=mychecksum'
Response body
(empty)
7.6.27. User approves sechub job
REST API for usecase UC_007-User approves sechub job
Definition
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/63080498-e7a1-45d8-a7fe-a4714fd55183/approve' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.28. 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/551241c0-e4e3-4a13-84e9-b183b920575b' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"jobUUID":"551241c0-e4e3-4a13-84e9-b183b920575b","owner":"CREATOR1","created":"","started":"2024-03-15T15:56:28.42732385","ended":"2024-03-15T16:11:28.42735052","state":"ENDED","result":"OK","trafficLight":"GREEN"}
7.6.29. User downloads sechub job report
REST API for usecase UC_010-User downloads sechub job report
7.6.29.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/9e88901a-c1ff-4fe2-b5a6-bdf9a70d018b' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
7.6.29.2. HTML variant
Definition
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/e70d3ed5-cab7-4e73-939a-72747c0da07f' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/xhtml+xml'
7.6.30. User marks false positives for finished sechub job
REST API for usecase UC_044-User marks false positives for finished sechub job
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 '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. 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 describing why this is a false positive |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"apiVersion":"1.0","type":"falsePositiveJobDataList","jobData":[{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"an optional comment why this is a false positive..."}]}'
Response body
(empty)
7.6.31. User unmarks existing false positive definitons
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.32. 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 |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X GET
Response body
{"falsePositives":[{"jobData":{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"Only used in documentation build not in deployment"},"author":"developer1","metaData":{"scanType":"codeScan","name":"Absolute Path Traversal","severity":"MEDIUM","code":{"start":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"args","sourceCode":"\tpublic static void main(String[] args) throws Exception {"},"end":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"File","sourceCode":"\t\tFile documentsGenFolder = new File(path);"}},"cweId":36},"created":"2020-06-12 11:53:15"}]}
7.6.33. User uploads binaries
REST API for usecase UC_069-User uploads binaries
Definition
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 parameters
Parameter | Description |
---|---|
|
A sha256 checksum for file upload validation |
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/3050520a-abcc-42ac-81ec-2a41183898ea/binaries' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-H 'x-file-size: 10240' \
-F 'file=test1.txt 0000664 0001750 0001750 00000000000 13353454574 012170 0 ustar albert albert ' \
-F 'checkSum=mychecksum'
Response body
(empty)
7.6.34. User downloads job report in SPDX format
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/96e5447e-951a-4369-9bdb-fd0b90fd2417' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
7.6.35. User self registration
REST API for usecase UC_001-User self registration
Definition
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.36. 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.37. 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.38. 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.39. 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.40. 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 |
|
|
Configuration used for this job |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/running' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
[{"jobUUID":"8fec5e2a-618a-480e-91ea-07c4081491c6","projectId":"project-name","owner":"owner-userid","status":"RUNNING","since":"2024-03-15T16:11:21.289494909","configuration":"{ config data }"}]
7.6.41. 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/d28f7856-777c-471e-946d-a4d56043f76a' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.42. Admin restarts a job
REST API for usecase UC_041-Admin restarts a job
Definition
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/7eb204a2-0ac4-4498-abf6-cc47e778fc31' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.43. Admin restarts a job (hard)
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/8a2306f6-94a8-4d3a-a50b-f9246d068184' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.44. User defines mock data configuration for project
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.45. 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.46. 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.47. 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.48. 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 config 1","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productXYZ.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"},{"key":"example.key2","value":"Another value"}]}}'
Response body
3d70b300-ecbc-4ac6-8b16-29409aeb42e3
7.6.49. 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/e083f1ba-8973-416a-b984-933f268d1ca1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.50. Admin fetches executor configuration list
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":"eabfa51a-ea6f-46e5-b02d-44001317bee5","name":"example configuration","enabled":true}],"type":"executorConfigurationList"}
7.6.51. 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/101802e8-6aca-4ecd-8933-1c59074ff3c1' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"}]},"executorVersion":1,"enabled":false,"uuid":"101802e8-6aca-4ecd-8933-1c59074ff3c1"}
7.6.52. 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/baba2300-83dc-49c6-84bf-470fcf3746e0' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"name":"New name","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productNew.example.com","credentials":{"user":"env:EXAMPLE_NEW_USENAME","password":"env:EXAMPLE_NEW_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]}}'
Response body
(empty)
7.6.53. Admin creates an execution profile
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.54. 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.55. 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":"367bbe04-7307-4a3a-80ad-f95b04673d9a","executorVersion":0,"enabled":false,"setup":{"credentials":{},"jobParameters":[]}}],"enabled":true}'
Response body
(empty)
7.6.56. 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 config |
|
|
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":[{"name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]},"executorVersion":1,"enabled":false,"uuid":"8ff82efd-1b38-425c-a3f7-be6d38b0065a"}],"projectIds":["project-1","project-2"]}
7.6.57. 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.58. 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.59. 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.60. 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.61. 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.62. 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.63. 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.64. 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.65. 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.66. 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.67. 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 |
Request 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":"dcc0ec19-7a6b-4674-b572-f568a4cee36f","executedBy":"User1","created":"2024-03-15T15:54:28.490962614","started":"2024-03-15T15:56:28.490996778","ended":"2024-03-15T16:11:28.49100849","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 JOB_CANCELLATION_RUNNING
7.7.2.6. Message JOB_CREATED
7.7.2.7. Message JOB_DONE
Use cases related to this message |
7.7.2.8. Message JOB_EXECUTION_STARTING
Use cases related to this message |
7.7.2.9. Message JOB_FAILED
7.7.2.10. Message JOB_RESTART_CANCELED
Use cases related to this message |
7.7.2.11. Message JOB_RESTART_TRIGGERED
Use cases related to this message |
7.7.2.12. Message JOB_RESULTS_PURGED
Use cases related to this message |
7.7.2.13. Message JOB_RESULT_PURGE_DONE
7.7.2.14. Message JOB_RESULT_PURGE_FAILED
7.7.2.15. Message JOB_STARTED
Use cases related to this message |
7.7.2.16. Message MAPPING_CONFIGURATION_CHANGED
7.7.2.17. Message PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE
7.7.2.18. Message PROJECT_ACCESS_LEVEL_CHANGED
7.7.2.19. Message PROJECT_CREATED
7.7.2.20. Message PROJECT_DELETED
7.7.2.21. Message PROJECT_OWNER_CHANGED
7.7.2.22. Message PROJECT_WHITELIST_UPDATED
7.7.2.23. Message REQUEST_JOB_CANCELLATION
7.7.2.25. Message REQUEST_JOB_RESTART_HARD
Use cases related to this message |
7.7.2.26. Message REQUEST_PURGE_JOB_RESULTS
Use cases related to this message |
7.7.2.27. Message REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING
Use cases related to this message |
7.7.2.28. Message REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING
Use cases related to this message |
7.7.2.29. Message REQUEST_SCHEDULER_JOB_STATUS
Use cases related to this message |
7.7.2.30. Message REQUEST_SCHEDULER_STATUS_UPDATE
7.7.2.31. Message REQUEST_USER_ROLE_RECALCULATION
Use cases related to this message |
7.7.2.32. Message SCAN_DONE
7.7.2.33. Message SCAN_FAILED
7.7.2.34. Message SCHEDULER_JOB_PROCESSING_DISABLED
Use cases related to this message |
7.7.2.35. Message SCHEDULER_JOB_PROCESSING_ENABLED
Use cases related to this message |
7.7.2.36. Message SCHEDULER_JOB_STATUS
7.7.2.37. Message SCHEDULER_STARTED
7.7.2.38. Message SCHEDULER_STATUS_UPDATE
7.7.2.39. Message SOURCE_UPLOAD_DONE
7.7.2.40. Message START_SCAN
Use cases related to this message |
7.7.2.41. Message UNSUPPORTED_OPERATION
7.7.2.42. Message USER_ADDED_TO_PROJECT
Use cases related to this message |
7.7.2.43. Message USER_API_TOKEN_CHANGED
7.7.2.44. Message USER_BECOMES_SUPERADMIN
7.7.2.46. Message USER_DELETED
7.7.2.47. Message USER_EMAIL_ADDRESS_CHANGED
7.7.2.48. Message USER_NEW_API_TOKEN_REQUESTED
Use cases related to this message |
7.7.2.49. Message USER_NO_LONGER_SUPERADMIN
7.7.2.50. Message USER_REMOVED_FROM_PROJECT
Use cases related to this message |
7.7.2.51. 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 | 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 | Default | Description |
---|---|---|
sechub.user.onetimetoken.outdated.millis |
86400000 |
One time token time when outdating |
Key | Default | Description |
---|---|---|
sechub.adapter.checkmarx.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter check operation is called next. When -1 value is 1 minutes |
sechub.adapter.checkmarx.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.checkmarx.trustall |
false |
Turns off certification checks for this product only. Should only be used in test or development environments! |
Key | Default | Description |
---|---|---|
sechub.initialadmin.apitoken |
An apitoken for initial admin, will only be used in DEV and INTEGRATIONTEST profiles and is optional! |
|
sechub.initialadmin.email |
Mail of initial administrator |
|
sechub.initialadmin.userid |
Userid of initial administrator |
Key | Default | Description |
---|---|---|
sechub.migration.flyway.autorepair |
true |
When enabled, flyway migration problems will be automatically repaired |
Key | Default | Description |
---|---|---|
sechub.notification.email.mock.cache.enabled |
false |
When email mock shall cache the mails this must be configured to true, per default disabled! |
Key | Default | Description |
---|---|---|
sechub.adapter.nessus.defaultpolicyid |
deprecated |
Default policy ID for nessus scans |
sechub.adapter.nessus.internet.baseurl |
deprecated |
Base url of nessus used for internet scans |
sechub.adapter.nessus.internet.password |
deprecated |
Password for nessus instance used for internet scans |
sechub.adapter.nessus.internet.userid |
deprecated |
User id of nessus user (internet) |
sechub.adapter.nessus.intranet.baseurl |
deprecated |
Base url of nessus used for intranet scans |
sechub.adapter.nessus.intranet.password |
deprecated |
Password for nessus instance used for intranet scans |
sechub.adapter.nessus.intranet.userid |
deprecated |
User id of nessus user (intranet) |
sechub.adapter.nessus.proxy.hostname |
Proxy hostname for nessus server connection, when empty no proxy is used. When not empty proxy port must be set too! |
|
sechub.adapter.nessus.proxy.port |
0 |
Proxy port for nessus server connection, default is 0. If you are setting a proxy hostname you have to configure this value correctly |
sechub.adapter.nessus.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.nessus.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.nessus.trustall |
true |
Turns off certification checks for this product only. Should only be used in test or development environments! |
Key | Default | Description |
---|---|---|
sechub.adapter.netsparker.agentname |
deprecated |
The name of the agent to be used by netsparker. If a agent group name is already defined the group will be superiour. If no group set and no agent name netsparker will use a agent but seems to be unpredictable which agent will be used. |
sechub.adapter.netsparker.apitoken |
deprecated |
API token for netsparker user |
sechub.adapter.netsparker.baseurl |
deprecated |
Base url for netsparker installation |
sechub.adapter.netsparker.defaultpolicyid |
deprecated |
Default policy ID for netsparker scans |
sechub.adapter.netsparker.internet.agentgroupname |
deprecated |
The name of the agent group to be used by netsparker for intranet scans. If not set no agent group will be used. |
sechub.adapter.netsparker.intranet.agentgroupname |
deprecated |
The name of the agent group to be used by netsparker for intranet scans. If not set no agent group will be used. |
sechub.adapter.netsparker.licenseid |
deprecated |
|
sechub.adapter.netsparker.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.netsparker.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter check operation is called next. When -1 value is 1 minutes |
sechub.adapter.netsparker.trustall |
true |
Turns off certification checks for this product only. Should only be used in test or development environments! |
sechub.adapter.netsparker.userid |
deprecated |
user id of netsparker user |
Key | Default | Description |
---|---|---|
sechub.user.onetimetoken.outdated.millis |
86400000 |
Time until the one time token expires |
Key | Default | Description |
---|---|---|
sechub.notification.email.administrators |
Single email address used for emails to administrators. This should be a NPM (non personalized mailbox) |
|
sechub.notification.email.from |
Address used for emails sent by sechub system |
|
sechub.notification.email.replyto |
Address used for reply when email was sent by sechub system |
Key | Default | Description |
---|---|---|
sechub.adapter.checkmarx.resilience.badrequest.retry.max |
3 |
Amount of retries done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.badrequest.retry.wait |
2000 |
Time to wait until retry is done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.max |
1 |
Amount of retries done when a 500 server internal error happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.wait |
5000 |
Time to wait until retry is done when a 500 server internal error happened on Checkmarx server |
sechub.adapter.pds.default.check.timetowait.milliseconds |
30000 |
Time in milliseconds when adapter check operation is called next. When -1 value is 60000 minutes |
sechub.adapter.pds.default.timeout.minutes |
240 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
Key | Default | Description |
---|---|---|
sechub.notification.smtp.config |
mail.smtp.auth=false,mail.transport.protocol=smtp |
SMTP configuration map. You can setup all java mail smtp settings here in comma separate form with key=value. For Example: |
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 | 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 | Default | Description |
---|---|---|
sechub.config.trigger.healthcheck.enabled |
true |
When enabled each trigger will do an healtching by monitoring service. If system has too much CPU load or uses too much memory, the trigger will not execute until memory and CPU load is at normal level! |
sechub.config.trigger.nextjob.delay |
10000 |
Define delay for next job execution trigger after last executed. |
sechub.config.trigger.nextjob.initialdelay |
5000 |
Define initial delay for next job execution trigger. Interesting inside a cluster - just define this value different inside your instances (e.g. random value). This avoids write operations at same time. |
sechub.config.trigger.nextjob.maxwaitretry |
300 |
When retry mechanism is enabled by |
sechub.config.trigger.nextjob.retries |
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 | Default | Description |
---|---|---|
sechub.adapter.checkmarx.resilience.badrequest.retry.max |
3 |
Maximum amount of possible retries for situations when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.badrequest.retry.wait |
2000 |
Time to wait until retry is done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.networkerror.retry.max |
100 |
Maximum amount of possible retries for situations when a network error happened on communication to Checkmarx server |
sechub.adapter.checkmarx.resilience.networkerror.retry.wait |
5000 |
Time to wait until retry is done when a network server happened on communication to Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.max |
1 |
Maximum amount of possible retries for situations when a 500 server internal error happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.wait |
5000 |
Time to wait until retry is done when a 500 server internal error happened on Checkmarx server |
sechub.project.joblist.page.max |
100 |
|
sechub.project.joblist.size.max |
100 |
Maximum limit for job information list entries per page |
sechub.server.baseurl |
Base url of SecHub server - e.g. https://sechub.example.org |
Key | Default | Description |
---|---|---|
sechub.security.diffiehellman.length |
Define diffie hellman key length, see https://github.com/mercedes-benz/sechub/issues/689 for details |
Key | Default | Description |
---|---|---|
sechub.server.debug |
false |
When debug flag is set, rest call reponse error messages do also contain stacktraces. |
Key | Default | Description |
---|---|---|
sechub.storage.s3.accesskey |
undefined |
Defines the access key for used S3 bucket |
sechub.storage.s3.bucketname |
undefined |
Defines the S3 bucket name |
sechub.storage.s3.connection.idle.max.milliseconds |
60000 |
S3 client maximum idle time (in milliseconds) for a connection in the connection pool. |
sechub.storage.s3.connection.idle.validate.milliseconds |
5000 |
S3 client time (in milliseconds) a connection can be idle in the connection pool before it must be validated that it’s still open. |
sechub.storage.s3.connection.max.poolsize |
50 |
S3 client max connection pool size. |
sechub.storage.s3.connection.ttl.milliseconds |
-1 |
S3 client expiration time (in milliseconds) for a connection in the connection pool. -1 means deactivated |
sechub.storage.s3.endpoint |
undefined |
Defines the S3 endpoint - e.g. https://play.min.io |
sechub.storage.s3.secretkey |
undefined |
Defines the secret key for used S3 bucket |
sechub.storage.s3.signer.override |
AWSS3V4SignerType |
Can be used to override the default name of the signature algorithm used to sign requests. |
sechub.storage.s3.timeout.connection.milliseconds |
10000 |
S3 client timeout (in milliseconds) for creating new connections. |
sechub.storage.s3.timeout.execution.milliseconds |
0 |
S3 client timeout (in milliseconds) for execution. 0 means it is disabled. |
sechub.storage.s3.timeout.request.milliseconds |
0 |
S3 client timeout (in milliseconds) for a request. 0 means it is disabled. |
sechub.storage.s3.timeout.socket.milliseconds |
50000 |
S3 client timeout (in milliseconds) for reading from a connected socket. |
sechub.storage.sharedvolume.upload.dir |
undefined |
Defines the root path for shared volume uploads - e.g. for sourcecode.zip etc. When using keyword temp as path, this will create a temporary directory (for testing). |
Key | Default | Description |
---|---|---|
sechub.monitoring.accepted.cpu.average.max |
2.0 |
Maximum CPU load average accepted by sechub system. Value is calculated by measured system load average divided by available processors. A value above 1.0 usually means that a processor is very heavily loaded. |
sechub.monitoring.accepted.memory.usage.max |
90.0 |
Maximum memory usage percentage accepted by sechub system. Can be a value from 50 up to 100 for 100% |
sechub.monitoring.cache.time.millis |
2000 |
Time in milliseconds monitoring fetch results are cached before fetching again |
Key | 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. |
8.2.5. Configuration properties for mocked adapters
Key | Default | Description |
---|---|---|
sechub.adapter.mock.sanitycheck.enabled |
false |
See AbstractMockedAdapter.java |
Key | Default | Description |
---|---|---|
sechub.adapter.checkmarx.clientsecret |
014DF517-39D1-4453-B7B3-9930C563627C |
See MockedCheckmarxAdapter.java |
sechub.adapter.mock.setup.filepath |
./../sechub-other/mockdata/mockdata_setup.json |
See MockedAdapterSetupService.java |
8.3. Local development
This section describes the start on local machine (development/presentation).
Only SecHub itself is described. The products must be either running and well
configured, or profile mocked_products
must be active.
See product infrastructure sections for details.
8.3.1. Java launch configuration setup
Because it takes too much time - even when security products are configured with
test profiles (for testing persistence, transaction rollback etc.) a
mocked_products
profile was introduced which can be used.
It does use normal product executors but injects mocked adapters
(e.g. MockedNessusAdapter
, MockedNetsparkerAdapter
, ..)
which do not really communicate with the real security products but return
instead preconfigured values (which where recorded from real communications).
Startup is done by using active spring profile mocked_products
.
Some mocks have special options to change their behaviour at runtime.
8.3.1.1. Launch in demo mode
Here an example for calling in demomode:
To start spring boot application SecHubServerApplication
create a new launch configuration with
following arguments:
class: com.mercedesbenz.sechub.SecHubServerApplication
-Dspring.profiles.active=demomode
8.3.1.2. Launch in DEV mode
To start spring boot application SecHubServerApplication
create a new launch configuration with
following arguments:
class: com.mercedesbenz.sechub.SecHubServerApplication
-Dspring.profiles.active=dev,h2,real_products (1)
-Dsechub.server.debug=true (2)
...
-Dsechub.adapter.name.something.specific=${necessaryData} (3)
...
-Dsechub.storage.sharedvolume.upload.dir=temp (4)
-Dsechub.initialadmin.userid=sechubadm (5)
-Dsechub.initialadmin.email=sechubadm@example.org(5)
-Dsechub.initialadmin.apitoken=pseudo-token-development-only(5)
1 | Enables debug logging, localserver certificates, uses real products
and starts server with h2 database.
|
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. Checkmarx
Currently we provide Checkmarx as direct product inside SecHub and also as a PDS solution. The aim is to provide Checkmarx only as pds} solution in future. So the direct product integration will vanish. |
Static code analyzer see http://www.checkmarx.com/
8.4.4. Netsparker
Netsparker support inside SecHub is deprecated and will vanish. As a replacement we have: https://github.com/mercedes-benz/sechub/tree/develop/sechub-pds-solutions/owaspzap |
Netsparker is a web scanner.
8.4.5. Nessus
Nessus support inside SecHub is deprecated and will vanish when there is another infrastructure scan product integration available as an replacement. |
8.5. Kubernetes
We provide container images and Helm charts: https://github.com/mercedes-benz/sechub/packages
8.6. Docker-Compose
Change into the product’s folder and issue:
docker-compose up
Please also see the README file in the respective folder. |
9. Cross-cutting Concepts
9.1. Security tools
9.1.1. Modules and module groups
9.1.1.1. Modules
Security tools are categorized into modules. Each module performs a different security testing method:
Module | Description |
---|---|
codeScan |
Scans the code for potential vulnerabilities (weaknesses). Also known as SAST or static source code analysis |
webScan |
Scans a deployed web application for vulnerabilities. Also known as DAST. |
infraScan |
Scans infrastructure for vulnerabilities. |
licenseScan |
Scans code or artifacts for license information |
secretScan |
Scans code or artifacts for secrets |
9.1.1.2. Module groups
Every module belongs to exact one module group:
Module | Module group |
---|---|
codeScan |
static |
webScan |
dynamic |
infraScan |
network |
licenseScan |
static |
secretScan |
static |
Every module group contains at least one module:
Module group | Contained modules |
---|---|
static |
codeScan, licenseScan, secretScan |
dynamic |
webScan |
network |
infraScan |
Inside a SecHub configuration file the user defines which modules shall be executed by the SecHub job. But only modules which are in same module group can be run as part of the same job.
As an example: Inside one SecHub job configuration file, it is
|
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. Mappings
SecHub needed a way to configure simple configuration values and also provide a mapping from project names to adapter specific values (see Scan config )
9.4.1. Structure
To provide this in a very generic way SecHub does use the mappings
means
a simple setup of
-
pattern
(simple key or a regular expression) -
replacement
(just the value) -
comment (describes what this mapping is used for - just for information)
9.4.2. Domain handling
9.4.2.1. Global mappings
The Administration
domain will know every global mapping (e.g. scan configuration) and provide the
corresponding REST API for administrators.
Changes of global mappings will be sent from administration domain to other domains via event bus and a message with ID: MAPPING_CONFIGURATION_CHANGED.
Dedicated message handlers inside other domains will recognize wanted parts and store information when necessary.
9.4.2.2. Product executor parameter mappings
This will not lead to any domain event. The product executors will inspect the mapping information always again before a job has been started. The mapping data is stored inside executor configurations, which is always available inside a job execution, so there is no need of any domain events.
9.5. Product delegation server
9.5.1. General
There are many open source clients available having no server component inside so lacking:
-
REST access
-
queuing
-
status requests
-
scalable
-
… more
So when we want to adapt them in SecHub style (the product does the work and we ask for result) we
need to provide a ProductDelegationServer
(in short form PDS
).
PDS
is
-
a spring boot application which uses a network DB for providing cluster possibility
-
a complete standalone application without runtime dependencies to SecHub server (or its shared kernel)
-
provides REST access
-
a very simple priviledge model with just two users (
tech user
+admin user
), basic auth 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.5.2. Handling of resources
-
PDS server provides
auto unzipping
of uploaded resources when configured - see PDS server configuration file -
When a PDS job fails or is done the resources inside job workspace location are automatically removed
9.5.3. Big picture
9.5.4. Storage and sharing
PDS needs - like SecHub - the possiblity to store job data in a central storage location when operating inside a cluster (it’s not clear which cluster member uploads job data and which one does execute the job and need the data at exectuion time).
PDS does use the already existing sechub-storage-*
libraries which provide storage mechanism for S3 and
for shared volumes.
The next examples explain the different situations appearing for a PDS cluster executing product "XYZ", but of course this applies to multiple clusters for different products as well |
For non clustered environment "shared volumes" can also be local file system paths like
|
When talking about a NFS or a shared volume here, this is always meant to be a file system path. It’s important to mount a NFS at a local file path for the PDS server when using a shared volume. URLs are NOT supported - only file paths. So you must mount your network file storage to a local file location! For example: a base path for a shared volume could look like: |
9.5.4.1. Shared S3 storage
In the next example PDS and SecHub are using the same S3 bucket to store files uploaded by the user.
We have two different scenarios here:
-
Product executor configuration
pds.config.use.sechub.storage
istrue
In this case the way is exactly as shown in next picture:-
The user uploads job data for a SecHub job and it is stored at shared S3 bucket (blue lines).
-
When SecHub job is starting it will create a PDS job but does not upload any additional data.
-
When PDS job is starting the PDS server will fetch workspace files from existing SecHub job data (red lines).
-
The storage path location is for PDS and SecHub
${sharedS3Bucket}/jobstorage/${secHubJobUUID}/
-
-
Product executor configuration
pds.config.use.sechub.storage
is NOTtrue
In this case the way is NOT like in picture before, but more like in Different S3 storages. Read there for more details - it’s the same - except there are not 2 different S3 buckets but only one.
9.5.4.2. Different S3 storages
In the next example PDS and SecHub are using different S3 buckets as storage.
We have two different scenarios here:
-
Product executor configuration
pds.config.use.sechub.storage
is NOTtrue
In this case the way is exactly as shown in next picture:-
The user uploads job data for a SecHub job and it is stored at shared S3 bucket (blue lines).
-
The storage path location for SecHub is
${sechubS3Bucket}/jobstorage/${secHubJobUUID}/
-
When SecHub job is starting it will create and initialize a PDS job by uploading all existing job data by PDS rest API. This will store job data at PDS storage. (green lines).
-
When PDS job is starting, the PDS server will fetch workspace files from its PDS job data (red lines).
-
The storage path location for PDS is
${pdsS3Bucket}/pds/${pdsProductIdentifier}/${pdsJobUUID}/
-
-
Product executor configuration
pds.config.use.sechub.storage
istrue
This will NOT WORK! The job storage will not be found and an error will be thrown at job execution time. |
9.5.4.3. Same shared volume (NFS)
In the next example PDS server and SecHub are using same shared volume as storage.
We have two different scenarios here:
-
Product executor configuration
pds.config.use.sechub.storage
istrue
In this case the way is exactly as shown in next picture:-
The user uploads job data for a SecHub job and it is stored at shared volume (blue lines).
-
When SecHub job is starting it will create a PDS job but does not upload any additional data.
-
When PDS job is starting the PDS server will fetch workspace files from existing SecHub job data (red lines).
-
The storage path location is for PDS and SecHub
${sharedVolumeBasePath}/jobstorage/${secHubJobUUID}/
-
-
Product executor configuration
pds.config.use.sechub.storage
is NOTtrue
In this case the way is NOT like in picture before, but more like in Different shared volumes. Read there for more details - it’s the same - except there are not 2 different NFS but only one.
9.5.4.4. Different shared volumes (NFS)
In the next example PDS and SecHub are using different shared volumes as storage.
We have two different scenarios here:
-
Product executor configuration
pds.config.use.sechub.storage
is NOTtrue
In this case the way is exactly as shown in next picture:-
The user uploads job data for a SecHub job and it is stored at SecHub shared volume (blue lines).
-
The storage path location for SecHub is
${sechubSharedVolumeBasePath}/jobstorage/${secHubJobUUID}/
-
When SecHub job is starting it will create and initialize a PDS job by uploading all existing job data by PDS rest API. This will store job data at PDS storage. (green lines).
-
When PDS job is starting, the PDS server will fetch workspace files from its PDS job data (red lines).
-
The storage path location for PDS is
${pdsSharedVolumeBasePath}/pds/${pdsProductIdentifier}/${pdsJobUUID}/
-
-
Product executor configuration
pds.config.use.sechub.storage
istrue
This will NOT WORK! The job storage will not be found and an error will be thrown at job execution time. |
9.5.4.5. Mixing S3 and shared volume (NFS)
This example is only mentioned for the sake of completeness: It is the same as before described for different S3 and different shared volumes:
pds.config.use.sechub.storage
cannot be used in this case.
When not reusing SecHub storage, this scenario does work also well. In the next picture, SecHub itself would use a S3 storage and he
PDS instances for product XYZ
would use a NFS to store job data. But of course it could be also the other way.
9.5.5. Process execution
PDS instances are executing so called caller scripts
by spanning a new process. At this time
dedicated environment variables are automatically injected and available inside the scripts.
When implementing a new PDS product integration you should always start with a normal,
executable script (e.g. So you can simply call your script standalone and when it works you just have to create the PDS configuration file and make the script callable. |
9.5.5.1. How PDS provides output and error stream content of running jobs in clustered environments
We use error.txt
and output.txt
inside the workspace location of
a running PDS job.
The PDS job process does not store the files on a shared volume or S3 bucket but on the local file system (like done for uploaded source files for example).
So we can easily write those text content from the files to our database when the OS process (executing PDS caller script) has finished or failed, because at this time we have direct access to the files.
But when an administrator wants to get the current output for a running job / operation this becomes tricky in a clustered environment, because the process stream data is only available on the machine where the job is executed. Using a loadbalancer we do not know which machine will be used for the REST operation.
So it becomes necessary, that the executing cluster member will store the error and output text data in database to provide this cluster wide.
On the other hand it shall not slow down or block the execution machine because of permanent updates inside the DB. If an admin wants to check the output or error stream content of a running job, the information shall be gathered on demand. But when the job has finished (no matter if canceled, done or failed) the information will always be written to DB.
The next figure gives an overview about the workflow to achieve this goal:
9.5.5.2. How PDS handles meta data
When communication of PDS with the used product is stateful and is a long running operation, it can be useful to store such state/meta data.
One use case is the restart possibility for a SecHub job. Another one are debugging or trace information.
Most times PDS solutions do not need to store special meta data information: When the PDS job starts a CLI tool, the result or the failure will just be returned to the SecHub side. If it shall be done again (because of on failure) just a new PDS job will be started. If a PDS job has meta data this means it should be restarted |
A PDS launcher script has no access to the PDS database!
If meta data shall be read or written, we just have the workspace file metadata.txt
.
Inside this file the product relevant meta data
of the job run must be available, see next diagram for details:
9.5.5.2.1. Checkmarx PDS solution adapter meta data handling
The PDS solution for Checkmarx
does reuse the already existing CheckmarxAdapter
class.
A sechub-wrapper-checkmarx
gradle project was introduced which contains a simple spring boot
CLI application which uses the adapter for communication. The adapter callback is not directly
reading or writing to the database but uses the metadata.txt
file from the PDS workspace.
Look at next figure for more details:
9.5.5.3. How PDS handles storage data
The PDS
does automatically fetch uploaded files from shared storage
temporary into its local filesystem. After the scan has been done, the temporary local files
will be automatically deleted.
9.5.5.3.1. Source code fetching
Source code is always contained in a file called sourcecode.zip
.
When a PDS
starts a new job, it will fetch the complete ZIP file from storage
to it’s local storage at
${PDSJobWorkspaceLocation}/upload/sourcecode.zip
.
Afterwards the relevant sources will be automatically extracted by inspecting the archive data structure.
9.5.5.3.2. Binaries fetching
Binaries are always contained in a file called binaries.tar
.
When a PDS
starts a new job and the scan does references a binary data section, it will fetch
the complete TAR file from storage to it’s local storage at
${WorkspaceLocation}/upload/binaries.tar
.
Afterwards the relevant binaries will be automatically extracted by inspecting the archive data structure.
9.5.5.3.3. Data structure inside TAR and ZIP files
The data structure inside TAR
and ZIP
files contains
data configuration parts inside data
folder.
Before we introduced the possibility to define referenceable data inside a
SecHub configuration, we already provided a For source scans this a more convenient way and we wanted to keep this possiblity - also for backward compatibility with existing SecHub configuration files. So this is the reason, why data is contained inside |
Only source code scan configuration files may be located inside the root folder! |
${content} (1)
__data__/unique-name-1/${content} (2)
__data__/unique-name-2/${content} (3)
...
1 | code scan embedded file system data |
2 | content of a data configuration with name "unique-name-1" |
3 | content of a data configuration with name "unique-name-2" |
Here an example:
{
"data": {
"sources": [ (1)
{
"name": "reference-name-sources-1", (2)
"fileSystem": {
"files": [
"somewhere/file1.txt",
"somewhere/file2.txt"
],
"folders": [
"somewhere/subfolder1",
"somewhere/subfolder2"
]
},
"excludes": [
"**/mytestcode/**",
"**/documentation/**"
],
"additionalFilenameExtensions": [
".cplusplus",
".py9"
]
}
],
"binaries": [ (3)
{
"name": "reference-name-binaries-1", (4)
"fileSystem": {
"files": [
"somewhere/file1.dll",
"somewhere/file2.a"
],
"folders": [
"somewhere/bin/subfolder1",
"somewhere/bin/subfolder2"
]
}
},
{
"name": "reference-name-binaries-2", (5)
"fileSystem": {
"files": [
"somewhere-else/file1.dll",
"somewhere-else/file2.a"
],
"folders": [
"somewhere-else/bin/subfolder1",
"somewhere-else/bin/subfolder2"
]
}
}
]
}
}
1 | source definition - these structure parts are inside the sourcecode.zip file |
2 | Name of one source data configuration |
3 | binaries definition - these structure parts are inside the binaries.tar file |
4 | Name of the first binaries data configuration |
5 | Name of the second binaries data configuration |
The example json configuration defines following content structure inside the upload files:
__data__/
reference-name-sources-1/ (2)
somewhere/
file1.txt
file2.txt
subfolder1/
example-content.py9
subfolder2/
example-content.cplusplus
example-content.txt
The example json configuration would lead to a TAR
file containing:
__data__/
reference-name-binaries-1/(4)
somewhere/
file1.dll
file2.a
subfolder1/
example-content.bin
subfolder2/
example-content.img
reference-name-binaries-2/(5)
somewhere-else/
file1.dll
file2.a
subfolder1/
example-content.bin
subfolder2/
example-content.img
9.5.5.3.4. Automated Extraction of relevant parts
Only files and folders which are available for the configured scan type will be automatically
extracted!
The artificial path element _data_
and the reference name will not be contained in extracted
folders.
Please read the SecHub technical documentation for more details about the data configuration. You will find it described at https://mercedes-benz.github.io/sechub. |
Automated extraction of source code
Let’s assume PDS has fetched sourcezip.zip
which contains following structure:
__data__/
license-sources/
somewhere/
file1a.txt
subfolder1/
file1b.txt
file2.txt
other-sources/
file3.txt
and a SecHub configuration file like this:
{
// .. assume data section and other parts are configured correctly ..
"licenseScan": {
"use" : ["license-sources"]
},
"codeScan": {
"use" : ["other-sources"]
}
}
In the example the SecHub configuration has a license scan configured which references
license-sources
data configuration and a code scan which references other-sources
.
The PDS
for license scanning will only extract license-sources
:
${PDSJobWorkspaceLocation}/upload/unzipped/sourcecode
somewhere/
file1a.txt
subfolder1/
file1b.txt
file2.txt
|
Automated extraction of binaries
Let’s assume PDS has fetched binaries.tar
which contains following structure:
__data__/
license-binaries/
somewhere/
file1a.bin
subfolder1/
file1b.bin
file2.bin
other-binaries/
file3.bin
and a SecHub configuration file like this:
{
// .. assume data section and other parts are configured correctly ..
"licenseScan": {
"use" : ["license-binaries"]
},
"codeScan": {
"use" : ["other-binaries"]
}
}
In the example the SecHub configuration has a license scan configured which references
license-binaries
data configuration and a code scan which references other-binaries
.
The PDS
for license scanning will only extract license-binaries
:
${PDSJobWorkspaceLocation}/upload/extracted/binaries
somewhere/
file1a.bin
subfolder1/
file1b.bin
file2.bin
9.5.5.4. How PDS handles user messages
9.5.5.5. How PDS handles execution events
9.5.6. PDS events
Sometimes it is necessary that the PDS inform the script about changes. This can be done by execution events.
9.5.6.1. Overview
The product adapter is able to read and write events into a dedicated folder inside the workspace.
This is utilized by the PDSWorkspaceService
class.
As an example for an event the PDS cancel service calls are additionally shown (grey) |
9.5.6.2. Handling events in launcher script
The launcher scripts (or in started wrapper applications by these scripts) have the
environment variable PDS_JOB_EVENTS_FOLDER
injected.
The launcher part must inspect the folder periodically for new
Most PDS solutions do not need to inspect for events. It depends on the situation if there is any special event treatment necessary. An example: |
9.5.6.3. How PDS product executors configure the PDS adapter
The different PDS product executors have different config builders which inherit from different abstract base classes
(e.g. AbstractCodeScanAdapterConfigBuilder
). We have no multi inheritance in Java, but we do also not
want to implement the setup logic (which is complicated) for every PDS product executor again.
There is a specialized adapter configuration strategy for PDS standard setup: PDSAdapterConfigurationStrategy
.
9.5.6.4. Overview
9.5.7. SecHub integration
9.5.7.1. Executors and Adapters
9.5.7.1.1. Executors
With PDS
there is a default REST
API
available.
For different scanTypyes there will be dedicated PDSExecutors
(PDSWebScanExecutor
, PDSInfraScanExecutor
, etc., etc.)
9.5.7.1.2. Adapters
The Adapter will always be the same, but filled with other necessary parameters.
So there will be no need to write any adapter or executor when using PDS! |
9.6. HowTo integrate a new product via PDS
Having new security product XYZ but being a command line tool, we
-
create an environment (e.g. a docker container) where all your needed parts are integrated. E.g. bash shell, tools, the product and its dependencies etc.
-
create an executable starter script (e.g. bash) which
-
calls the product
-
does system out/err to standard pipes
-
writes the product result report to relative path
./output/result.txt
-
-
create a
PSD
configuration file and fill with necessary data, see PDS server configuration file -
start wanted amount of
ProductDelegationServer
instances with dedicated configuration setup to have a clustered, server ready execution of CLI security products. If you want your PDS to be started inside a cluster you have to setup load balancing etc. by your own. For example: When using Kubernetes you normally would do this by just defining aService
pointing to yourPODs
. -
test via developer admin UI if the servers are working:
-
create test job, remember PDS job uuid
-
upload data
-
mark job as ready to start
-
check job state
-
fetch result and inspect
-
-
when former test was successful
-
Define executor on SecHub server side - will be implemented with #148
-
When your product uses sereco general report format your are done- will be implemented with #283 otherwise SERECO must have a logic to import custom format for the PRODUCT - means needs an implementatiion
-
-
test via SecHub client by starting a new SecHub job which shall use the product and verify results
9.7. Archive extraction
The data structure concept does need an automated archive
extraction. The main java class is ArchiveSupport
.
The next figure gives an overview about the involved classes:
9.8. False-positive handling
SecHub must be able to handle false positives of used products.
9.8.1. General
9.8.1.1. How can false positives be handled across multiple security products?
9.8.1.1.1. Problem
-
Missing API
Most commercial security products are able to mark false positives, but maybe not every tool has a dedicated API for this feature. In addition, many FOSS security tools do not support false positive handling.
9.8.1.1.2. Solution
Instead of configuring false positives for each product (e.g. by calling a REST API) we do the filtering of false positives always at SecHub side only!
The involved product just returns all it’s findings without any false positive marking on the product side. SecHub will store the product results in the database without any filtering.
Only when it comes to report generation at the end, SecHub will filter the false positives from the result. This makes it easy to debug - the original information from the product is still available and problems on false positive marking can be reproduced and fixed.
9.8.1.2. Different kinds of false-positive filtering
Some people prefer code/API-centric way to define false positives, some prefer a WebUI.
9.8.1.2.1. API centric
Define false positive handling in JSON
by referencing a former SecHub job UUID and the
corresponding finding entry (by id) and post it to REST API.
JSON
{
"apiVersion": "1.0", (1)
"type": "falsePositiveJobDataList", (2)
"jobData": [
{
"jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd", (3)
"findingId": 1, (4)
"comment": "Absolute Path Traversal, can be ignored because not in deployment" (5)
},
{
"jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd",
"findingId": 15
}
]
}
1 | API version |
2 | a type identifier for false positives, so it’s clear what this file represents |
3 | job UUID for which the given identifiers are representative |
4 | the finding id (number) in the report |
5 | comment (optional) are only to define why this is a false positive. |
This is a very easy, generic approach - and also future-proof: The only dependency is to the job,
The |
ID handling
We must ensure identifiers are always correct and continue even for false positives. An example:
We have a SecHub job 1 were we mark the first finding with id 1 as a false positve. Executing now SecHub job 2 finding with id 1 must be filtered. But findings may no longer start with identifier 1! Because the finding already exists.
9.8.1.2.2. Web UI
Just uses the API centric approach (by using given REST API,) over UI.
9.8.1.2.3. Code centric
Inside source code / deployment scripts etc. users can define comments to define false positive handling - this is only possible for situations where we have access to source code - means SAST (static application security testing)
Currently this is not supported! The detection algorithm is already implemented inside |
9.8.2. Code scan
9.8.2.1. API centric
see general concept
9.8.2.1.1. How to identify same vulnerability on code changes?
-
We inspect source and sink and use
-
Location
-
relevant part - this is absolutely necessary.
-
-
Line numbers must always be irrelevant!
Very important for Sereco: If no relevant part is available we must at least create a pseudo one by given source snippet - in a whitespace reduced form! We will compress the source content, so adding new lines, spaces, tabs etc. would not matter. So if a product does not support "relevant part" detection we must create the "relevant
part" inside |
9.8.2.2. Web UI
see general concept
9.8.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.8.2.3.1. Java
We will provide single comments (//
)
// SPDX-License-Identifier: MIT
public class FalsePositiveJavaApplication {
public static void main(String[] args) {
// NOSECHUB (1)
falsePositiveCall(); //NOSECHUB-END (2)
}
}
1 | marks start |
2 | marks end |
All between those tags will be ignored by SecHub.
9.8.3. Web scan
9.8.3.1. Code centric
Not possible
9.8.3.2. API centric
see general concept
9.8.3.3. Web UI
see general concept
9.8.4. Infra scan
9.8.4.1. Code centric
Not possible
9.8.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.8.4.3. Web UI
see general concept
9.9. Product execution profiles and executor configuration
To have the possibility of using dedicated security products for different projects, to disable/enable products on demand without server restart or just to test new products in one evaluation project but not for all other projects a runtime configuration is necessary.
This is provided by execution profiles and and executor configurations.
9.9.1. Overview
9.9.2. Executor configuration
An executor configuration represents a runtime configuration for product executors. The configuration has an enabled state. So it is possible to enable/disable product execution.
9.9.3. Execution profile
An execution profile can contain multiple executor configurations. The configurations can be shared between multiple profiles. E.g. a config with name "pds-gosec-1" can be used in profiles "profileA" and also "profileB" at the same time.
Additionally a profile can be assigned to a project (but technically we assign a projectId to a profile, because
in domain scan
we only know projectIds but no the Project
entity…).
The profile has also an enabled state - like executors.
9.9.4. How execution process uses profiles and configurations
ScanService
is called by SecHub batch operation from scheduler and contains the project id for the
project to scan for.
When it comes to execution, ProductExectionStoreService
fetches all enabled profiles related to the given
project id and executes all enabled product executors for the wanted scan job - e.g. code scan product executors
9.9.4.1. Results handling done by configured report executor or fallback
All of the results returned by the dedicated product executors are stored in database. After this has been done,
the configured report product executor(s) is (are) executed (if none has been defined in at least one profile, the
fallback will automatically use Sereco
product executor version 1, which is embedded)
9.10. Product results
Product results can be either from security products or from reporting products.
For a job different security products can be executed, depending on the execution configuration.
After this the results will be stored in database as dedicated ProductResult
entries.
Afterwards reporting products will be executed to collect the former stored reports and merge them together.
The report product merge result will be stored as a ProductResult
as well in database for the job.
When no report collector is configured/available the embedded report product Sereco ("SecHub report collector") will be used .
|
9.10.1. Product messages inside product result
Every product can add custom messages which shall be available to user.
9.10.1.1. Storing product messages
The product adapter fetches the information from the product and delivers it to
the product executor, who stores the SecHub messages inside the ProductResult
entity.
9.10.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.10.2. Report data flow
9.10.2.1. Report model
Here a reduced class model of the report data model:
9.10.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.10.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.11. 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.11.1. Job status fetching
9.11.2. Job status data flow
9.11.2.1. Job execution done, final Job status update
9.12. 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.13. Auto cleanup
To prevent full hard drives there is an option to automatically remove old data.
See also |
9.13.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.13.2. Execution
The execution is automatically done by SecHub.
9.13.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.14. 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.14.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.14.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.15. 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.16. 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. |
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. |