About SecHub
SecHub is an acronym for Security Hub
and is first of
all one API to scan for different security problems. Users of SecHub do not
care about which exact product is doing the real scan on server side, but only
configure their wanted aim.
SecHub does NOT provide a security infrastructure but does orchestrate different security products/tools. So you still need an existing security infrastructure behind SecHub ! |
It was designed to be very easy to integrate into any existing build pipeline / contionus integration (CI) and helps to provide SecDevOps.
You can get more information about from SecHub web page . The project is hosted at https://github.com/mercedes-benz/sechub |
About documentation
This documentation is part of SecHub
.
Key | Value | Information |
---|---|---|
LICENSE |
MIT License |
Please look at https://github.com/mercedes-benz/sechub/blob/master/LICENSE |
Documentation version: Server 2.3.1 modified (commit 7de5e5c) - Build date: 2024-11-27 09:48 (UTCZ)
This architecture documentation is based on arc42 template.
About arc42
arc42, the Template for documentation of software and system architecture.
By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.
Template Revision: 7.0 EN (based on asciidoc), January 2017
© We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.
1. Introduction and Goals
1.1. About
Describes the relevant requirements and the driving forces that software architects and development team must consider. These include
-
underlying business goals, essential features and functional requirements for the system,
-
quality goals for the architecture,
-
relevant stakeholders and their expectations
1.2. What is SecHub?
SecHub is an easy to use security scan integration for developers to provide security tooling as a SecDevOps service. It can be used by build servers and other tools.
Independent from security products: The So security products used by SecHub server instance(s) can change on time but usage and configuration of SecHub will not change at all! |
1.3. Requirements Overview
1.3.1. Non functional requirements
1.3.1.1. Scalable
SecHub server must be able to scale vertically and horizontally.
SecHub itself is build to be ready for usage inside Kubernetes clusters, so main bottle neck will normally
not be SecHub but maybe used security products.
|
1.3.1.2. High available
SecHub server must be able to handle new job requests at any time so at least jobs must must be accepted and added to queue.
1.3.1.3. Resilient
-
Security product connection failure
One failing security product shall not lead in a non working SecHub "state" but produce a dedicated entry in scan results! -
The system shall be still working on errors
1.3.1.4. Stable
-
API and configuration syntax are stable and do NOT change in a breaking way
1.3.1.5. Acceptable
SecHub shall be accepted by developers. So it must be easy to use, to embed and also … just work!
1.3.2. Functional requirements
-
One single and easy to use API / client to secure
-
Easy to integrate new security products
More and also more detailed functional requirements can be found in issue tracker system
1.4. Quality Goals
-
Documentation shall be always up-to-date
-
… TBD
1.5. Stakeholders
Role/Name | Contact | Expectations |
---|---|---|
Product Owner |
||
User |
A person who wants to execute scans by SecHub. |
|
Administrator |
A person who installs SecHub server and does maintenance of
target security products. Also responsible for onboarding of
projects and users. |
|
External Systems |
Another system which will call the REST API or the SecHub client. E.g. Build Servers like Jenkins. |
2. Architecture Constraints
2.1. About
2.1.1. Content
Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.
2.1.2. Motivation
Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.
2.1.3. Form
Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)
2.2. Domain communication
Direct communication between different domains may not appear - to avoid the "big ball of mud", even when we have no real micro-service landscape at the moment and SecHub is a self-contained-system.
For more information please refer to Domain Driven Design
2.2.1. DB constraints
As long as there is no really need there will be only ONE database instance across the SecHub system!!!!!
Even when the spring boot application is a single one and shares a database every domain has only access to dedicated tables and does not share its tables across other domains! This includes relation ships between tables as well.
This is to prevent the database becoming part of a "hidden shared kernel" /"central bottleneck". If we decide to
transform sechub-server
from self-contained-system into single separate deployment units we can achieve this without too
much effort/impact.
Domain | Table | Description |
---|---|---|
SCHEDULE |
SCHEDULE_SECHUBJOB |
Represents a SecHub Job instance |
SCAN |
SCAN_RESULT |
Contains the collected scan result from all scan product. Shall represent entity ScanResult |
SCAN |
SCAN_DATA |
Does contain (intermediate) information from job scans etc. |
… |
… |
… |
For more information please refer to Domain Driven Design
3. System Scope and Context
3.1. About
3.1.1. Content
System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).
3.1.2. Motivation
The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.
3.2. Business Context
3.2.1. Overview
3.3. Technical Context
3.3.1. Web scanner
A scanner used for automated penetration testing on given sites
We support currently:
-
Netsparker
3.3.2. Code scanner
A scanner used for automated static code analysis
We support currently:
-
Checkmarx
3.3.3. Infrastructure scanner
A scanner used for automated penetration testing on given infrastructure
We support currently:
-
Nessus
We got the problem that Nessus has terminated their REST API and only supports a REST API when ordering another product. So currently it’s difficulat to support NESSUS directly. |
4. Solution Strategy
4.1. About
4.1.1. Contents
A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture. These include
-
technology decisions
-
decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
-
decisions on how to achieve key quality goals
-
relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.
4.1.2. Motivation
These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules.
4.1.3. Form
Keep the explanation of these key decisions short.
Motivate what you have decided and why you decided that way, based upon your problem statement, the quality goals and key constraints.
4.1.4. Solutions
Quality Goal | Scenario | Solution approach | Link to details |
---|---|---|---|
Server development shall be easy to maintain and developers shall have experience with the language and frameworks |
All |
Spring Boot, Java |
|
Users shall have a convenient and simple way to start scans |
All |
We provide not only a REST API but provide a convenient CLI client which just needs a JSON config file |
|
Client shall be small, fast and usable on many platforms without much effort to install |
All |
Go client |
|
Developers shall be able to test and develop server parts without an existing infrastructure (means no security products installed etc) |
Development |
Mock profile and also Mocked Adapters for every supported product |
|
Developers shall be able to write adapters without starting server |
Development |
Adapters are "dumb" and can be started as simple java application. |
|
For corporate continous-integration scans we need a scalable solution which can be clustered |
Cluster installation |
With SpringBoot and DDD we ensure we can run server components inside Kubernetes |
|
People or smaller companies shall be able to install SecHub without Kubernetes |
Single installation |
Server software will be always startable as a simple jar as well (done by Spring Boot Jar) |
|
Developers shall be able to start SecHub without Kubernetes |
Development |
Server software will be always startable as a simple jar as well (done by Spring Boot Jar) |
|
SecHub sserver integration tests shall be possible without available products, PostgreSQL or Kubernetes |
Development |
Server software will be always startable as a simple jar as well (done by Spring Boot Jar), we provide also different profiles for normal database (postgres) and in memory DB (h2), we provide a profile for mocked products |
|
We need a reliable database which is mature, stable and good documented |
Cluster installation, Single installation, Development |
We will provide postgres |
|
We must avoid "big ball of mud" in development and also be able to separate server parts to smaller deployments easily in future (when needed) |
Development |
Domain driven design is choosen to support this. On the other side we do not want to have
a large event bus system (e.g. |
see |
We want to have many integration tests which are easy to read, maintain, make fun to write,
have reduced test code and using server nearly as done in production. |
Development |
We implement a specialized integration-test framework which provides
a DSL like, fluent API which is able to test again a running test server instance. We implement
spring profiles for |
|
We want to have an agile, living documentation, which is matching to source code and a diff can be easily done by GIT |
Development |
We use AsciiDoc and checkin documenteation together inside one GIT repository |
see https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ |
We want to have a way to provide special scan configurations in a dynamic way |
Deployment |
We provide a JSON based scan configuration where different provider meta information can be defined. Dedicated providers can use this information and handle dynamic configuration - e.g. based on name of SecHub project. |
see https://github.com/mercedes-benz/sechub/issues/127 , |
5. About
5.1. Content
The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, datas structures, …) as well as their dependencies (relationships, associations, …)
This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.
5.2. Motivation
Maintain an overview of your source code by making its structure understandable through abstraction.
This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.
5.3. Form
The building block view is a hierarchial collection of black boxes and white boxes and their descriptions.
6. Building Block View
6.1. SecHub Overall System
Overview Diagram
7. Runtime View
7.1. About
7.2. Content
The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:
-
important use cases or features: how do building blocks execute them?
-
interactions at critical external interfaces: how do building blocks cooperate with users and neighbouring systems?
-
operation and administration: launch, start-up, stop
-
error and exception scenarios
The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevancy. It is not important to describe a large number of scenarios. You should rather document a representative selection. |
7.3. Motivation
You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakholders that are less willing or able to read and understand the static models (building block view, deployment view).
7.4. Form
There are many notations for describing scenarios, e.g.
-
numbered list of steps (in natural language)
-
activity diagrams or flow charts
-
sequence diagrams
-
BPMN or EPCs (event process chains)
-
state machines
-
…
7.5. Use cases
7.5.1. Overview about usecase groups
7.5.1.1. Anonymous
All these usecases handling anonymous access.
7.5.1.2. User administration
Usecases handling administration of users
7.5.1.3. Project administration
Usecases for project administration
7.5.1.4. User profile
User actions belonging to their profiles
7.5.1.5. Sechub execution
Execution of SecHub -either by CLI or direct with REST api call
7.5.1.6. Sign up
All these usecases are handling user sign up (part of user self registration process)
7.5.1.7. Job administration
Usecases about job administration
7.5.1.8. Technical
Usecases about technical operations being executed by sechub itself
7.5.1.9. Testing
Some use cases for testing
7.5.1.10. Configuration
Usecases for configuration parts
7.5.1.11. Encryption
Usecases for encryption parts
7.5.1.12. Other
All other use cases
7.5.2. UC_001-User self registration
The self registration can be done by anonymous
users.
If a user is not already inside the system and there exists not already a self registration the signup is persisted.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest API call |
2 |
Rest api called to register user. Normally done by user itself |
|
2 |
Persistence |
3 |
Valid self registration input will be persisted to database. |
|
3 |
Email to user |
4 |
A notification is send per email to user that a new user signup has been created and waits for acceptance. |
|
4 |
Email to admin |
A notification is send per email to admins that a new user signup has been created and waits for acceptance. |
7.5.3. UC_002-Admin lists open user signups
In this usecase the administrator will list the currently unapplied user self registrations/signups.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
All self registrations are returned as json |
7.5.4. UC_003-Admin applies self registration
In this usecase the administrator will accept the self registration done by an user.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator accepts a persisted self registration entry by calling rest api |
2 |
Create user and send events |
SUPERADMIN |
3, 4 |
The service will create the user a one time token for api token generation and triggers asynchronous events. It will also remove the existing user signup because no longer necessary. |
3 |
Email to user |
A notification is send per email to user that a new api token was requested. The mail contains a link for getting the secure API token |
||
4 |
Give user access |
Authorization layer is informed about new user and gives access to sechub. But without any project information |
7.5.5. UC_004-Admin lists all users
An administrator downloads a json file containing all user ids
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
All userids of sechub users are returned as json |
2 |
Service call |
SUPERADMIN |
All userids of sechub users are returned as json |
7.5.6. UC_005-User creates a new sechub job
A user wants to create a new sechub job.
This will not directly start the job. Please refer to User approves job. |
As a result the user will have created a new SecHub
job and have a job UUID as result.
After this the user is able to
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Persistence and result |
Persist a new job entry and return Job UUID |
7.5.7. UC_006-User uploads source code
A user wants to upload sourcecode for a former created sechub job.
The source code must be a valid zipfile.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find project and upload sourcecode as zipfile |
USER |
When project is found and user has access and job is initializing the sourcecode file will be uploaded |
7.5.8. UC_007-User approves sechub job
A user wants to approve a former created sechub job.
This means the user has done all necessary preparations - e.g. uploading source code for code scanning - and wants the job marked as ready for execution
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find job annd update execution state |
When job is found and user has access job will be marked as ready for execution |
7.5.9. UC_008-Sechub scheduler starts job
Scheduler service starts next SchedulerJob
. Before a user has only created and approved a job which was lead only to database persistence of JobData.
The work itself is triggered/executed here by asynchronous batch operation.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Fetches next schedule job from queue and trigger execution. |
|
2 |
Execution |
3, 4 |
Triggers job execution - done parallel, but with synchronous domain communication (to wait for result). |
|
4 |
Store admin job info |
5 |
Fetches event about started job and store info in admin domain. |
|
5 |
Update admin job info |
Deletes store info in admin domain when job is done. |
7.5.10. UC_009-User checks sechub job state
User wants to get the state of the current running job.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find project and fail or return job status |
7.5.11. UC_010-User downloads sechub job report
A user wants to download a SecHub
report for an executed job
by its given job UUID.
The report standard format is a human and machine readable JSON format. Additionally, there is the option to download the report as HTML file.
Both, the HTML and the JSON file have a reduced view of the scan results. Code snippets etc. can be found on the real security products.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get JSON report |
SUPERADMIN, USER |
3 |
|
2 |
REST API call to get HTML report |
SUPERADMIN, USER |
3 |
|
3 |
Resolve scan report result |
7.5.12. UC_011-User starts scan by client
Sechub has got it’s own client, written in go. The client is available for Linux and Windows and can be downloaded at https://github.com/mercedes-benz/sechub .
The client encapsulated and simplifies the necessary steps to do a scan to one single step only
It does automate following usecases:
If the scan report traffic light is RED the build client will return an System exit code greater than zero so build will break.
More information about the client can be found inside the user documentation.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
create new job |
SUPERADMIN, USER |
2, 3 |
|
2 |
upload sourcecode |
SUPERADMIN, USER |
2 |
|
2 |
upload binaries |
SUPERADMIN, USER |
3 |
|
3 |
approve job |
SUPERADMIN, USER |
4 |
|
4 |
download job report and traffic light |
SUPERADMIN, USER |
4 |
|
4 |
get job status |
SUPERADMIN, USER |
7.5.13. UC_012-User clicks link to get new api token
The user has to open the received email and click there on the contained link with a onetimetoken api which is another usecase.
This use case is either triggered by when a new user was initial registered or a new API token was requested by user.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
2 |
User opens url by browser |
|
2 |
Validation and update |
3, 4 |
When its a valid one time token a new api token is generated and persisted hashed to user. The token itself is returned. When not valid an emtpy string is the result … |
|
3 |
Update auth data |
|||
4 |
Inform user about api token change done |
7.5.14. UC_013-Admin creates a project
Administrator creates a project inside SecHub
.
A Project is the main entry point for every SecHub
operation!
For example a user must have a project assigned to be able to scan on it!
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator creates a new project by calling rest api |
2 |
Create project |
SUPERADMIN |
The service will create the project when not already existing with such name. |
7.5.15. UC_014-Admin lists all projects
An administrator downloads a json file containing all project ids
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
All project ids of sechub are returned as json |
7.5.16. UC_015-Admin assigns user to project
An administrator assigns an user to an existing sechub project.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator does call rest API to assign user |
2 |
Assign user |
SUPERADMIN |
2 |
The service will add the user to the project. If user does not have ROLE_USER it will obtain it |
2 |
Update schedule authorization parts |
3 |
||
3 |
Update scan authorization parts |
4 |
||
4 |
Roles changed in auth |
Authorization layer adds ROLE_USER |
7.5.17. UC_016-Admin unassigns user from project
An administrator unassigns an user from a sechub project.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator does call rest API to unassign user |
2 |
Unassign user |
SUPERADMIN |
2 |
The service will remove the user to the project. If users has no longer access to projects ROLE_USER will be removed |
2 |
Update authorization parts |
2 |
||
2 |
Update authorization parts |
4 |
||
4 |
Roles changed in auth |
Authorization layer removes ROLE_USER |
7.5.18. UC_017-Admin shows user details
An administrator downloads a json file containing json containing user details
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Json returned containing details about user and her/his projects |
2 |
Service fetches user details. |
SUPERADMIN |
The service will fetch user details for given user id |
7.5.19. UC_018-Admin deletes a user
An administrator deletes an user. All associations etc. are removed as well.
If the user is still a project owner the delete will not work and an error message will appear that this is not acceptable and that the ownership must be moved before User delete is possible. |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
User will be deleted |
2 |
Service deletes user. |
SUPERADMIN |
3, 4 |
The service will delete the user with dependencies and triggers asynchronous events |
3 |
revoke user from schedule access |
3 |
||
3 |
revoke user from schedule access |
4 |
||
4 |
Delete user access |
Authorization layer is informed about user deltete and removes access to sechub. But without any project information |
||
5 |
Inform user that the account has been deleted by administrator |
7.5.20. UC_019-Admin deletes user signup
In this usecase the administrator will not accept the self registration done by an user but delete the entry.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest API call |
SUPERADMIN |
2 |
Rest api called to remove user signup |
2 |
Persistence |
SUPERADMIN |
Existing signup will be deleted |
7.5.21. UC_020-Admin deletes a project
Administrator deletes a project from SecHub
.
A Project is the main entry point for every SecHub
operation and deleting this will result in:
-
Terminate all running jobs for this project
-
Remove project administration setup
-
User to project association
-
All existing project report results
Albert Tregnaghi, 2018-08-03: This is currently not full implemented! |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Project will be deleted |
2 |
Service deletes projects. |
SUPERADMIN |
3, 4, 5, 6, 7 |
The service will delete the project with dependencies and triggers asynchronous events |
3 |
Inform sechub admins that project has been deleted |
4 |
||
4 |
Inform project owner that the project has been deleted |
5 |
||
5 |
Inform users that the project has been deleted |
6 |
||
6 |
Update authorization parts - remove entries for deleted project |
7 |
||
7 |
revoke any scan access from project |
8 |
||
8 |
delete all project scan data |
7.5.22. UC_021-Admin shows project details
An administrator downloads a json file containing json with project details
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Json returned containing details about project |
2 |
Service fetches project details. |
SUPERADMIN |
The service will fetch project details |
7.5.23. UC_022-Update project whitelist
Administrator creates a project inside SecHub
.
A Project is the main entry point for every SecHub
operation!
For example a user must have a project assigned to be able to scan on it!
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
White list will be updated |
2 |
Update project |
SUPERADMIN |
The service will update the Project whitelist. |
7.5.24. UC_023-Admin lists all running jobs
Administrator lists all running jobs inside SecHub
.
The list entries do contain
-
jobUUID
-
project id
-
owner of job (id of user who executed job)
-
status
-
since time stamp
-
configuration
These entries are only available at running jobs
This is an important action to get info about current treshold in sechub.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator lists all running jobs by calling rest api |
2 |
Fetchjob information from database |
Fetches stored job information from administration database. |
7.5.25. UC_024-User requests new API token
It shall be possible to achieve this by calling REST API and also by just visiting static sechub website and entering email address and post request by simple web form.
When user exists a new one time token will be created and sent to user per email - so same way as done when a new user signup is accepted by admin.
The user has to open the received email.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest API call |
Rest api called to request new user api token. Normally done by user itself |
7.5.26. UC_025-Admin shows scan logs for project
An admin downloads a json file containing log for scans of project
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get JSON list |
SUPERADMIN |
2 |
7.5.27. UC_026-Admin downloads all details about a scan job
An administrator downloads a ZIP file containing full details of a scan. Main reason for this use case is for debugging when there are problems with security products. Another reason is for developers to adopt new security products easier.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to zip file containing full scan data |
SUPERADMIN |
2 |
|
2 |
Collect all scan data |
SUPERADMIN |
7.5.28. UC_027-Admin grants admin rights to user
An administrator grants admin rights to another user. So this user will become also an administrator.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
User will be granted admin rights |
2 |
Service grants user admin rights. |
SUPERADMIN |
3, 4 |
The service will grant user admin rights and triggers asynchronous events |
3 |
Inform user that he/she became administrator |
4 |
||
4 |
Inform SecHub admins that another user became administrator |
7.5.29. UC_028-Admin revokes admin rights from an admin
An administrator revokes existing admin rights from another administrator.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Admin rights will be revoked from admin |
2 |
Service revokes user admin rights. |
SUPERADMIN |
3, 4 |
The service will revoke user admin righs and triggers asynchronous events |
3 |
Inform user about loosing administrator rights |
4 |
||
4 |
Inform SecHub admins that another admin is no longer admin |
7.5.30. UC_029-Admin lists all admins
An administrator downloads a json file containing all names of SecHub admins
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
All userids of sechub administrators are returned as json |
2 |
Service call |
SUPERADMIN |
All userids of sechub administrators are returned as json |
7.5.31. UC_030-Admin disables job processing in scheduler
An administrator disables scheduler job processing. This can be a preparation for system wide update - when scheduling is stoped, user can ask for new SecHub Jobs etc. But as long as scheduler is stopped nothing is executed - so JVMs/PODs can be updated in cluster
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator wants to stop (pause) scheduler job processing |
2 |
Service call |
SUPERADMIN |
2 |
Sends request to scheduler to send updates about current status. |
2 |
Service call |
SUPERADMIN |
3 |
Sends request to scheduler domain to disable scheduler job processing |
3 |
Disable processing |
4 |
Disables job processing inside scheduler database |
|
4 |
Inform SecHub admins that scheduler job processing has been disabled |
7.5.32. UC_031-Admin enables scheduler job processing
An administrator starts scheduler job processing. This can be a necessary step after a system wide update where processing of jobs was stoped before.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator wants to start (unpause) scheduler job processing |
2 |
Service call |
SUPERADMIN |
3 |
Sends request to scheduler domain to enable scheduler job processing |
3 |
Enable processing |
4 |
Enables job processing inside scheduler database |
|
4 |
Inform SecHub admins that scheduler job processing has been enabled |
7.5.33. UC_032-Admin get scheduler status
An administrator wants to update information about scheduler status
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
Administrator wants to trigger a refresh of scheduler status. Will update information about running, waiting and all jobs in scheduler etc. etc. |
7.5.34. UC_033-Admin lists status information
An administrator fetches current known status information about sechub
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
Administrator wants to list status information about sechub |
7.5.35. UC_034-Admin cancels a job
Administrator does cancel a job by its Job UUID
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Triggers job cancellation request, owners of project will be informed |
2 |
Cancel job |
3 |
Will trigger event that job cancel requested |
|
3 |
Try to find job and mark as being canceled |
4 |
When job is found and user has access the state will be updated and marked as canceled |
|
4 |
Inform user that her/his job has been canceled |
7.5.36. UC_035-User defines mock data configuration for project
User retrieves project mockdata - see define project mockdata
SecHub must be started with |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to define mock configuration byJSON data |
SUPERADMIN, USER |
2 |
|
2 |
Service call to store mock configuration |
7.5.37. UC_036-User retrieves mock data configuration for project
When other systems integrate sechub into their live cylce (this means not a build server integration,
but an integration from another product…)
they also want to integrate into their integration tests as well - so a special environment is
necessary an INT environment
.
When using commercial security products it can happen that integration tests will lead to additional
license costs. To prevent this the INT environment
can be setup to use mocked adapters. These
adapters will not communicate with the real security products but instead return mocked product
results. All logic, every behaviour inside SecHub is exactly the same except the communication with
the security product. This technique is used by SecHub for integration testing itself.
SecHub must be started with |
Tests/Testers have the possibility to setup wanted traffic-light
result on their SecHub
projects by REST API.
-
green will contain only green results,
-
yellow shall contain green and yellow results and
-
red will contain green, yellow and red ones.
{
"codeScan" : {
"result" : "RED"
},
"webScan" : {
"result" : "YELLOW"
},
"infraScan" : {
"result" : "GREEN"
}
}
Of course you can reduce mock to wanted parts only:
{
"codeScan" : {
"result" : "YELLOW"
}
}
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get JSON data |
SUPERADMIN, USER |
2 |
|
2 |
Service call to get JSON data |
7.5.38. UC_037-Admin updates mapping configuration
An administrator changes mapping configuration. Mappings represents a generic mechanism to replace a given string, matched by configured regular expression pattern with a replacement string. Some of the mappings are used for adapter behaviour.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator wants to update a mapping configuration |
2 |
Service call |
3 |
Services updates data in database and sends event |
|
3 |
Event handler |
4 |
Receives mapping configuration change event |
|
4 |
Service call |
5 |
Updates scan mapping in DB |
|
5 |
Trigger service |
6 |
Checks periodically for updates in scan configuration |
|
6 |
Service call |
Checks if current mappings in DB lead to a new scan configuration. |
7.5.39. UC_038-Admin fetches mapping configuration
An administrator fetches mapping configuration by its ID.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator wants to fetch a mapping configuration |
2 |
Service call |
Services fetches data from database, if not set an empty mapping data result will be returned |
7.5.40. UC_039-Check if the server is alive and running.
An anonymous user or system wants to know if the server is alive and running.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call |
An anonymous user checks if the server is alive and running using the REST API |
7.5.41. UC_040-Admin fetches server runtime data
An administrator fetches the current SecHub server runtime data. Only administrators are allowed to do this because it contains the server version and knowing the exact server version makes it easier for penetration tester or attacker to attack the system.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API Call |
SUPERADMIN |
Administrator wants to fetch server runtime data. This data contains for example the server version |
7.5.42. UC_041-Admin restarts a job
Administrator restarts job
When a JVM
(or POD
) crashes with running SecHub job, the job process execution has been
terminated without resetting the scheduler state.
If this has happened, somebody or a build server who/which is waiting for sechub job result will wait infinite and without hope of having a status refresh.
So the admin must be able to restart a job.
The restart will be intransparent for end user so they will just keep on waiting but get the result as soon as possible. |
The restart will
-
first of all write an audit log enry
-
be canceled, when job does not exist in scheduler
-
be canceled, when execution already finished
-
check for running batch jobs with SecHub job UUID.
If there are existing batch operations, those will be stopped -
new scan will be restarted immediately without scheduling, will try to reuse existing results
E.g. when a static code scan job is triggered to a product and scan ID is wellknown, no new scan will be started, but state of this scan is refetched by the ID, etc. etc. But exact resilience behaviour depends on adapter implementation
Event overview - variant: accidently restart because job has already finished
Event overview - variant: crashed jvm with product result
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Triggeres job restart (soft) |
2 |
Restart job |
3 |
Will trigger event that job restart (soft) requested |
|
3 |
Inform sechub admins when job restart was canceled |
4 |
||
4 |
Inform sechub admins when job has been restarted |
5 |
||
5 |
Inform sechub admins when job results have been purged |
7.5.43. UC_042-Admin restarts a job (hard)
Administrator restarts job the hard way , means it is possible to restart a running (not finished) job and destroy all former results.
It is very similar to related use case admin restarts job, but with difference that all former product results and also adapter meta data is removed. |
We do NOT allow restarts of former finished jobs because finalization does destroy interim data - e.g. uploaded source code etc. - and is no longer restartable. Also we cannot ensure that a client has not already downloaded the existing results, so we we keep them as is! The term "hard" is only because we destroy former meta data and product results! So the restart is like from "scratch". |
The restart will
-
first of all write an audit log enry
-
be canceled, when job does not exist in scheduler
-
be canceled, when execution already finished
-
delete all former product results and also adapter meta data
-
check for running batch jobs with SecHub job UUID.
If there are existing batch operations, those will be stopped -
new scan will be restarted immediately without scheduling, will not try to reuse existing results because such information was formerly deleted
Event overview - variant: accidently restart because job has already finished
Event overview - variant: crashed jvm with product result
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Triggeres job restart (hard) |
2 |
Restart job |
3 |
Will trigger event that job restart (hard) requested |
|
3 |
Inform sechub admins when job restart was canceled |
3 |
||
3 |
Try to restart job |
3 |
When job is found and job is not already finsihed, a restart will be triggered. Existing batch jobs will be terminated |
|
3 |
Try to rstart job (hard) |
4 |
When job is found, a restart will be triggered. Existing batch jobs will be terminated |
|
4 |
Inform sechub admins when job has been restarted |
5 |
||
5 |
Inform sechub admins when job results have been purged |
7.5.44. UC_043-Admin receives notification about start of a new scheduler instance
Administrators receive notification about start of a new scheduler instance.
The notification will contain also information about potential zombie jobs - just show all started but not finished jobs before scheduler start.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
send domain message that new scheduler instance has been started and information about potential zombie jobs |
2 |
||
2 |
Inform sechub admins that new scheduler job has been started |
7.5.45. UC_044-User marks false positives
A user wants to mark false positives either for a finished job or with project data not necessarily connected to a finished job.
To mark false positives using job data the job must have been executed, finished without failure and job NOT been deleted. The user will be able to mark former job results by their given id as false positives.
To mark false positives using project data no job must have been run, but it will help identify findings as false positives of course. The project data are not related to any job information.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to define false positives by JSON data containing identifiers for existing jobs or false positive project data |
SUPERADMIN, USER |
7.5.46. UC_045-User unmarks existing false positive definitons
A user wants to unmark existing false positives This means the false positives has been marked before.
This will NOT change any former job report where the false positive to unmark has been filtered! |
After next scan job the former false positive is no longer filtering the finding.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to remove existing false positive definition |
SUPERADMIN, USER |
7.5.47. UC_046-User fetches false positive configuration of project
A user wants to fetch false positive configuration of project.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to fetch existing false positive configuration of project |
SUPERADMIN, USER |
7.5.48. UC_047-Admin creates an executor configuration
An administrator creates an executor a new configuration entry.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator adds a new product executor configuration by calling REST API |
2 |
Service call |
SUPERADMIN |
Service creates a new product executor configuration |
7.5.49. UC_048-Admin deletes executor configuration
An administrator deletes an executor by removing the configuration entry identified by its uuid
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator deletes an existing product executor configuration by calling REST API |
2 |
Service call |
SUPERADMIN |
Service deletes an existing product executor configuration by its UUID |
7.5.50. UC_049-Admin fetches executor configuration list
An administrator fetches executor configuration list which contains all executor configurations
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator fetches list of existing product executor configurations by calling REST API, will not contain setup information |
2 |
Service call |
SUPERADMIN |
Service fetches data and creates a list containing all executor configurations |
7.5.51. UC_050-Admin fetches executor configuration
An administrator fetches one explicit executor configuration by its uuid.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator fetches setup of an existing product executor configuration by calling REST API |
2 |
Service call |
SUPERADMIN |
Service reads setup information for an existing product executor configuration |
7.5.52. UC_051-Admin updates executor configuration setup
An administrator updateds dedicated executor configuration. The update does change description, enabled state and also used executors, but Will NOT change any associations between profile and projects.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator updates setup for an existing product executor configuration by calling REST API |
2 |
Service call |
SUPERADMIN |
2 |
Service updates existing executor configuration |
2 |
Service call |
SUPERADMIN |
Service updates existing executor configuration |
7.5.53. UC_052-Admin creates an execution profile
An administrator creates an execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator adds a new product execution profile by calling REST API |
2 |
Service call |
SUPERADMIN |
Service creates a new product executor configuration |
7.5.54. UC_053-Admin deletes execution profile
An administrator deletes execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator deletes an existing product execution profile by calling REST API |
2 |
Service call |
SUPERADMIN |
Service deletes an existing product execution profile by its profile id |
7.5.55. UC_054-Admin updates execution profile
An administrator updateds dedicated execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
Administrator updates existing profile by calling REST API |
7.5.56. UC_055-Admin fetches execution profile
An administrator fetches details about an execution profile
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator fetches setup of an existing product executor configuration by calling REST API |
2 |
Service call |
SUPERADMIN |
Service reads setup information for an existing product executor configuration |
7.5.57. UC_056-Admin fetches execution profile list
An administrator fetches execution profile list
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator fetches lsit of all available execution profiles by calling REST API |
2 |
Service call |
SUPERADMIN |
Service fetches data and creates a list containing all executor profiles |
7.5.58. UC_057-Admin assigns execution profile to project
An administrator assigns an execution profile to an existing project
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator adds profile relation to project by calling REST API |
2 |
Service call |
SUPERADMIN |
Services creates a new association between project id and profile |
7.5.59. UC_058-Admin unassigns execution profile from project
An administrator unassigns an execution profile from a projects.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator removes profile relation to project by calling REST API |
2 |
Service call |
SUPERADMIN |
Services deletes an existing association between project id and profile |
7.5.60. UC_059-Update project metadata
Administrator updates project meta data inside SecHub
.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
MetaData will be updated |
2 |
Update project |
SUPERADMIN |
The service will update the Project metadata. |
7.5.61. UC_060-Admin changes owner of a project
An administrator changes the owner of an existing sechub project.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator does call rest API to set new project owner |
2 |
Change project owner |
SUPERADMIN |
4 |
The service will set the user as the owner of the project. If user does not have ROLE_OWNER it will obtain it. The old owner will loose project ownership. |
4 |
Inform new and previous project owners that the project owner ship has changed |
7.5.62. UC_061-Admin changes project description
An administrator changes the project description
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Changes project description. Json returned containing details about changed project |
2 |
Service changes project description. |
SUPERADMIN |
The service will change project description. |
7.5.63. UC_062-Admin changes project access level
An administrator is able to change the access level of a project.
Project access levels do constraint possible user operations for a project - e.g. restrict to read only operations. The details of different restrictions are described below.
A project access level none will make it also for administrators
impossible to fetch reports from the project. Only
special administrator REST API calls are not restricted.
|
7.5.63.1. Levels
-
full
no restrictions -
read_only
users can download their reports, get job status, but cannot trigger any project jobs -
none
users have no access to reports, jobs and cannot trigger any jobs for the project
7.5.63.2. Conststraints
7.5.63.2.1. Full
When a project has access level full
any read or write user operation
is possible:
-
a new scan can be triggered, so user can
-
create job
-
approve job
-
upload job data
-
-
scheduling is active for the project new jobs are processed
-
user can check status for a job in their project
-
user can download their former reports
7.5.63.2.2. Read only
When a project has access level read_only
only read user operations
are possible:
-
a new scan is not possible, HTTP 403: Forbidden will be sent for
-
create job
-
approve job
-
upload job data
-
-
running jobs are still running
-
already scheduled jobs will be scheduled
-
user are still able to check status for a job in their project
-
user can still download their former reports
7.5.63.2.3. None
When a project has access level none
no user operation is possible:
-
a new scan is not possible, HTTP 403: Forbidden will be sent for
-
create job
-
approve job
-
upload job data
-
-
running jobs are still running
-
already scheduled jobs will be scheduled
-
user are NOT able to check status for a job in their project, HTTP 403: Forbidden will be sent
-
user can NOT download their former reports, HTTP 403: Forbidden will be sent
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Admin does call REST API to change project access level |
2 |
Change access level |
SUPERADMIN |
3 |
The service will change the project access level inside administration domain and trigger a change event to inform recipients about the new situation. |
3 |
Event handler |
4 |
Receives change project access level event |
|
4 |
Event handler |
Receives change project access level event |
7.5.64. UC_063-Admin updates user email address
An administrator update the email address of an user. After the change an email will be sent to the old email-address to inform the user about the change. In addition, a new mail to the new email address will be sent as well.
When the new email address is the same as before, the action will be rejected. |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
User emaill address will be changed |
2 |
Service updates user email address. |
SUPERADMIN |
3 |
The service will update the user email address and also trigger events. |
3 |
Inform user that the email address has been changed |
7.5.65. UC_064-Admin fetches auto cleanup configuration
An administrator feches current auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator fetches auto cleanup configuration |
2 |
Fetches auto cleanup config |
Fetches auto cleanup configuration from database |
7.5.66. UC_065-Admin updates auto cleanup configuration
An administrator changes auto cleanup configuration.
Event overview
Involved messages |
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Administrator changes auto cleanup configuration |
2 |
Updates auto cleanup config |
3, 4, 5 |
Updates auto cleanup configuration as JSON in database and sends event |
|
3 |
Administration domain receives auto cleanup event |
4 |
Received event in administration domain about auto cleanup configuration change. Stores data, so available for next auto clean execution |
|
4 |
Schedule domain receives auto cleanup event |
5 |
Received event in schedule domain about auto cleanup configuration change. Stores data, so available for next auto clean execution |
|
5 |
Scan domain receives auto cleanup event |
Received event in scan domain about auto cleanup configuration change. Stores data, so available for next auto clean execution |
7.5.67. UC_066-Sechub administration domain auto cleanup
The administration domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Checks for parts to auto clean. |
|
2 |
Delete old data |
deletes old job information |
7.5.68. UC_067-Sechub scan domain auto cleanup
The scan domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Checks for parts to auto clean. |
|
2 |
Delete old data |
deletes old job information |
7.5.69. UC_068-Sechub schedule domain auto cleanup
The schedule domain does auto cleanup old data. This is done periodically. The time period is defined by auto cleanup configuration.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduling |
2 |
Checks for parts to auto clean. |
|
2 |
Delete old data |
3 |
deletes old job information |
|
3 |
Schedule cipher pool data cleanup |
Removes cipher pool data entries from database which are no longer used by any job |
7.5.70. UC_069-User uploads binaries
A user wants to upload binaries for a former created SecHub job.
The binaries must be inside a valid tar file.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Authenticated REST call |
SUPERADMIN, USER |
2 |
|
2 |
Try to find project and upload binaries as tar |
USER |
When project is found and user has access and job is initializing the binaries file will be uploaded |
7.5.71. UC_070-User downloads job report in SPDX format
A user wants to download a SPDX report for a finished SecHub
job
using the job UUID.
Only SPDX JSON is supported.
In case, there is no SPDX JSON result for a given job an error will be thrown.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to get SPDX JSON report |
SUPERADMIN, USER |
7.5.72. UC_071-User lists jobs for project
User fetches a list containing information about jobs of a SecHub project. Per default only the last created job is returned, but it is possible to define a limit and fetch more than one. In this case the returned entries are ordered by creation date.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
get pageable list of jobs in project |
SUPERADMIN, USER |
2 |
|
2 |
Assert access by service and fetch job information for user |
7.5.73. UC_072-Admin shows user details for email address
An administrator fetches user details for an email address.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Json returned containing details about user and her/his projects |
2 |
Service fetches user details. |
SUPERADMIN |
The service will fetch user details for given user email address |
7.5.74. UC_073-Admin starts encryption rotation
An administrator starts encryption rotation.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
2 |
Admin triggers rotation of encryption via REST |
2 |
Service call |
3 |
Triggers rotation of encryption via domain message |
|
3 |
Service call |
4 |
Forces new cipher pool entry creation and triggers encryption service pool refresh |
|
4 |
Service call |
5 |
Creates new cipher pool entry in database in own transaction |
|
5 |
Refresh encryption pool |
6 |
Encryption pool is refreshed (necessary because pool changed before this method call) |
|
6 |
Update encrypted data |
Encrypted data is updated (a direct pool refresh was triggered by admin action) |
7.5.75. UC_074-Scheduler encryption pool refresh
The scheduler refreshes its encryption pool data to handle new setup
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Init encryption pool |
3 |
Encryption pool is created on startup |
|
1 |
Encryption pool data refresh trigger |
2 |
Scheduler instance will check if encryption pool is in sync with the database definitions. If not, the instance will try to create new encryption pool object and provide the new setup. |
|
2 |
Refresh encryption pool |
3 |
Encryption pool is refreshed (if necessary) |
|
3 |
Update encrypted data |
Encrypted data is updated (all other cluster members) |
7.5.76. UC_075-Scheduler rotates data encryption
The scheduler checks for old encrypted data and will encrypt with latest cipher
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Update encrypted data |
Final update of encrypted job data. Will update all SecHub jobs having a pool id which is lower than latest from encryption pool |
7.5.77. UC_076-Admin fetches encryption status
An administrator fetches encryption status from all domains where encryption is used.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest call |
SUPERADMIN |
1 |
Admin fetches encryption status from domains via REST |
1 |
Service call |
Services collects encryption status from domains via event bus |
7.5.78. UC_077-SecHub does cleanup encryption
Secub does an ecnryption cleanup.
Inside relevant domains the encryption situation will be checked and old encryption setup, which is no longer necessary, will be dropped.
For example: When encryption was done with formerly via ENV variable
SECRET_1_AES_256
and the new one setup is using SECRET_2_AES_256
and
all jobs have been migrated to the new encryption, the cipher setup
using SECRET_1_AES_256
will become obsolete and will be automatically
removed. After the remove is done, there is no longer a need to
start the server with SECRET_1_AES_256
, but only with SECRET_2_AES_256
…
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Schedule cipher pool data cleanup |
Removes cipher pool data entries from database which are no longer used by any job |
7.5.79. UC_078-User unmarks existing false positive project data definitons
A user wants to unmark existing false positives This means the false positives has been marked before.
This will NOT change any former job report where the false positive to unmark has been filtered! |
After next scan job the former false positive is no longer filtering the finding.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
REST API call to remove existing false positive project data definition by id |
SUPERADMIN, USER |
7.5.80. UC_079-System suspends running jobs on SIGTERM
When a SecHub instance is receiving a SIGTERM signal from OS, the server instance must block further job processing (on this instance) and suspend all of its running jobs. Because after some time the job will be resumed by another instance, this process will not stop any running PDS jobs.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Scheduler terminates |
2 |
Scheduler instance is terminating. Will stop processing new jobs and inform job executor to suspend |
|
2 |
Scheduler job executor suspends current jobs |
3 |
Scheduler instance is terminating. Will mark current running jobs of this instance as SUSPENDED |
|
3 |
Scheduler job executor suspends current jobs |
4 |
Scheduler instance is terminating. Will mark current running jobs of this instance as SUSPENDED |
|
4 |
Scan job executor stops suspended jobs |
5 |
Scheduler instance has marked jobs as suspended. Will stop execution of scans of these jobs |
|
5 |
Scan job executable handles SUSPEND state |
6 |
Scan job executable stops execution because suspended |
|
6 |
Inform listeners |
7 |
Inform listeners about job suspension |
|
7 |
Administration handles suspended job |
Administration domain removes suspended job from its running job list |
7.5.81. UC_080-System resumes suspended jobs
SecHub jobs which have been suspended a minimum duration time will be restarted automatically.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Schedule suspended jobs |
2 |
Scheduler checks not only for new jobs but also for resumed ones. |
|
2 |
Resolve next job |
3 |
Resolves UUID of job which shall be executed at next time. If there is a suspended job and shall be resumed this job will be returned. Otherwise the selected schedule strategy will be used to determine next job uuid. Remark: A suspended job shall only be executed when the minium duration time has been reached. The time period can be configured and prevents side effects at deployments. |
|
3 |
Mark next job to execute |
4 |
When a suspended job is the next one, the job execution state will be changed to RESUMING |
|
4 |
Resume job |
The SecHub job will be resumed. This is done by triggering a soft restart request for the job. You can read Admin restarts a job for the steps which are
done at restart process. The steps are the same, except there is no audit logging
and the event is not triggered from |
7.5.82. UC_081-get assigned project data
User, Owner or Admin fetches a list containing information about assigned and/ or owned projects.
The Project data contains the following information:
-
Project ID
-
Owner
-
is owned
-
assigned users (can only be viewed by owner or admin)
A project user can see only projects he is assigned to. A project owner can see all projects he owns and the assigned users. A project admin can see assigned or owned projects and all assigned users.
Steps
Nr | Title | Role(s) | Next | Description |
---|---|---|---|---|
1 |
Rest API call to get Projects with information |
OWNER, SUPERADMIN, USER |
Rest api call to get projects with details |
7.6. Rest API documentation
7.6.1. Overview
7.6.1.1. Anonymous
All these usecases handling anonymous access.
7.6.1.2. User administration
Usecases handling administration of users
7.6.1.3. Project administration
Usecases for project administration
7.6.1.4. User profile
User actions belonging to their profiles
7.6.1.5. Sechub execution
Execution of SecHub -either by CLI or direct with REST api call
7.6.1.6. Sign up
All these usecases are handling user sign up (part of user self registration process)
7.6.1.7. Job administration
Usecases about job administration
7.6.1.8. Testing
Some use cases for testing
7.6.1.9. Configuration
Usecases for configuration parts
-
REST API for UC_049-Admin fetches executor configuration list
-
REST API for UC_051-Admin updates executor configuration setup
-
REST API for UC_057-Admin assigns execution profile to project
-
REST API for UC_058-Admin unassigns execution profile from project
-
REST API for UC_064-Admin fetches auto cleanup configuration
-
REST API for UC_065-Admin updates auto cleanup configuration
7.6.1.10. Encryption
Usecases for encryption parts
7.6.2. Check if the server is alive and running.
REST API for usecase UC_039-Check if the server is alive and running.
7.6.2.1. HEAD variant
Definition
Value | |
---|---|
Path |
/api/anonymous/check/alive |
Method |
HEAD |
Status code |
200 OK |
Example
Curl request
$ curl 'https://sechub.example.com/api/anonymous/check/alive' -i -X HEAD
Response body
(empty)
7.6.2.2. GET variant
Definition
Value | |
---|---|
Path |
/api/anonymous/check/alive |
Method |
GET |
Status code |
200 OK |
Example
Curl request
$ curl 'https://sechub.example.com/api/anonymous/check/alive' -i -X GET
Response body
(empty)
7.6.3. Admin lists all users
REST API for usecase UC_004-Admin lists all users
Definition
Value | |
---|---|
Path |
/api/admin/users |
Method |
GET |
Status code |
200 OK |
Response fields
Path | Type | Description |
---|---|---|
|
|
List of user Ids |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/users' -i -u 'user:secret' -X GET
Response body
["user1","user2","admin1"]
7.6.4. Admin assigns user to project
REST API for usecase UC_015-Admin assigns user to project
Definition
Value | |
---|---|
Path |
/api/admin/project/{projectId}/membership/{userId} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The 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/d997d479-f12b-4b26-9005-beb905c60f86' -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":"b2a0f621-cbed-431f-816d-f8f5a655e8bc","executedBy":"spartakus","started":"2024-11-26T09:48:46.447108027","ended":"2024-11-27T09:48:46.447126853","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. get assigned project data
REST API for usecase UC_081-get assigned project data
Definition
Value | |
---|---|
Path |
/api/projects |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Project ID |
|
|
Name of owner of the Project |
|
|
If caller is owner of the project |
|
|
Optional: Assigned users (only viewable by owner or admin) |
Example
Curl request
$ curl 'https://sechub.example.com/api/projects' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
[{"projectId":"project1","owner":"user1","assignedUsers":["user1","user2"],"isOwned":true}]
7.6.25. User clicks link to get new api token
REST API for usecase UC_012-User clicks link to get new api token
Definition
Value | |
---|---|
Path |
/api/anonymous/apitoken/{oneTimeToken} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
A one time token the user has got by a previous mail from sechub server |
Example
Curl request
$ curl 'https://sechub.example.com/api/anonymous/apitoken/oneTimeToken1' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.26. User creates a new sechub job
REST API for usecase UC_005-User creates a new sechub job
7.6.26.1. Code Scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Code scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Code scan sources from given file system folders |
|
|
Code scan sources from given file system files |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"codeScan":{"fileSystem":{"files":[],"folders":["testproject1/src/main/java","testproject2/src/main/java"]},"use":[]},"apiVersion":"1.0"}'
Response body
{"jobId":"7786c4a7-042f-4d2b-8bcf-6c23aabf6e7b"}
7.6.26.2. Code Scan using data section variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Code scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Unique reference name |
|
|
Sources from given file system folders |
|
|
Sources from given file system files |
|
|
Unique reference name |
|
|
Binaries from given file system folders |
|
|
Binaries from given file system files |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"codeScan":{"use":["source-ref-name","bin-ref-name"]},"data":{"sources":[{"fileSystem":{"files":["testproject1/src/other/example/php-example.php"],"folders":["testproject1/src/main/java","testproject2/src/main/java"]},"name":"source-ref-name"}],"binaries":[{"fileSystem":{"files":["testproject1/build/other/native.dll"],"folders":["testproject1/build/kotlin","testproject1/build/kotlin"]},"name":"bin-ref-name"}]},"apiVersion":"1.0"}'
Response body
{"jobId":"35ea98be-9e36-4cc6-8c8a-3a157d24ead7"}
7.6.26.3. Secret scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Secret scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Unique reference name |
|
|
Unique reference name |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"data":{"sources":[{"name":"source-ref-name"}],"binaries":[{"name":"bin-ref-name"}]},"secretScan":{"use":["source-ref-name","bin-ref-name"]},"apiVersion":"1.0"}'
Response body
{"jobId":"dc364126-fdc7-40a8-b8e7-ff087eb22bf2"}
7.6.26.4. License scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
License scan configuration block |
|
|
Referenced data configuration objects by their unique names |
|
|
Unique reference name |
|
|
Unique reference name |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"data":{"sources":[{"name":"source-ref-name"}],"binaries":[{"name":"bin-ref-name"}]},"licenseScan":{"use":["source-ref-name","bin-ref-name"]},"apiVersion":"1.0"}'
Response body
{"jobId":"7ff1f27b-bae9-4593-b4ee-5a5df3e52604"}
7.6.26.5. Infrastructure scan variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Infrastructure configuration block |
|
|
Infrastructure URIs to scan for |
|
|
Infrastructure IPs to scan for |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"infraScan":{"uris":["https://localhost"],"ips":["127.0.0.1"]},"apiVersion":"1.0"}'
Response body
{"jobId":"fcf8cb7f-4f7c-413a-9978-ce8a085fbc7f"}
7.6.26.6. Web scan anonymous variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Duration of the scan as integer |
|
|
Unit of the duration. Possible values are: millisecond(s), second(s), minute(s), hour(s), day(s) |
|
|
Include URL sub-paths to scan. Example: /hidden |
|
|
Exclude URL sub-paths to scan. Example: /admin |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"maxScanDuration":{"duration":1,"unit":"HOUR"},"url":"https://localhost/mywebapp/login","includes":["/admin","/hidden","/admin.html"],"excludes":["/public/media","/static","/contaxt.html"]},"apiVersion":"1.0"}'
Response body
{"jobId":"42566c19-7464-4f4a-95e6-79e722ae39b7"}
7.6.26.7. Web scan with api definition variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Type of the API definition files that will be provided |
|
|
Reference to the data section containing the API definition files. Always use 'sources' with 'files' instead 'folders'. |
|
|
Specifies an URL to read the API definition from. |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"api":{"type":"OPEN_API","apiDefinitionUrl":"https://www.example.org/api/v1/swagger/","use":["openApi-file-reference"]},"url":"https://www.example.org/"},"apiVersion":"1.0"}'
Response body
{"jobId":"1ad5cd3b-5a1e-4a7e-8b07-8d5bd87dd515"}
7.6.26.8. Web scan with client certificate definition variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Password the client certificate file is protected with |
|
|
Reference to the data section containing the client certificate definition file. Always use 'sources' with a single 'file' instead 'folders'. |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"url":"https://localhost/mywebapp","clientCertificate":{"password":"example-cert-password","use":["client-certificate-file-reference"]}},"apiVersion":"1.0"}'
Response body
{"jobId":"019ef25e-a21a-4c9e-9412-2ec55887f291"}
7.6.26.9. Web Scan login basic variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Webscan login definition |
|
|
Login URL |
|
|
basic login definition |
|
|
username |
|
|
password |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"login":{"url":"https://localhost/mywebapp/login","basic":{"user":"username1","password":"password1"}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'
Response body
{"jobId":"b7960f36-3dcd-4030-a4d1-fa8ba4f99462"}
7.6.26.10. Web Scan login form scripted variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
Webscan login definition |
|
|
Optional TOTP configuration as an additional authentication factor. |
|
|
The seed/secret for the TOTP generation. If TOTP is configured this parameter is mandatory. |
|
|
The time in seconds the generated TOTP is valid. In most cases nothing is specified and the default of '30' seconds is used. |
|
|
The length of the generated TOTP. In most cases nothing is specified and the default length '6' is used. |
|
|
The hash algorithm to generate the TOTP. In most cases nothing is specified and the default hash algorithm 'HMAC_SHA1' is used. Currently available values are: 'HMAC_SHA1', 'HMAC_SHA256', 'HMAC_SHA512' |
|
|
Login URL |
|
|
form login definition |
|
|
script |
|
|
action type: username, password, input, click, wait |
|
|
css selector |
|
|
value |
|
|
description |
|
|
the time unit to wait: millisecond, second, minute, hour, day. |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"login":{"url":"https://localhost/mywebapp/login","form":{"script":{"pages":[{"actions":[{"type":"USERNAME","selector":"#example_login_userid","value":"username1","description":"the username field"},{"type":"INPUT","selector":"#example_login_email_id","value":"user@example.com","description":"The email id field."}]},{"actions":[{"type":"WAIT","value":"2345","unit":"MILLISECOND"},{"type":"PASSWORD","selector":"#example_login_pwd","value":"Super$ecret234!"},{"type":"CLICK","selector":"#example_login_button"}]}]}},"totp":{"seed":"example-seed","validityInSeconds":30,"tokenLength":6,"hashAlgorithm":"HMAC_SHA1"}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'
Response body
{"jobId":"d70e8d78-f3c9-4d16-a57f-9f4957e4723a"}
7.6.26.11. Web Scan headers variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The unique id of the project id where a new sechub job shall be created |
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Webscan configuration block |
|
|
Webscan URI to scan for |
|
|
List of HTTP headers. Can be used for authentication or anything else. |
|
|
Name of the defined HTTP header. |
|
|
Value of the defined HTTP header. Either specify the header value directly here or reference a data section with 'use' e.g. if the value is to big, but never specify both. |
|
|
Reference to the data section containing a file with the value for this header, e.g if the value is to big for the sechub configuration. Always use 'sources' with a single 'file' instead 'folders'. |
|
|
Optional list of URLs this header shall be used for like: https://mywebapp.com/path/. Can contain wildcards like: https://mywebapp.com/path/<*>/with/wildcard |
|
|
Defines header masking. If 'true' the header value will be replaced with '**' inside the report, 'false' will show the value as is. Default is set to 'true'. |
Response fields
Path | Type | Description |
---|---|---|
|
|
A unique job id |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"webScan":{"url":"https://localhost/mywebapp","headers":[{"name":"api-token","value":"secret","onlyForUrls":["https://localhost/mywebapp/admin","https://localhost/mywebapp/<*>/profile","https://localhost/mywebapp/blog/<*>"],"sensitive":true,"use":["header-value-file-ref-for-big-tokens"]}]},"apiVersion":"1.0"}'
Response body
{"jobId":"67515a5b-1f33-4d6b-b432-1ed5ba525ee0"}
7.6.27. User uploads source code
REST API for usecase UC_006-User uploads source code
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID}/sourcecode |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where sourcecode shall be uploaded for |
|
The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub. |
Query parameters
Parameter | Description |
---|---|
|
A sha256 checksum for file upload validation |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job/24722135-2100-465e-bcef-4b1dfdae5ffd/sourcecode?checkSum=checkSumValue' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-F 'file=PK
�<M test1.txtPK ?
�<M $ test1.txt
��IW� ��IW� ��IW� PK [ ' '
Response body
(empty)
7.6.28. User approves sechub job
REST API for usecase UC_007-User approves sechub job
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID}/approve |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where sechub job shall be approved |
|
The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub. |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job/64b78b45-b45e-4c2c-8719-bd74688a0e63/approve' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.29. User checks sechub job state
REST API for usecase UC_009-User checks sechub job state
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where sechub job was started for |
|
The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub. |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The job uuid |
|
|
Creation timestamp of job |
|
|
Start timestamp of job execution |
|
|
End timestamp of job execution |
|
|
Owner / initiator of job |
|
|
State of job |
|
|
Result of job |
|
|
Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job/92179639-e089-4894-a4df-14f1e40e453d' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"jobUUID":"92179639-e089-4894-a4df-14f1e40e453d","owner":"CREATOR1","created":"","started":"2024-11-27T09:33:44.986322732","ended":"2024-11-27T09:48:44.986349833","state":"ENDED","result":"OK","trafficLight":"GREEN"}
7.6.30. User downloads sechub job report
REST API for usecase UC_010-User downloads sechub job report
7.6.30.1. JSON variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/report/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/report/9df5834d-4dc1-4a96-8995-926fcae88f9d' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
7.6.30.2. HTML variant
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/report/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/report/72362f49-ecbd-4ad6-9961-cacc3a8e11fa' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/xhtml+xml'
7.6.31. User marks false positives
REST API for usecase UC_044-User marks false positives
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positives |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The projectId of the project where users adds false positives for |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
The type of the json content. Currently only accepted value is 'falsePositiveDataList' but we also still accept the deprecated type 'falsePositiveJobDataList'. |
|
|
Job data list containing false positive setup based on former jobs |
|
|
SecHub job uuid where finding was |
|
|
SecHub finding identifier - identifies problem inside the job which shall be markeda as a false positive. |
|
|
A comment describing why this is a false positive |
|
|
Porject data list containing false positive setup for the project |
|
|
Identifier which is used to update or remove the respective false positive entry. |
|
|
A comment describing why this is a false positive. |
|
|
Defines a section for false positives which occur during webscans. |
|
|
Defines a url pattern for false positives which occur during webscans. Can be used with wildcards like '.host.com'. Each entry must contain more than just wildcards, '..' or '*' are not allowed. |
|
|
Defines a list of (HTTP) methods for false positives which occur during webscans. This is optional and if nothing is specified, the entry applies to all methods. |
|
|
Defines a CWE ID for false positives which occur during webscans. This is mandatory, but can be empty. If it is not specified it matches the findings with no CWE IDs. |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"apiVersion":"1.0","type":"falsePositiveDataList","jobData":[{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"an optional comment why this is a false positive..."}],"projectData":[{"id":"unique-identifier","webScan":{"cweId":564,"urlPattern":"https://*.example.com/api/*/search","methods":["GET","POST"]},"comment":"an optional comment for this false positive project entry"}]}'
Response body
(empty)
7.6.32. User unmarks existing false positive definitons
REST API for usecase UC_045-User unmarks existing false positive definitons
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positive/{jobUUID}/{findingId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
Job uuid |
|
Finding id - in combination with job UUID this defines the false positive to remove |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positive/f1d02a9d-5e1b-4f52-99e5-401854ccf936/42' -i -u 'user:secret' -X DELETE
Response body
(empty)
7.6.33. User fetches false positive configuration of project
REST API for usecase UC_046-User fetches false positive configuration of project
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positives |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Job data list containing false positive setup based on former jobs |
|
|
User id of author who created false positive |
|
|
Creation timestamp |
|
|
Meta data for this false positive |
|
|
Scan type - e.g. codeScan |
|
|
Name of origin finding marked as false positive |
|
|
CWE (common weakness enumeration). For code scans this is always set. |
|
|
CVE (common vulnerability and exposures). For infra scans this is always set. |
|
|
OWASP At least this field must be set for web scans when no cwe identifier is defined. |
|
|
Severity of origin report entry marked as false positive |
|
|
Code part. Only available for scan type 'codeScan' |
|
|
entry point |
|
|
location of code |
|
|
relevant part of source vulnerability |
|
|
source code |
|
|
end point (sink) |
|
|
location of code |
|
|
relevant part of source vulnerability |
|
|
source code |
|
|
Job data parts, can be used as key to identify false positives |
|
|
SecHub job uuid where finding was |
|
|
SecHub finding identifier - identifies problem inside the job which shall be markeda as a false positive. ATTENTION: at the moment only code scan false positive handling is supported. Infra and web scan findings will lead to a non accepted error! |
|
|
A comment from author describing why this was marked as a false positive |
|
|
Porject data list containing false positive setup for the project. |
|
|
Identifier which is used to update or remove the respective false positive entry. |
|
|
A comment describing why this is a false positive. |
|
|
Defines a section for false positives which occur during webscans. |
|
|
Defines a url pattern for false positives which occur during webscans. Can be used with wildcards like '.host.com'. Each entry must contain more than just wildcards, '..' or '*' are not allowed. |
|
|
Defines a list of (HTTP) methods for false positives which occur during webscans. This is optional and if nothing is specified, the entry applies to all methods. |
|
|
Defines a CWE ID for false positives which occur during webscans. This is mandatory, but can be empty. If it is not specified it matches the findings with no CWE IDs. |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X GET
Response body
{"falsePositives":[{"jobData":{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"Only used in documentation build not in deployment"},"author":"developer1","metaData":{"scanType":"codeScan","name":"Absolute Path Traversal","severity":"MEDIUM","code":{"start":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"args","sourceCode":"\tpublic static void main(String[] args) throws Exception {"},"end":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"File","sourceCode":"\t\tFile documentsGenFolder = new File(path);"}},"cweId":36},"projectData":{"id":"unique-identifier","webScan":{"cweId":564,"urlPattern":"https://*.example.com/api/*/search","methods":["GET","POST"]},"comment":"an optional comment for this false positive project entry"},"created":"2020-06-12 11:53:15"}]}
7.6.34. User uploads binaries
REST API for usecase UC_069-User uploads binaries
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/job/{jobUUID}/binaries |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project for which the binaries are uploaded for |
|
The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub. |
Request headers
Name | Description |
---|---|
|
The file size of the tar-archive to upload in bytes. Needs to be a positive integer value. |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/job/0fd0197f-f865-4068-90ac-fb4a8db4aa30/binaries' -i -X POST \
-H 'Content-Type: multipart/form-data;charset=UTF-8' \
-H 'x-file-size: 10240' \
-F 'file=test1.txt 0000664 0001750 0001750 00000000000 13353454574 012170 0 ustar albert albert ' \
-F 'checkSum=checkSumValue'
Response body
(empty)
7.6.35. User downloads job report in SPDX format
REST API for usecase UC_070-User downloads job report in SPDX format
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/report/spdx/{jobUUID} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project Id |
|
The job UUID |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/report/spdx/4500d9f1-4df9-413b-bf2f-dd2bc8c9ee09' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
7.6.36. User unmarks existing false positive project data definitons
REST API for usecase UC_078-User unmarks existing false positive project data definitons
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/false-positive/project-data/{id} |
Method |
DELETE |
Status code |
204 NO_CONTENT |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
Identifier which is used to remove the respective false positive entry. |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/false-positive/project-data/unique-identifier' -i -u 'user:secret' -X DELETE
Response body
(empty)
7.6.37. User self registration
REST API for usecase UC_001-User self registration
Definition
Value | |
---|---|
Path |
/api/anonymous/signup |
Method |
POST |
Status code |
200 OK |
Request fields
Path | Type | Description |
---|---|---|
|
|
The api version, currently only 1.0 is supported |
|
|
Wanted userid, the userid must be lowercase only! |
|
|
Email address |
Example
Curl request
$ curl 'https://sechub.example.com/api/anonymous/signup' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"apiVersion":"1.0","userId":"valid_userid","emailAddress":"valid_mailaddress@example.org"}'
Response body
(empty)
7.6.38. Admin lists open user signups
REST API for usecase UC_002-Admin lists open user signups
Definition
Value | |
---|---|
Path |
/api/admin/signups |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
List of user signups |
|
|
The user id |
|
|
The email address |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/signups' -i -u 'user:secret' -X GET
Response body
[{"userId":"johnsmith","emailAddress":"john.smith@example.com"},{"userId":"janesmith","emailAddress":"jane.smith@example.com"}]
7.6.39. Admin applies self registration
REST API for usecase UC_003-Admin applies self registration
Definition
Value | |
---|---|
Path |
/api/admin/signup/accept/{userId} |
Method |
POST |
Status code |
201 CREATED |
Path parameters
Parameter | Description |
---|---|
|
The userId of the signup which shall be accepted |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/signup/accept/user1' -i -u 'user:secret' -X POST
Response body
(empty)
7.6.40. Admin deletes user signup
REST API for usecase UC_019-Admin deletes user signup
Definition
Value | |
---|---|
Path |
/api/admin/signup/{userId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The userId of the signup which shall be deleted |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/signup/userId1' -i -u 'user:secret' -X DELETE
Response body
(empty)
7.6.41. User requests new API token
REST API for usecase UC_024-User requests new API token
Definition
Value | |
---|---|
Path |
/api/anonymous/refresh/apitoken/{emailAddress} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
Email address for user where api token shall be refreshed. |
Example
Curl request
$ curl 'https://sechub.example.com/api/anonymous/refresh/apitoken/emailAddress@example.com' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.42. Admin lists all running jobs
REST API for usecase UC_023-Admin lists all running jobs
Definition
Value | |
---|---|
Path |
/api/admin/jobs/running |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The uuid of the running job |
|
|
The name of the project the job is running for |
|
|
Owner of the job - means user which triggered it |
|
|
A status information |
|
|
Timestamp since when job has been started |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/running' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
[{"jobUUID":"a8503241-c02c-4722-afce-7a54eb0e7ea0","projectId":"project-name","owner":"owner-userid","status":"RUNNING","since":"2024-11-27T09:48:49.769371918"}]
7.6.43. Admin cancels a job
REST API for usecase UC_034-Admin cancels a job
Definition
Value | |
---|---|
Path |
/api/admin/jobs/cancel/{jobUUID} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/cancel/e520e1f5-60b5-45d0-abeb-d9267c54474b' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.44. Admin restarts a job
REST API for usecase UC_041-Admin restarts a job
Definition
Value | |
---|---|
Path |
/api/admin/jobs/restart/{jobUUID} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/restart/3c1f4235-016f-4246-bcfd-21531b315fe6' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.45. Admin restarts a job (hard)
REST API for usecase UC_042-Admin restarts a job (hard)
Definition
Value | |
---|---|
Path |
/api/admin/jobs/restart-hard/{jobUUID} |
Method |
POST |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The job UUID |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/jobs/restart-hard/e2e059a8-c340-4c1d-b68e-921fc0bd5c9c' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.46. User defines mock data configuration for project
REST API for usecase UC_035-User defines mock data configuration for project
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/mockdata |
Method |
PUT |
Status code |
200 OK |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/mockdata' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{"codeScan":{"result":"RED"},"webScan":{"result":"YELLOW"},"infraScan":{"result":"GREEN"}}'
Response body
(empty)
7.6.47. User retrieves mock data configuration for project
REST API for usecase UC_036-User retrieves mock data configuration for project
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/mockdata |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/mockdata' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Response body
{"codeScan":{"result":"RED"},"webScan":{"result":"YELLOW"},"infraScan":{"result":"GREEN"}}
7.6.48. Admin updates mapping configuration
REST API for usecase UC_037-Admin updates mapping configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/mapping/{mappingId} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The mappingID, identifiying which mapping shall be updated |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
Pattern |
|
|
Replacement |
|
|
Comment |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/mapping/checkmarx.newproject.teamid.mapping' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"entries":[{"pattern":"testproject_*","replacement":"8be4e3d4-6b53-4636-b65a-949a9ebdf6b9","comment":"testproject-team"},{"pattern":".*","replacement":"3be4e3d2-2b55-2336-b65a-949b9ebdf6b9","comment":"default-team"}]}'
Response body
(empty)
7.6.49. Admin fetches mapping configuration
REST API for usecase UC_038-Admin fetches mapping configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/mapping/{mappingId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The mapping Id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Pattern |
|
|
Replacement |
|
|
Comment |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/mapping/checkmarx.newproject.teamid.mapping' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"entries":[{"pattern":"testproject_*","replacement":"8be4e3d4-6b53-4636-b65a-949a9ebdf6b9","comment":"testproject-team"},{"pattern":".*","replacement":"3be4e3d2-2b55-2336-b65a-949b9ebdf6b9","comment":"default-team"}]}
7.6.50. Admin creates an executor configuration
REST API for usecase UC_047-Admin creates an executor configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/executor |
Method |
POST |
Status code |
201 CREATED |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
A name for this configuration |
|
|
Executor product identifier |
|
|
Executor version |
|
|
Enabled state of executor, per default false |
|
|
Base URL to the product |
|
|
User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable |
|
|
Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable |
|
|
Job parameter key |
|
|
Job parameter value |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"name":"PDS gosec configuration 1","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productXYZ.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"},{"key":"example.key2","value":"Another value"}]}}'
Response body
b922b3e7-3416-4d74-8b1a-81fbe61a3f63
7.6.51. Admin deletes executor configuration
REST API for usecase UC_048-Admin deletes executor configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/executor/{uuid} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The configuration uuid |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor/4cfe54a8-c2ce-4bef-b96b-a047a5c4c38f' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.52. Admin fetches executor configuration list
REST API for usecase UC_049-Admin fetches executor configuration list
Definition
Value | |
---|---|
Path |
/api/admin/config/executors |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Always |
|
|
The uuid of the configuration |
|
|
The configuration name |
|
|
Enabled state of configuration |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executors' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"executorConfigurations":[{"uuid":"fd85ad57-94c1-4671-a1ea-100fcb679201","name":"example configuration","enabled":true}],"type":"executorConfigurationList"}
7.6.53. Admin fetches executor configuration
REST API for usecase UC_050-Admin fetches executor configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/executor/{uuid} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The configuration uuid |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The uuid of this configuration |
|
|
The name of this configuration |
|
|
Executor product identifier |
|
|
Executor version |
|
|
Enabled state of executor |
|
|
Base URL to the product |
|
|
User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable |
|
|
Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable |
|
|
Job parameter key |
|
|
Job parameter value |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor/cf306d66-846b-4bc2-a66e-5b60055aaa70' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"uuid":"cf306d66-846b-4bc2-a66e-5b60055aaa70","name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"}]},"executorVersion":1,"enabled":false}
7.6.54. Admin updates executor configuration setup
REST API for usecase UC_051-Admin updates executor configuration setup
Definition
Value | |
---|---|
Path |
/api/admin/config/executor/{uuid} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The configuration uuid |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
The name of this configuration |
|
|
Executor product identifier |
|
|
Executor version |
|
|
Enabled state of executor, per default false |
|
|
Base URL to the product |
|
|
User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable |
|
|
Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable |
|
|
Job parameter key |
|
|
Job parameter value |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/executor/35803fed-b7b0-4bd8-9387-4773ab128a43' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"name":"New name","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productNew.example.com","credentials":{"user":"env:EXAMPLE_NEW_USENAME","password":"env:EXAMPLE_NEW_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]}}'
Response body
(empty)
7.6.55. Admin creates an execution profile
REST API for usecase UC_052-Admin creates an execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
POST |
Status code |
201 CREATED |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
A short description for the profile |
|
|
Enabled state of profile, default is false |
|
|
Configurations can be linked at creation time as well - see update description |
|
|
Projects can be linked by their ids at creation time as well - see update description |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profile/new-profile-1' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"description":"a short description for profile","configurations":[],"projectIds":[],"enabled":false}'
Response body
(empty)
7.6.56. Admin deletes execution profile
REST API for usecase UC_053-Admin deletes execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-to-delete-1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.57. Admin updates execution profile
REST API for usecase UC_054-Admin updates execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
PUT |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Request fields
Path | Type | Description |
---|---|---|
|
|
A short description for the profile |
|
|
Enabled state of profile, default is false |
|
|
Add uuid for configuration to use here |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profile/existing-profile-1' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"description":"changed description","configurations":[{"uuid":"5a8e548a-169d-4642-8d2d-00bed1357847","executorVersion":0,"enabled":false,"setup":{"credentials":{},"jobParameters":[]}}],"enabled":true}'
Response body
(empty)
7.6.58. Admin fetches execution profile
REST API for usecase UC_055-Admin fetches execution profile
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId} |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The profile id |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
A short description for the profile |
|
|
Enabled state of profile, default is false |
|
|
uuid of configuration |
|
|
name of configuration |
|
|
enabled state of this configuration |
|
|
executed product |
|
|
executor version |
|
|
Projects can be linked by their ids here |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profile/existing-profile-1' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"description":"a description","enabled":true,"configurations":[{"uuid":"006a3f33-85f6-4586-a509-5ef17c40004b","name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]},"executorVersion":1,"enabled":false}],"projectIds":["project-1","project-2"]}
7.6.59. Admin fetches execution profile list
REST API for usecase UC_056-Admin fetches execution profile list
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profiles |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
Always |
|
|
The profile id |
|
|
A profile description |
|
|
Enabled state of profile |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profiles' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"executionProfiles":[{"id":"profile1","description":"A short decription for profile1","enabled":false},{"id":"profile2","description":"A short decription for profile2","enabled":false}],"type":"executionProfileList"}
7.6.60. Admin assigns execution profile to project
REST API for usecase UC_057-Admin assigns execution profile to project
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId}/project/{projectId} |
Method |
POST |
Status code |
201 CREATED |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
The profile id |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-1/project/project-1' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.61. Admin unassigns execution profile from project
REST API for usecase UC_058-Admin unassigns execution profile from project
Definition
Value | |
---|---|
Path |
/api/admin/config/execution/profile/{profileId}/project/{projectId} |
Method |
DELETE |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The project id |
|
The profile id |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-1/project/project-1' -i -u 'user:secret' -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
(empty)
7.6.62. Admin fetches auto cleanup configuration
REST API for usecase UC_064-Admin fetches auto cleanup configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/autoclean |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/autoclean' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"cleanupTime":{"unit":"MONTH","amount":0}}
7.6.63. Admin updates auto cleanup configuration
REST API for usecase UC_065-Admin updates auto cleanup configuration
Definition
Value | |
---|---|
Path |
/api/admin/config/autoclean |
Method |
PUT |
Status code |
202 ACCEPTED |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/config/autoclean' -i -u 'user:secret' -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{"cleanupTime":{"unit":"MONTH","amount":0}}'
Response body
(empty)
7.6.64. Admin starts encryption rotation
REST API for usecase UC_073-Admin starts encryption rotation
Definition
Value | |
---|---|
Path |
/api/admin/encryption/rotate |
Method |
POST |
Status code |
200 OK |
Request headers
Name | Description |
---|
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/encryption/rotate' -i -u 'user:secret' -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"algorithm" : "AES_GCM_SIV_256",
"passwordSourceType" : "ENVIRONMENT_VARIABLE",
"passwordSourceData" : "SECRET_1"
}'
Response body
(empty)
7.6.65. Admin fetches encryption status
REST API for usecase UC_076-Admin fetches encryption status
Definition
Value | |
---|---|
Path |
/api/admin/encryption/status |
Method |
GET |
Status code |
200 OK |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The type description of the json content |
|
|
Name of the domain which will provide this encryption data elements |
|
|
Unique identifier |
|
|
Algorithm used for encryption |
|
|
Type of password source. Can be [NONE, ENVIRONMENT_VARIABLE] |
|
|
Data for password source. If type is ENVIRONMENT_VARIABLE then it is the the name of the environment variable. |
|
|
Map containing information about usage of this encryption |
|
|
Key value data |
|
|
Creation timestamp |
|
|
User id of admin who created the encryption entry |
Example
Curl request
$ curl 'https://sechub.example.com/api/admin/encryption/status' -i -u 'user:secret' -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"type":"encryptionStatus","domains":[{"name":"schedule","data":[{"id":"1","algorithm":"AES_GCM_SIV_256","passwordSource":{"type":"ENVIRONMENT_VARIABLE","data":"SECRET_1"},"usage":{"job.state.cancel_requested":4,"job.state.canceled":5,"job.state.ended":8,"job.state.initializing":1,"job.state.ready_to_start":2,"job.state.resuming":7,"job.state.started":3,"job.state.suspended":6},"createdFrom":"admin-username","created":"2024-08-01T09:26:00"}]}]}
7.6.66. 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.67. 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.68. 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.69. 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.70. 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.71. User lists jobs for project
REST API for usecase UC_071-User lists jobs for project
Definition
Value | |
---|---|
Path |
/api/project/{projectId}/jobs |
Method |
GET |
Status code |
200 OK |
Path parameters
Parameter | Description |
---|---|
|
The id of the project where job information shall be fetched for |
Query parameters
Parameter | Description |
---|---|
|
The wanted (maximum) size for the result set. When not defined, the default will be 1. |
|
The wanted page number. When not defined, the default will be 0. |
|
An optional dynamic query parameter to filter jobs by labels. The syntax is 'metadata.labels.${labelKey}=${labelValue}'. It is possible to query for multiple labels (up to 10 ). The filter works as an AND combination: Only jobs having all wanted label key value combinations are returned. |
|
An optional parameter to define if meta data shall be fetched as well. When not defined, the default will be false. |
Request headers
Name | Description |
---|
Response fields
Path | Type | Description |
---|---|---|
|
|
The page number |
|
|
The total pages available |
|
|
The job uuid |
|
|
Creation timestamp of job |
|
|
Start timestamp of job execution |
|
|
End timestamp of job execution |
|
|
User who initiated the job |
|
|
Execution state of job |
|
|
Execution result of job |
|
|
Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF |
|
|
Meta data of job - but only contained in result, when query parameter |
Example
Curl request
$ curl 'https://sechub.example.com/api/project/project1/jobs?size=1&page=0&withMetaData=true&metadata.labels.stage=testing' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Response body
{"page":0,"totalPages":1,"content":[{"jobUUID":"8d080df1-24cd-470f-b8bd-845baf4b7d60","executedBy":"User1","created":"2024-11-27T09:31:45.196835109","started":"2024-11-27T09:33:45.196866799","ended":"2024-11-27T09:48:45.19687809","executionState":"ENDED","trafficLight":"GREEN","executionResult":"OK","metaData":{"labels":{"stage":"test"}}}]}
7.7. Domain Driven Design
We use domain driven design, but communication is done very simple - for more details read the concept.
7.7.1. Domain Message Bus
The domain message bus represents an abstraction layer for communication between different domains. It shall be the ONLY way to communicate between the different domains. Purpose: In future maybe the domains will be separate spring boot applications and be also autark deployable!
Currently SecHub contains of ONE deployable spring boot application. But to prevent the "Big ball of mud" this abstraction must be always used when one domain calls another one.
7.7.2. Domain communication and actions
7.7.2.1. Overview
7.7.2.1.1. Diagram
7.7.2.1.2. List of all messages
7.7.2.2. Message ANALYZE_SCAN_RESULTS_AVAILABLE
7.7.2.3. Message AUTO_CLEANUP_CONFIGURATION_CHANGED
Use cases related to this message |
7.7.2.4. Message BINARY_UPLOAD_DONE
7.7.2.5. Message GET_ENCRYPTION_STATUS_SCHEDULE_DOMAIN
7.7.2.6. Message JOB_CANCELLATION_RUNNING
7.7.2.7. Message JOB_CREATED
7.7.2.8. Message JOB_DONE
Use cases related to this message |
7.7.2.9. Message JOB_EXECUTION_STARTING
Use cases related to this message |
7.7.2.10. Message JOB_FAILED
7.7.2.11. Message JOB_RESTART_CANCELED
Use cases related to this message |
7.7.2.12. Message JOB_RESTART_TRIGGERED
Use cases related to this message |
7.7.2.13. Message JOB_RESULTS_PURGED
Use cases related to this message |
7.7.2.14. Message JOB_RESULT_PURGE_DONE
7.7.2.15. Message JOB_RESULT_PURGE_FAILED
7.7.2.16. Message JOB_STARTED
Use cases related to this message |
7.7.2.17. Message JOB_SUSPENDED
7.7.2.18. Message MAPPING_CONFIGURATION_CHANGED
7.7.2.19. Message PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE
7.7.2.20. Message PROJECT_ACCESS_LEVEL_CHANGED
7.7.2.21. Message PROJECT_CREATED
7.7.2.22. Message PROJECT_DELETED
7.7.2.23. Message PROJECT_OWNER_CHANGED
7.7.2.24. Message PROJECT_WHITELIST_UPDATED
7.7.2.25. Message REQUEST_JOB_CANCELLATION
7.7.2.27. Message REQUEST_JOB_RESTART_HARD
Use cases related to this message |
7.7.2.28. Message REQUEST_PURGE_JOB_RESULTS
Use cases related to this message |
7.7.2.29. Message REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING
Use cases related to this message |
7.7.2.30. Message REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING
Use cases related to this message |
7.7.2.31. Message REQUEST_SCHEDULER_JOB_STATUS
Use cases related to this message |
7.7.2.32. Message REQUEST_SCHEDULER_STATUS_UPDATE
7.7.2.33. Message REQUEST_USER_ROLE_RECALCULATION
Use cases related to this message |
7.7.2.34. Message RESULT_ENCRYPTION_STATUS_SCHEDULE_DOMAIN
7.7.2.35. Message SCAN_DONE
7.7.2.36. Message SCAN_FAILED
7.7.2.37. Message SCAN_SUSPENDED
7.7.2.38. Message SCHEDULER_JOB_PROCESSING_DISABLED
Use cases related to this message |
7.7.2.39. Message SCHEDULER_JOB_PROCESSING_ENABLED
Use cases related to this message |
7.7.2.40. Message SCHEDULER_JOB_STATUS
7.7.2.41. Message SCHEDULER_STARTED
7.7.2.42. Message SCHEDULER_STATUS_UPDATE
7.7.2.43. Message SCHEDULE_ENCRYPTION_POOL_INITIALIZED
7.7.2.44. Message SOURCE_UPLOAD_DONE
7.7.2.45. Message START_ENCRYPTION_ROTATION
7.7.2.46. Message START_SCAN
Use cases related to this message |
7.7.2.47. Message UNSUPPORTED_OPERATION
7.7.2.48. Message USER_ADDED_TO_PROJECT
Use cases related to this message |
7.7.2.49. Message USER_API_TOKEN_CHANGED
7.7.2.50. Message USER_BECOMES_SUPERADMIN
7.7.2.52. Message USER_DELETED
7.7.2.53. Message USER_EMAIL_ADDRESS_CHANGED
7.7.2.54. Message USER_NEW_API_TOKEN_REQUESTED
Use cases related to this message |
7.7.2.55. Message USER_NO_LONGER_SUPERADMIN
7.7.2.56. Message USER_REMOVED_FROM_PROJECT
Use cases related to this message |
7.7.2.57. Message USER_ROLES_CHANGED
Use cases related to this message |
7.8. Calling Security Products
7.8.1. Product adapter
A Product adapter is "stupid" and does NOT know anything about SecHub.
It only knows a product and is able to provide methods for access. That’s all. In most cases there exists also a simple test application which can be used to play around with the product. So we got rapid response if product adapter works well.
Every product adapter must be provided and used by its own interface. Also the adapter project must provide:
-
Real adapter implementation
-
Additional mock variant
-
mock REST api calls etc.
-
returns a predefined set of an real output
-
maybe has possibilities to change the behaviour on runtime
-
By the mock variant it is possible to - test the complete szenario in a very fast way… - test configuration values from SecHub are passed through adapter
7.8.1.1. Implementation of new adapters
Only green highlighted classes in former image above needs to be implmemented to get a new adapter running.
The abstract implementation does have the most technical parts already inside, so implementing a new adapter should be very easy and developers can concentrate on adapter business logic.
For example the handling of proxies or self signed certificates is already managed there. Please look into existing adapters for more information / inspiration.
7.8.2. Product executor
A Product executor
does know SecHub and has access to database etc. It uses a Product adapter
inside!
7.8.3. Product executors and results
The scan service
and the report builder service
are using different product executors to create ProductResult
table entries.
Each product executor will persist its state - so even SERECO
will persist its full content as report result as well!
This was made to store all information - for retry mechanism in future and also for easier debugging etc.
When failures on last step are occurring (and e.g. we got a succesful scan(s) by other (product(s) which took
3 hours….) we can retry the full step - or, at least interesting for debugging/analyzing.
7.8.4. Product executor versus product execution service
The service does execute and handle different product executors.
7.9. Network target handling
For some security products it’s necessary to differ between intranet
and internet
scan targets.
This is represented by the class NetworkTarget
.
Some products are not able to handle different network targets when not being installed twice, some can do this by a product specific identifier. SecHub must be able to automatically call the correct product installation in such cases.
To handle this always the same way some framework mechanism was introduced, see next chapter.
7.9.1. Automatic Network Target info resolving
The class AbstractProductExecutor
is the single base class for mostly all product executors and does
automatically provide network target handling for scan types webScan
and infraScan
.
The abstract executor will create a ProductExecutorData
object at runtime let child implementations
customize it and then prepare all necessary steps before giving it again to the child implementation
for final execution.
For automated target handling the customization of ProductExecutorData
must set a
NetworkTargetProductServerDataProvider
and a NetworkTargetLocationProvider
.
For |
8. Deployment View
8.1. SecHub infrastructure setup
8.2. Spring boot
8.2.1. SecHub Spring Profiles
SecHub
provides multiple Spring
profiles
8.2.1.1. Server
8.2.1.1.1. Overview
8.2.1.1.2. PROD
As name offers, this profile is designed for production.
For production the profile |
8.2.1.1.3. DEV
For development this profile must be combinated with others to get server starting - but its extreme flexible and has only a dependency to localserver
8.2.1.1.4. Integration-Test
SecHub itself
We use integrationtest
profile for server integration tests. You must add some
additional profiles. We use h2
and mocked_products
for unit testing
of sechub server itself.
Test your security tool suite installation
You can use this profile also for testing your security product suite in combination with sechub server - e.g. when you have done an update at your product suite and you are not sure if its compatible or the products have bugs.
But (at least currently) you have to write your own tests then. Following could be done:
-
Write some simple bash scripts which are using SecHub client
-
Use
sechub-integrationtest
project as dependency and write some junit tests using TestAPI.
if you want to test your installed environment is working you can also use
real_products
.
We got dedicated profile constants. For adapters the constants can be found at |
8.2.2. Database configuration
8.2.2.1. PostgreSQL
First of all, install a PostgreSQL database.
Then define following environment entries before you start the server with active postgres profile:
-
POSTGRES_DB_URL
-
POSTGRES_DB_USERNAME
-
POSTGRES_DB_PASSWORD
Examples:
POSTGRES_DB_URL=jdbc:postgresql://127.0.0.1:49152/sechub POSTGRES_DB_USERNAME=sechub-pg-admin POSTGRES_DB_PASSWORD=a-very-strong-password...
8.2.3. General configuration
SecHub can be configured by keys on server startup.
Using the spring @Value
annotation we are able to
use these keys as Java system properties but also as environment entries.
E.g. a key like sechub.server.baseurl
can be set with
java ... -Dsechub.server.baseurl=https://sechub.example.org
or with an environment entry SECHUB_SERVER_BASEURL
which
is e.g. more suitable for a kubernetes
cluster deployment.
The next text blocks describe the keys available on SecHub:
Key or variable name | Default | Description |
---|---|---|
sechub.feature.showProductResultLink |
false |
Administrators can turn on this mode to allow product links in json and HTML output |
sechub.notification.scheduler.startup.enabled |
true |
When enabled, administrators will be informed by notification when new scheduler instances are started. Those notifications will also contain information about potential zombie jobs. When disabled, incoming events will be ignored and no notification sent. |
Key or variable name | Default | Description |
---|---|---|
sechub.user.onetimetoken.outdated.millis |
86400000 |
One time token time when outdating |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.checkmarx.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter check operation is called next. When -1 value is 1 minutes |
sechub.adapter.checkmarx.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.checkmarx.trustall |
false |
Turns off certification checks for this product only. Should only be used in test or development environments! |
Key or variable name | Default | Description |
---|---|---|
sechub.initialadmin.apitoken |
An apitoken for initial admin, will only be used in DEV and INTEGRATIONTEST profiles and is optional! |
|
sechub.initialadmin.email |
Mail of initial administrator |
|
sechub.initialadmin.userid |
Userid of initial administrator |
Key or variable name | Default | Description |
---|---|---|
sechub.migration.flyway.autorepair |
true |
When enabled, flyway migration problems will be automatically repaired |
Key or variable name | Default | Description |
---|---|---|
sechub.notification.email.mock.cache.enabled |
false |
When email mock shall cache the mails this must be configured to true, per default disabled! |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.nessus.defaultpolicyid |
deprecated |
Default policy ID for nessus scans |
sechub.adapter.nessus.internet.baseurl |
deprecated |
Base url of nessus used for internet scans |
sechub.adapter.nessus.internet.password |
deprecated |
Password for nessus instance used for internet scans |
sechub.adapter.nessus.internet.userid |
deprecated |
User id of nessus user (internet) |
sechub.adapter.nessus.intranet.baseurl |
deprecated |
Base url of nessus used for intranet scans |
sechub.adapter.nessus.intranet.password |
deprecated |
Password for nessus instance used for intranet scans |
sechub.adapter.nessus.intranet.userid |
deprecated |
User id of nessus user (intranet) |
sechub.adapter.nessus.proxy.hostname |
Proxy hostname for nessus server connection, when empty no proxy is used. When not empty proxy port must be set too! |
|
sechub.adapter.nessus.proxy.port |
0 |
Proxy port for nessus server connection, default is 0. If you are setting a proxy hostname you have to configure this value correctly |
sechub.adapter.nessus.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.nessus.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.nessus.trustall |
true |
Turns off certification checks for this product only. Should only be used in test or development environments! |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.netsparker.agentname |
deprecated |
The name of the agent to be used by netsparker. If a agent group name is already defined the group will be superiour. If no group set and no agent name netsparker will use a agent but seems to be unpredictable which agent will be used. |
sechub.adapter.netsparker.apitoken |
deprecated |
API token for netsparker user |
sechub.adapter.netsparker.baseurl |
deprecated |
Base url for netsparker installation |
sechub.adapter.netsparker.defaultpolicyid |
deprecated |
Default policy ID for netsparker scans |
sechub.adapter.netsparker.internet.agentgroupname |
deprecated |
The name of the agent group to be used by netsparker for intranet scans. If not set no agent group will be used. |
sechub.adapter.netsparker.intranet.agentgroupname |
deprecated |
The name of the agent group to be used by netsparker for intranet scans. If not set no agent group will be used. |
sechub.adapter.netsparker.licenseid |
deprecated |
|
sechub.adapter.netsparker.scanresultcheck.period.minutes |
-1 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
sechub.adapter.netsparker.scanresultcheck.timeout.minutes |
-1 |
Time in minutes when adapter check operation is called next. When -1 value is 1 minutes |
sechub.adapter.netsparker.trustall |
true |
Turns off certification checks for this product only. Should only be used in test or development environments! |
sechub.adapter.netsparker.userid |
deprecated |
user id of netsparker user |
Key or variable name | Default | Description |
---|---|---|
sechub.user.onetimetoken.outdated.millis |
86400000 |
Time until the one time token expires |
Key or variable name | Default | Description |
---|---|---|
sechub.notification.email.administrators |
Single email address used for emails to administrators. This should be a NPM (non personalized mailbox) |
|
sechub.notification.email.from |
Address used for emails sent by sechub system |
|
sechub.notification.email.replyto |
Address used for reply when email was sent by sechub system |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.pds.default.check.timetowait.milliseconds |
30000 |
Time in milliseconds when adapter check operation is called next. When -1 value is 60000 minutes |
sechub.adapter.pds.default.timeout.minutes |
240 |
Time in minutes when adapter result check will automatically time out and adapter stops execution automatically. When -1 timeout is 7200 minutes |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.checkmarx.resilience.badrequest.retry.max |
3 |
Amount of retries done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.badrequest.retry.wait |
2000 |
Time to wait until retry is done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.max |
1 |
Amount of retries done when a 500 server internal error happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.wait |
5000 |
Time to wait until retry is done when a 500 server internal error happened on Checkmarx server |
sechub.adapter.pds.resilience.encryption-out-of-sync.retry.max |
3 |
Amount of retries done when a PDS encryption out of sync problem happens |
sechub.adapter.pds.resilience.encryption-out-of-sync.retry.wait |
2000 |
Time to wait until retry is done when a PDS encryption out of sync problem happens |
Key or variable name | Default | Description |
---|---|---|
sechub.config.check.canceljob.delay |
60000 |
Define delay in milliseconds, for before next job cancellation check will be executed. |
sechub.config.scan.scanconfig.refresh.delay |
5000 |
Define delay (in milliseconds) for next job execution trigger after last executed. |
sechub.config.scan.scanconfig.refresh.initialdelay |
0 |
Define initial delay (in milliseconds) for scan config refresh check operation. |
sechub.report.sensitivedata.max.nonobfuscated.characters |
0 |
Define the amount of visible characters which are NOT obfuscated. |
Key or variable name | Default | Description |
---|---|---|
sechub.schedule.nextjob.suspend.miniumum-duration.milliseconds |
60000 |
The scheduler automatically restarts the next suspended jobs, regardless of the defined schedule strategy. This is done to get suspended jobs of another shut down instance back up and running as quickly as possible. To avoid suspended jobs being restarted too quickly, you can use this value to set the minimum time that must pass before the next suspended job can be restarted. The value is defined in milliseconds. The (previous) end date of the suspended job is used. For example, this value is important for K8s redeployment, because the servers that have not yet been updated should not immediately continue with the suspended jobs - they will also be shut down soon and would suspend the restarted jobs again… |
Key or variable name | Default | Description |
---|---|---|
sechub.config.trigger.healthcheck.enabled |
true |
When enabled each trigger will do an health check by monitoring service. If system has too much CPU load or uses too much memory, the trigger will not execute until memory and CPU load is at normal level! |
sechub.config.trigger.nextjob.delay |
10000 |
Define delay for next job execution trigger after last executed. |
sechub.config.trigger.nextjob.initialdelay |
5000 |
Define initial delay for next job execution trigger. Interesting inside a cluster - just define this value different inside your instances (e.g. random value). This avoids write operations at same time. |
sechub.config.trigger.nextjob.maxwaitretry |
300 |
When retry mechanism is enabled by |
sechub.config.trigger.nextjob.retries |
5 |
Inside a cluster the next job fetching can lead to concurrent access. When this happens a retry can be done for the 'looser'. This value defines the amount of *tries*If you do not want any retries set the value to a value lower than 2. 2 Means after one execution failed there is one retry. Values lower than 2 will lead to one try of execution only. |
sechub.scheduler.strategy.id |
Define the scheduler strategy by given identifier. This strategy determines the next job which shall be executed by job scheduler. Possible values are:first-come-first-serve,only-one-scan-per-project-at-a-time and only-one-scan-per-project-and-module-group |
|
sechub.server.upload.validate.checksum |
true |
With |
sechub.server.upload.validate.zip |
true |
With |
sechub.upload.binaries.maximum.bytes |
52428800 |
Define the maximum amount of bytes accepted for uploading |
Key or variable name | Default | Description |
---|---|---|
sechub.adapter.checkmarx.resilience.badrequest.retry.max |
3 |
Maximum amount of possible retries for situations when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.badrequest.retry.wait |
2000 |
Time to wait until retry is done when a 400 bad request happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.networkerror.retry.max |
100 |
Maximum amount of possible retries for situations when a network error happened on communication to Checkmarx server |
sechub.adapter.checkmarx.resilience.networkerror.retry.wait |
5000 |
Time to wait until retry is done when a network server happened on communication to Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.max |
1 |
Maximum amount of possible retries for situations when a 500 server internal error happened on Checkmarx server |
sechub.adapter.checkmarx.resilience.servererror.retry.wait |
5000 |
Time to wait until retry is done when a 500 server internal error happened on Checkmarx server |
sechub.project.joblist.page.max |
100 |
|
sechub.project.joblist.size.max |
100 |
Maximum limit for job information list entries per page |
sechub.schedule.encryption.refresh.accept-outdated.milliseconds |
1800000 |
The maximum amount of milliseconds an outdated encryption pool is still accepted in refresh phase |
sechub.server.baseurl |
Base url of SecHub server - e.g. https://sechub.example.org |
Key or variable name | Default | Description |
---|---|---|
sechub.security.diffiehellman.length |
Define diffie hellman key length, see https://github.com/mercedes-benz/sechub/issues/689 for details |
Key or variable name | Default | Description |
---|---|---|
sechub.server.debug |
false |
When debug flag is set, rest call reponse error messages do also contain stacktraces. |
Key or variable name | Default | Description |
---|---|---|
sechub.notification.smtp.config |
mail.smtp.auth=false,mail.transport.protocol=smtp |
SMTP configuration map. You can setup all java mail smtp settings here in comma separate form with key=value. For Example: |
sechub.notification.smtp.credential.password |
Password on SMPTP server, empty value means no password |
|
sechub.notification.smtp.credential.username |
Username on SMPTP server, empty value means no username |
|
sechub.notification.smtp.hostname |
Hostname of SMPTP server |
|
sechub.notification.smtp.port |
25 |
Port of SMPTP server, per default:25 |
Key or variable name | Default | Description |
---|---|---|
sechub.storage.s3.accesskey |
undefined |
Defines the access key for used S3 bucket |
sechub.storage.s3.bucketname |
undefined |
Defines the S3 bucket name |
sechub.storage.s3.connection.idle.max.milliseconds |
60000 |
S3 client maximum idle time (in milliseconds) for a connection in the connection pool. |
sechub.storage.s3.connection.idle.validate.milliseconds |
5000 |
S3 client time (in milliseconds) a connection can be idle in the connection pool before it must be validated that it’s still open. |
sechub.storage.s3.connection.max.poolsize |
50 |
S3 client max connection pool size. |
sechub.storage.s3.connection.ttl.milliseconds |
-1 |
S3 client expiration time (in milliseconds) for a connection in the connection pool. -1 means deactivated |
sechub.storage.s3.endpoint |
undefined |
Defines the S3 endpoint - e.g. https://play.min.io |
sechub.storage.s3.secretkey |
undefined |
Defines the secret key for used S3 bucket |
sechub.storage.s3.signer.override |
AWSS3V4SignerType |
Can be used to override the default name of the signature algorithm used to sign requests. |
sechub.storage.s3.timeout.connection.milliseconds |
10000 |
S3 client timeout (in milliseconds) for creating new connections. |
sechub.storage.s3.timeout.execution.milliseconds |
0 |
S3 client timeout (in milliseconds) for execution. 0 means it is disabled. |
sechub.storage.s3.timeout.request.milliseconds |
0 |
S3 client timeout (in milliseconds) for a request. 0 means it is disabled. |
sechub.storage.s3.timeout.socket.milliseconds |
50000 |
S3 client timeout (in milliseconds) for reading from a connected socket. |
sechub.storage.sharedvolume.upload.dir |
undefined |
Defines the root path for shared volume uploads - e.g. for sourcecode.zip etc. When using keyword temp as path, this will create a temporary directory (for testing). |