SecHub Server Rest API Documentation

1. About

About SecHub

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

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

So you still need an existing security infrastructure behind SecHub !

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

You can get more information about from SecHub web page .

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

About documentation

This documentation is part of SecHub.

Key	Value	Information
LICENSE	MIT License	Please look at https://github.com/mercedes-benz/sechub/blob/master/LICENSE

Key

Value

Information

LICENSE

MIT License

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

Documentation version: Server 1.9.0 - Build date: 20240430152944

2. SecHub REST API

You are encouraged to use SecHub client instead of using REST API direct! It makes usage of SecHub much more comfortable!

Using REST API directly can be a little bit cumbersome…

Look at SecHub web page to get information about SecHub client.

2.1. SecHub configuration JSON

A SecHub configuration must be valid JSON and is defined at caller side.

It is used by the client and also by rest calls to define SecHub scan jobs and add meta data.

Some minor parts are client specific and must be handled by direct REST calls in a special way or do just not exist. But this is mentioned inside this documentation

The individual components in the JSON are documented below:

2.1.1. API version

apiVersion must be defined (so mandatory). Currently only 1.0 is valid.

2.1.2. Server

server defines the url of your SecHub server. Information can be used by client implementations.

This is an optional parameter only which is only interesting for the client to pass the URL. Every REST call contains the server URL already.

2.1.3. Project

project defines the project id within SecHub. Information can be used by client implementations.

When using project id related REST calls, you do not need the project id inside the configuration.

2.1.4. Code scan

codeScan defines the settings for code scans.

2.1.4.1. Upload source files from file system

This section applies only to the SecHub client.

All source code files inside the defined folders will be automatically zipped and uploaded by the SecHub client to the SecHub server for analysis.

Paths must be defined relative to caller location - for example on a Jenkins Build Server this is usually the root folder of your repository.

Please do NOT use \ inside paths but always /.

We do NOT recommend using absolute paths but always relative paths!
You should call SecHub inside the repository’s root folder - this is the standard on build servers.

There are two ways to define source code uploads for the SecHub client:

2.1.4.1.1. Using `data` section

Define the files and folders in a data section and reference it inside the codeScan.
This becomes useful e.g. if the same sources are used by different scan types.

Example sechub.json using data section

{
  "apiVersion": "1.0",
  "codeScan": { (1)
    "use": [
      "gamechanger-sources"
    ]
  },
  "data": {
    "sources": [ (2)
      {
        "name": "gamechanger-sources",
        "fileSystem": { (3)
          "folders": [ (4)
            "gamechanger-android/src/main/java",
            "gamechanger-server/src/main/java"
          ]
        },
        "excludes": [ (5)
          "**/mytestcode/**",
          "*.config"
        ],
        "additionalFilenameExtensions": [ (6)
          ".cplusplus",
          ".py9"
        ]
      }
    ]
  }
}

1	Define code scan
2	Upload source code (in contrast to binary uploads)
3	`fileSystem` - means uploading sources from local filesystem to SecHub server
4	Upload will contain sources from `gamechanger-android/src/main/java` and `gamechanger-server/src/main/java` and their sub folders
5	Exclude directories (optional), the ANT fileset pattern notation is supported. In the example above all files in directories named `mytestcode` and their subdirectories are excluded from upload. Also all files matching `.config` are excluded in any directory Default excludes: Per default, the directories `/test/` `/.git/` `/node_modules/*` are already excluded.
6	The SecHub client only adds "well known" sources into the upload zip file. This reduces the upload size and the scan duration. (E.g. a codescan for a JPEG image would not make sense…) In the SecHub client documentation you will find a list of the default file endings. Here we also add ".cplusplus" and ".py9" as additional accepted source file extensions.

2.1.4.1.2. `fileSystem` inside the `codeScan` section (deprecated)

Define a fileSystem child entry inside the codeScan section for code scanning.

This option is deprecated but still supported.
Please consider using the data section as described above as it provides more flexibility.

Example sechub.json using fileSystem inside the codeScan section (results in same upload as in above example):

{
  "apiVersion": "1.0",
  "codeScan": {
    "fileSystem": {
      "folders": [
        "gamechanger-android/src/main/java",
        "gamechanger-server/src/main/java"
      ]
    },
    "excludes": [
      "**/mytestcode/**",
      "*.config"
    ],
    "additionalFilenameExtensions": [
      ".cplusplus",
      ".py9"
    ]
  }
}

2.1.5. License scan

licenseScan defines the settings for license scans.

2.1.5.1. Example binary license scan

License scan configuration for binaries

{
  "apiVersion" : "1.0",
  "data" : {
    "binaries" : [ { 
      "name" : "firmware-images",(1)
      "fileSystem" : {
        "folders" : [ "gamechanger-firmware/images" ]
      }
    } ]
  },
  "licenseScan" : { 
    "use" : [ "firmware-images"] (2)
  }
}

1	name of the source data configuration: "firmware-images"
2	license scan uses the referenced data configuration "firmware-images"

2.1.5.2. Example source license scan

License scan configuration for sources

{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [ {
      "name" : "firmware-sources", (1)
      "fileSystem" : {
        "folders" : [ "gamechanger-firmware/src" ]
      }
    } ]
  },
  "licenseScan" : { 
    "use" : [ "firmware-sources"] (2)
  }
}

1	name of the source data configuration: "firmware-sources"
2	license scan uses the referenced data configuration "firmware-sources"

2.1.5.3. Example source licence scan with sources code scan combined

License scan and code scan configuration for sources

{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [ {
      "name" : "firmware-sources", (1)
      "fileSystem" : {
        "folders" : [ "gamechanger-firmware/src" ] 
      }
    } ]
  },
  "licenseScan" : {
    "use" : [ "firmware-sources"] (2)
  },
  
  "codeScan" : {
    "use" : [ "firmware-sources"] (3)
  }
}

1	name of the source data configuration: "firmware-sources"
2	license scan uses the referenced data configuration "firmware-sources"
3	code scan uses the referenced data configuration "firmware-sources"

2.1.6. Secret scan

secretScan defines the settings for scanning for secrets in your source code.

The SecHub client automatically adds every file of the defined source directories. (Not only known programming language file extensions like with codeScan)

SecHub Client: With the -addScmHistory option SCM directories like .git are also uploaded because secrets could be in the SCM history of previous commits.

2.1.6.1. Example source secret scan

Secret scan configuration for sources

{
  "apiVersion": "1.0",
  "data": {
    "sources": [
      {
        "name": "gamechanger-source", (1)
        "fileSystem": {
          "folders": [ "." ] (2)
        }
      }
    ]
  },
  "secretScan": {
    "use": [ "gamechanger-source" ] (3)
  }
}

1	name of the source data configuration: "gamechanger-source"
2	source code folder(s) to scan. ("." = current directory)
3	secret scan uses the referenced data configuration "gamechanger-source"

2.1.6.2. Example binary secret scan

Secret scan scan configuration for binaries

{
  "apiVersion" : "1.0",
  "data" : {
    "binaries" : [ { 
      "name" : "firmware-images",(1)
      "fileSystem" : {
        "folders" : [ "gamechanger-firmware/images" ]
      }
    } ]
  },
  "secretScan" : { 
    "use" : [ "firmware-images"] (2)
  }
}

1	name of the source data configuration: "firmware-images"
2	secret scan uses the referenced data configuration "firmware-images"

2.1.6.3. Example source secret scan combined with code scan

Secret scan and code scan configuration for sources

{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [
      {
        "name" : "gamechanger-source", (1)
        "fileSystem" : {
          "folders" : [ "."  ] (2)
        }
      }
    ]
  },
  "secretScan" : { 
    "use" : [ "gamechanger-source"] (3)
  },
  "codeScan" : { 
    "use" : [ "gamechanger-source"] (4)
  }
}

1	name of the source data configuration: "gamechanger-source"
2	source code folder(s) to scan.
3	secret scan uses the referenced data configuration "gamechanger-source"
4	code scan uses the referenced data configuration "gamechanger-source"

2.1.7. Web scan

webScan defines the settings for web scans (DAST).

2.1.7.1. URL

Use the url element to define a URL you want to scan.

The URL must be whitelisted in your project. Otherwise it will be rejected. So you are not able to start scanning foreign domains and do accidently attack them…

2.1.7.1.1. Example anonymous

{
  "apiVersion": "1.0",
  "webScan": { (1)
    "url": "https://www.gamechanger.example.org", (2)
    "includes": [ (3)
      "/special/include",
      "/special/include/<*>",
      "<*>/special/<*>/include/<*>",
      "<*>/special/include/<*>",
      "special/include/<*>",
      "special/include",
      "special/include/"
    ],
    "excludes": [ (4)
      "/en/contact",
      "/en/contacts/<*>",
      "<*>/en/<*>/contacts/<*>",
      "<*>/en/contacts/<*>",
      "en/contacts/<*>",
      "en/contacts",
      "en/contacts/"
    ]
  },
  "maxScanDuration": { (5)
    "duration": 1,
    "unit": "hour" (6)
  }
}

1	Define web scan
2	The `URL` to scan. This `URL` must be whitelisted in `SecHub` project. Normally without a slash `/` at the end.
3	Optional: Define includes, if you have a special path that is linked nowhere, so the scanner can not detect it automatically while crawling the application. You can use wildcards by using the symbol `<>` like in the example above. To make the scan work the target URL will always be implicitly included with `"https://www.gamechanger.example.org<>"` if no includes are specified. If includes are specified the scan is limited to these includes. In case you need to include certain parts of your application the scanner cannot detect, but you want everything else to be scanned as well, please specify a wildcard as include explicitly: `"includes": [ "/hidden/from/crawler/", "/<>" ]`. Includes starting with a slash (`/`) like `"includes": [ "/special/include","/special/include/<>"]` they are interpreted relative to the scan target `URL` provided before. Includes not starting with a slash (`/`) like `"includes": [ "<>/en/contacts/<>","en/contacts/<>","en/contacts","en/contacts/"`] are interpreted as enclosed by wildcards like the first include in the list example: `"<>/en/contacts/<*>"`.
4	Optional: Define excludes, if you have a special path you want to exclude, from the scan. You can use excludes the same way you can use the includes. Excludes do always overwrite includes if the provided patterns for includes and excludes do have intersections.
5	Optional: Define the maximum duration the scan can take. Scanning a "large" web page/application can take several hours or even days. This option ensures the scan will only run for a limited time.
6	Define the unit of time. The unit can be: `millisecond`, `second`, `minute`, `hour`, `day`.

Includes are a different from excludes looking at wildcards, because in includes they might not be resolved properly, if the pages behind the wildcards cannot be detected by a web crawler.

If you only want to scan a specific part of your application e.g only the customers section https://my-application.com/customer/, you can specify the target URL : "url": "https://my-application.com" and the wanted include starting with a slash like this : "includes": [ "/customer/<*>"].

A web scan does work much better if it has got access to all content - so a login is necessary most time. If you do not define a login configuration your web scan will be done only as anonymous user.

Providing login will enable web scanner to execute ALL possible actions!

An example: Your test application has a Web UI for sending SMS which can be triggered by an user. Then a web scan can trigger those operations as well!

If you do this inside an environment where a real SMS provider is connected, this could result into mass SMS and also in a bigger invoice from your SMS provider - so be careful!

2.1.7.2.1. Options

SecHub provides you with 2 options for login:

basic authentication
form based login
- script based

When a web scan product (or its adapter) does not support your wanted options you will have a failure at execution time!

2.1.7.2.2. Example basic authentication

{
    "apiVersion": "1.0",
    "webScan": {
        "url": "https://productfailure.demo.example.org",
        "login": {
            "url": "https://productfailure.demo.example.org/login",(1)
            "basic": {(2)
                "user": "{{ .LOGIN_USER }}",
                "password": "{{ .LOGIN_PWD }}",
                "realm": "{{ .LOGIN_REALM }}" (3)
            }
        }
    }
}

1	URL for web login
2	Basic authentication, needs user id/name and password.
3	Optional: You can set the realm used for basic authentication. But normally this is not necessary.

2.1.7.2.3. Example client certificate authentication

client certificate authentication

{
  "apiVersion" : "1.0",
  "project" : "example_project",
  "data" : {
    "sources" : [ {
      "name" : "client-certificate-file-reference", (1)
      "fileSystem" : {
        "files" : [ "path/to/backend-cert.p12" ]
      }
    } ]
  },
  "webScan" : {
    "url" : "https://my-app.com",
    "clientCertificate" : {
      "password" : "{{ .CERT_PASSWORD }}", (2)
      "use" : [ "client-certificate-file-reference" ] (3)
    }
  }
}

1	name of the source data configuration: "client-certificate-file-reference". Please use single files only instead of folders to specify the client certificate. If you want to combine this with an openAPI definition that must be uploaded for the scan as well, please refer to this example.
2	Optional: If the client certificate is password protected, the password can be specified here. Using our SecHub GO client you can make use of the GO templating engine. Like in the example above the you can provide an environment variable containing the password instead of writing the plaintext password in the JSON configuration file. In the example above the SecHub GO client will substitute the value of `"{{ .CERT_PASSWORD }}"` with the value of the environment variable `CERT_PASSWORD`.
3	web scan uses the referenced data configuration "client-certificate-file-reference", to obtain the client certificate file.

This example currently only works with the Netsparker DAST module. We deprecated the Netsparker integration because it is not developed any further from our side. We use and develop the Zaproxy integration. As soon as this feature is available for our actively maintained Zaproxy DAST module, we will remove this warning. If you host SecHub yourself with a Netsparker module, this does not affect you. You can use this configuration as before.

{
  "apiVersion" : "1.0",
  "webScan" : {
    "url" : "https://productfailure.demo.example.org",
    "login" : {
      "url" : "https://productfailure.demo.example.org/login", (1)
      "form" : { (2)
        "script" : { (3)
          "pages" : [ (4)
                  {
                    "actions" : [ (5)
                            {
                              "type" : "username", (6)
                              "selector" : "#example_login_userid", (7)
                              "value" : "{{ .LOGIN_USER }}" (8)
                            }, 
                            {
                              "type" : "password",
                              "selector" : "#example_login_pwd",
                              "value" : "{{ .LOGIN_PWD }}"
                            },
                            {
                              "type" : "click",
                              "selector" : "#next",
                              "description" : "Click to go to next page" (9)
                            }
                         ]
                  },
                  {
                    "actions" : [
                            {
                              "type" : "input",
                              "selector" : "#example_other_inputfield",
                              "value" : "{{ .OTHER_VALUE }}"
                            }, 
                            {
                              "type" : "wait", (10)
                              "value" : "1",
                              "unit" : "second" (11)
                            }, 
                            {
                              "type" : "click",
                              "selector" : "#doLogin"
                            } 
                    ]
                 } 
          ]
        }
      }
    }
  }
}

1	URL for web login.
2	Start of form based login.
3	Script definition.
4	Pages section. A page is a visible page. Some logins need more than one page.
5	The actions which should be executed on each page.
6	Type of action. Valid types are : `username` name of user used for login `password` password entered at login `input` setup value for a field on UI `click` will simulate a mouse click on UI `wait` time to wait before executing the next action
7	Selector (CSS) to identify web element.
8	Value, used by most actions (`username\|password\|input\|wait`). In this examples you see variables in `go template` format. This is SecHub client specific. If you use the REST API directly, you must use real values!
9	A description can be added to explain an action.
10	The time the next action will be delayed.
11	Define the unit of time. The unit can be: `millisecond`, `second`, `minute`, `hour`, `day`.

username and password are like input but SecHub tries to hide these information in logs or at UI where possible. So do NOT use input for credentials!

2.1.7.2.5. Example OpenAPI scan

Open API scan

{
  "apiVersion" : "1.0",
  "data" : { 
    "sources" : [ {
      "name" : "open-api-file-reference", (1)
      "fileSystem" : {
        "files" : [ "gamechanger-webapp/src/main/resources/openapi3.json" ]
      }
    } ]
  },
  "webScan" : { 
    "url" : "https://productfailure.demo.example.org",
    "api" : {
      "type" : "openApi", (2)
      "use" : [ "open-api-file-reference" ] (3)
    }
  }
}

1	name of the source data configuration: "open-api-file-reference"
2	web scan uses "openApi" as API type
3	web scan uses the referenced data configuration "open-api-file-reference" to obtain the open api configuration file

2.1.7.2.6. Example combination of openAPI definition and client certificate authentication

Open API scan with client certificate authentication

{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [ {
      "name" : "open-api-file-reference", (1)
      "fileSystem" : {
        "files" : [ "gamechanger-webapp/src/main/resources/openapi3.json" ]
      }
    }, {
      "name" : "client-certificate-file-reference", (2)
      "fileSystem" : {
        "files" : [ "path/to/backend-cert.p12" ]
      }
    } ]
  },
  "webScan" : {
    "url" : "https://productfailure.demo.example.org",
    "api" : {
      "type" : "openApi",
      "use" : [ "open-api-file-reference" ] (3)
    },
    "clientCertificate" : {
      "password" : "{{ .CERT_PASSWORD }}",
      "use" : [ "client-certificate-file-reference" ] (4)
    }
  }
}

1	Data section with files referenced by the `openAPI` definition. Multiple files (NOT folders) are possible.
2	Data section with the file referenced by the `clientCertificate` definition. Only one single file shall be provided here.
3	Reference to the data section containing files with your openAPI definitions (e.g. swagger.yml or openAPI.json)
4	Reference to the data section containing file with your client certificate for authentication.

2.1.7.2.7. Example Header scan

header scan

{
  "apiVersion" : "1.0",
  "webScan" : {
    "url" : "https://productfailure.demo.example.org",
    "headers" : [ {
      "name" : "Authorization", (1)
      "value" : "{{ .HEADER_VALUE }}" (2)
    }, {
      "name" : "x-file-size", (3)
      "value" : "123456", (4)
      "onlyForUrls" : [ "https://productfailure.demo.example.org/admin", "https://productfailure.demo.example.org/upload/<*>", "https://productfailure.demo.example.org/<*>/special/" ], (5)
      "sensitive" : false (6)
    } ]
  }
}

1	Name of the specified header. Must not be null or empty.
2	Value of the specified header. Must not be null or empty. You can use the `go template` format like above by creating a environment variable like: `HEADER_VALUE="Bearer mytoken1234"`. This might be useful to load the information via the SecHub client dynamically, if the header value you specify contains credentials.
3	Name of the second header. You can specify a list of headers the DAST Scanner needs interact with your application.
4	Value of the second header. Here no `go template` format is used, since in this example there are no credentials but only file size of an upload.
5	Optional Parameter: For each header you can specify a list of URLs. The header this list belongs to, will only be send when accessing one of the URLs on the list. If you do not specify a list of URLs or the list is empty, the header will be send on each request to every URL. You can also use wildcards by specifying `<*>` like in the example above. Adding a wildcard to the end of an URL, the header will be sent to all sub URLs as well, otherwise it won’t be sent to sub URLs. Make sure that the header URL combinations are unique. This means do not specify the same header multiple times for the same scope of URLs.
6	Optional Parameter to handle sensitive header data: If `true`, the value of this header will be masked inside the SecHub report to avoid leaking the information. But if the parameter is set to `false` the value will be shown as is. The default is `true` if nothing is specified.

2.1.7.2.8. Example Header scan with value from data section

header scan with value from data section

{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [ {
      "name" : "header-value-file-reference", 
      "fileSystem" : {
        "files" : [ "header_value.txt" ]
      }
    }]
  },
  "webScan" : {
    "url" : "https://productfailure.demo.example.org",
    "headers" : [ {
      "name" : "Authorization", (1)
      "use" : [ "header-value-file-reference" ] (2)
    } ]
  }
}

1 Name of the specified header. Must not be null or empty.

2 Name of the source data configuration: "header-value-file-reference". Please use single files only instead of folders to specify the header value. Use a separate data section for each header. This can be used if you want to provide a large header value, which exceeds the maximum size of the sechub.json configuration file. For each header provide either a value directly (as shown in Example Header scan) or a data section reference via use as shown in this example.

2.1.8. Infrastructure scan

infraScan (optional) defines the infrastructure scan settings.

2.1.8.1. URIs

Use uris element to define a string array containing URIs you want to scan.

2.1.8.1.1. Example infrascan one URI

{
  "apiVersion": "1.0",
  "infraScan": { (1)
    "uris": [ (2)
      "https://www.gamechanger.example.org/"
    ]
  }
}

1	Define infrastructure scan
2	The `URI` s to scan. Every `URI` listed here must be white listed in `SecHub` project.

2.1.8.2. IPs

Use ips element to define a string array containing IPs you want to scan.

2.1.8.2.1. Example infrascan one IP

{
  "apiVersion": "1.0",
  "infraScan": { (1)
    "ips": [ (2)
      "127.0.0.1"
    ]
  }
}

1	Define infrastructure scan
2	The `IP` s to scan. Every `IP` listed here must be white listed in `SecHub` project. The given example with `127.0.0.1` represents only an example and will always not work because scanners do not scan them self.

2.1.9. Data section

With the data section users are able to

define binary and source uploads
reference the same by muliple scan types in one job

The scan configurations can reference the name data configuration elements by defining the array attribute "use" with a list of references.

{
  // ..scan definition
  "use" : [ "reference-name-1","reference-name-2", ... ] (1)
}

1	the list of referenced data configurations . The referenced names must exist.

Here are some links to examples which are using data inside their configurations:

License scan for binaries
License scan for sources
License scan for sources combined with code scan
OpenAPI web scan

The next figure shows an example which presents all possibilities (for simplicity the source and binary configuration arrays do contain only just one entry):

General JSON syntax

{
  "data": { (1)
    "sources": [
      { (2)
        "name": "reference-name-sources-1", (3)
        "fileSystem": { (4)
          "files": [ (5)
            "somewhere/file1.txt",
            "somewhere/file2.txt"
          ],
          "folders": [ (6)
            "somewhere/subfolder1",
            "somewhere/subfolder2"
          ]
        },
        "excludes": [ (7)
          "**/mytestcode/**",
          "**/documentation/**"
        ],
        "additionalFilenameExtensions": [ (8)
          ".cplusplus",
          ".py9"
        ]
      }
    ],
    "binaries": [
      { (9)
        "name": "reference-name-binaries-1", (3)
        "fileSystem": {
          "files": [ (5)
            "somewhere/file1.dll",
            "somewhere/file2.a"
          ],
          "folders": [ (6)
            "somewhere/bin/subfolder1",
            "somewhere/bin/subfolder2"
          ]
        }
      }
    ]
  }
}

1	`data`: The main element for data configuration.
2	`sources`: Inside this array multiple source data definitions can be listed
3	`name`: Is a unique name for the data configuration element. The name must be unique inside the whole SecHub configuration file! Allowed characters are `a-z`,`0-9` and the special characters `_` and `-`.
4	`fileSystem`: Describes fileystem parts which are available inside this data configuration element
5	`files`: An array containing file paths to use for uploading dedicated files
6	`folders`: An array containing folder paths to use for uploading dedicated folders
7	`excludes`: Exclude directories (optional) - see code scan for details. The excludes work for sources and binaries the same way.
8	`additionalFilenameExtensions` Introduce additional file name extensions. See code scan for details about default behaviour for sources.
9	`sources`: Inside this array multiple binary data definitions can be listed.

2.1.10. MetaData

The SecHub configuration file can have optional meta data.

2.1.10.1. Labels

With labels a user is able to add additional information to the scan configuration which end up in the report as key value pairs.

Using the SecHub client, you can also pass labels via command line or environment variables.

The next figure shows an example which presents all possibilities (for simplicity other configuration elements are removed).

General JSON syntax

{
  "metaData": { (1)
    "labels": { (2)
      "Example1": (3)
      "The labels are alphabetically sorted!", (4)
      "Example1.1": "Values can be any text."
    }
  }
}

1	`metaData`: The main element for meta data configuration. It is optional.
2	`labels`: Inside this element the user can define labels as key value pairs. maximum allowed entries per configuration file: 20
3	represents the label key. allowed are characters `A-Z`,`a-z`,`0-9` and the special characters `_` , `-` and `.` minimum length: 1 character maximum length: 30 characters
4	represents the label value. can contain any text (content will be escaped accordingly in reports) minimum length: 0 characters maximum length: 150 characters

2.2. Rest API documentation

2.2.1. Overview

2.2.1.1. Anonymous

All these usecases handling anonymous access.

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

2.2.1.2. User administration

Usecases handling administration of users

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

2.2.1.3. Project administration

Usecases for project administration

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

2.2.1.4. User profile

User actions belonging to their profiles

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

2.2.1.5. Sechub execution

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

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

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

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

2.2.1.7. Job administration

Usecases about job administration

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

2.2.1.8. Testing

Some use cases for testing

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

2.2.1.9. Configuration

Usecases for configuration parts

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

2.2.1.10. Other

All other use cases

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

2.2.2. Check if the server is alive and running.

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

2.2.2.1. HEAD variant

Definition

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

Example

Curl request

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

Response body
(empty)

2.2.2.2. GET variant

Definition

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

Example

Curl request

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

Response body
(empty)

2.2.3. Admin lists all users

REST API for usecase UC_004-Admin lists all users

Definition

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

Response fields

Path Type Description

Path	Type	Description
`[]`	`Array`	List of user Ids

[]

Array

List of user Ids

Example

Curl request

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

Response body

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

2.2.4. Admin assigns user to project

REST API for usecase UC_015-Admin assigns user to project

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.5. Admin unassigns user from project

REST API for usecase UC_016-Admin unassigns user from project

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.6. Admin shows user details

REST API for usecase UC_017-Admin shows user details

Definition

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

Path parameters

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

Request headers

Name

Description

Response fields

Path Type Description

userId

String

The name of the user

email

String

The email address of the user

superAdmin

Boolean

True, when this user is a super administrator

projects

Array

The projects the user has access to

ownedProjects

Array

The projects the user is owner of

Example

Curl request

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

Response body

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

2.2.7. Admin deletes a user

REST API for usecase UC_018-Admin deletes a user

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.8. Admin shows project details

REST API for usecase UC_021-Admin shows project details

Definition

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

Path parameters

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

Request headers

Name

Description

Response fields

Path Type Description

projectId

String

The name of the project

users

Array

A list of all users having access to the project

owner

String

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

whiteList

Array

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

metaData

Object

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

metaData.key1

String

An arbitrary metadata key

accessLevel

String

The project access level

description

String

The project description.

Example

Curl request

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

Response body

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

2.2.9. Admin downloads all details about a scan job

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

Definition

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

Path parameters

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

Example

Curl request

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

2.2.10. Admin grants admin rights to user

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

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.11. Admin revokes admin rights from an admin

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

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.12. Admin lists all admins

REST API for usecase UC_029-Admin lists all admins

Definition

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

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

List of admin Ids

Example

Curl request

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

Response body

["admin1","admin2"]

2.2.13. Admin changes owner of a project

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

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.14. Admin updates user email address

REST API for usecase UC_063-Admin updates user email address

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.15. Admin shows user details for email address

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

Definition

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

Path parameters

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

Request headers

Name Description

Authorization

Basic authentication credentials

Response fields

Path Type Description

userId

String

The name of the user

email

String

The mail address of the user

superAdmin

Boolean

True, when this user is a super administrator

projects

Array

The projects the user has access to

ownedProjects

Array

The projects the user is owner of

Example

Curl request

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

Response body

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

2.2.16. Admin creates a project

REST API for usecase UC_013-Admin creates a project

Definition

Table 27. General request information
	Value
Path	/api/admin/project
Method	POST
Status code	201 CREATED

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

name

String

Name of the project to create. Is also used as a unique ID!

description

String

The description of the project.

owner

String

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

whiteList.uris

Array

All URIs used now for whitelisting. Former parts will be replaced completely!

metaData

Object

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

metaData.*

String

An arbitrary metadata key-value pair

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0", "name":"projectId", "description":"A description of the project.", "owner":"ownerName1", "whiteList":{"uris":["192.168.1.1","https://my.special.server.com/myapp1/"]}, "metaData":{"key1":"value1", "key2":"value2"}}'

Response body
(empty)

2.2.17. Admin lists all projects

REST API for usecase UC_014-Admin lists all projects

Definition

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

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

List of project Ids

Example

Curl request

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

Response body

["project1","project2"]

2.2.18. Admin deletes a project

REST API for usecase UC_020-Admin deletes a project

Definition

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

Path parameters

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

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.19. Update project whitelist

REST API for usecase UC_022-Update project whitelist

Definition

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

Path parameters

Table 32. https://localhost:8081/api/admin/project/{projectId}/whitelist
Parameter	Description
`projectId`	The id of the project for which whitelist shall be updated

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

whiteList.uris

Array

All URIS used now for whitelisting. Former parts will be replaced completely!

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/whitelist' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0", "whiteList":{"uris":["192.168.1.1","https://my.special.server.com/myapp1/"]}}'

Response body
(empty)

2.2.20. Admin shows scan logs for project

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

Definition

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

Path parameters

Table 34. https://localhost:8081/api/admin/project/{projectId}/scan/logs
Parameter	Description
`projectId`	The project Id

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

An array of scan log summary entries

[].executedBy

String

The user id of the user which executed the scan

[].started

String

The timestamp when the scan was started

[].ended

String

The timestamp when the scan was ended

[].status

String

A status field about scan situation

[].sechubJobUUID

String

The uuid of corresponding sechub Job.

Example

Curl request

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

Response body

[{"sechubJobUUID":"71d49f6c-c9a3-4a82-b53f-21ac50cc2e1f","executedBy":"spartakus","started":"2024-04-29T15:29:56.69565274","ended":"2024-04-30T15:29:56.695671105","status":"OK"}]

2.2.21. Update project metadata

REST API for usecase UC_059-Update project metadata

Definition

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

Path parameters

Table 36. https://localhost:8081/api/admin/project/{projectId}/metadata
Parameter	Description
`projectId`	The id of the project for which metadata shall be updated

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

metaData

Object

Metadata object. Contains key-value pairs.

metaData.key1

String

An arbitrary metadata key.

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/project/projectId1/metadata' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0", "metaData":{"key1":"value1"}}'

Response body
(empty)

2.2.22. Admin changes project description

REST API for usecase UC_061-Admin changes project description

Definition

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

Path parameters

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

Request headers

Name

Description

Response fields

Path Type Description

projectId

String

The name of the project.

users

Array

A list of all users having access to the project.

owner

String

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

whiteList

Array

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

metaData

Object

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

metaData.key1

String

An arbitrary metadata key.

accessLevel

String

The project access level

description

String

The project description.

Example

Curl request

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

Response body

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

2.2.23. Admin changes project access level

REST API for usecase UC_062-Admin changes project access level

Definition

Table 39. General request information
	Value
Path	/api/admin/project/{projectId}/accesslevel/{projectAccessLevel}
Method	POST
Status code	200 OK

Path parameters

Table 40. https://localhost:8081/api/admin/project/{projectId}/accesslevel/{projectAccessLevel}
Parameter	Description
`projectId`	The id for project
`projectAccessLevel`	The new project access level. Accepted values: full(Full access to project, no restrictions), read_only(Users have only read access to existing data, No new jobs possible), none(Users have no access at all.)

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.24. User clicks link to get new api token

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

Definition

Table 41. General request information
	Value
Path	/api/anonymous/apitoken/{oneTimeToken}
Method	GET
Status code	200 OK

Path parameters

Table 42. https://localhost:8081/api/anonymous/apitoken/{oneTimeToken}
Parameter	Description
`oneTimeToken`	A one time token the user has got by a previous mail from sechub server

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/apitoken/oneTimeToken1' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.25. User creates a new sechub job

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

2.2.25.1. Code Scan variant

Definition

Table 43. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 44. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

codeScan

Object

Code scan configuration block

codeScan.use

Array

Referenced data configuration objects by their unique names

codeScan.fileSystem.folders

Array

Code scan sources from given file system folders

codeScan.fileSystem.files

Array

Code scan sources from given file system files

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"codeScan":{"fileSystem":{"files":[],"folders":["testproject1/src/main/java","testproject2/src/main/java"]},"use":[]},"apiVersion":"1.0"}'

Response body

{"jobId":"07bca11c-137c-479e-b611-1750e78a48cf"}

2.2.25.2. Code Scan using data section variant

Definition

Table 45. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 46. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

codeScan

Object

Code scan configuration block

codeScan.use

Array

Referenced data configuration objects by their unique names

data.sources[].name

String

Unique reference name

data.sources[].fileSystem.folders[]

Array

Sources from given file system folders

data.sources[].fileSystem.files[]

Array

Sources from given file system files

data.binaries[].name

String

Unique reference name

data.binaries[].fileSystem.folders[]

Array

Binaries from given file system folders

data.binaries[].fileSystem.files[]

Array

Binaries from given file system files

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"codeScan":{"use":["source-ref-name","bin-ref-name"]},"data":{"sources":[{"fileSystem":{"files":["testproject1/src/other/example/php-example.php"],"folders":["testproject1/src/main/java","testproject2/src/main/java"]},"name":"source-ref-name"}],"binaries":[{"fileSystem":{"files":["testproject1/build/other/native.dll"],"folders":["testproject1/build/kotlin","testproject1/build/kotlin"]},"name":"bin-ref-name"}]},"apiVersion":"1.0"}'

Response body

{"jobId":"0d3b29a9-cb52-4de5-98eb-195031c53fb8"}

2.2.25.3. Secret scan variant

Definition

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

Path parameters

Table 48. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

secretScan

Object

Secret scan configuration block

secretScan.use

Array

Referenced data configuration objects by their unique names

data.sources[].name

String

Unique reference name

data.binaries[].name

String

Unique reference name

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"data":{"sources":[{"name":"source-ref-name"}],"binaries":[{"name":"bin-ref-name"}]},"secretScan":{"use":["source-ref-name","bin-ref-name"]},"apiVersion":"1.0"}'

Response body

{"jobId":"f46fc8f3-05a4-48c6-b3b6-9ec9ae9e2581"}

2.2.25.4. License scan variant

Definition

Table 49. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 50. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

licenseScan

Object

License scan configuration block

licenseScan.use

Array

Referenced data configuration objects by their unique names

data.sources[].name

String

Unique reference name

data.binaries[].name

String

Unique reference name

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"data":{"sources":[{"name":"source-ref-name"}],"binaries":[{"name":"bin-ref-name"}]},"licenseScan":{"use":["source-ref-name","bin-ref-name"]},"apiVersion":"1.0"}'

Response body

{"jobId":"9fe77eba-e3bb-4345-a549-93a5dfed520e"}

2.2.25.5. Infrastructure scan variant

Definition

Table 51. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 52. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

infraScan

Object

Infrastructure configuration block

infraScan.uris

Array

Infrastructure URIs to scan for

infraScan.ips

Array

Infrastructure IPs to scan for

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"infraScan":{"uris":["https://localhost"],"ips":["127.0.0.1"]},"apiVersion":"1.0"}'

Response body

{"jobId":"1b431868-47a0-440e-946c-23f09615f2da"}

2.2.25.6. Web scan anonymous variant

Definition

Table 53. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 54. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.maxScanDuration.duration

Number

Duration of the scan as integer

webScan.maxScanDuration.unit

String

Unit of the duration. Possible values are: millisecond(s), second(s), minute(s), hour(s), day(s)

webScan.includes[]

Array

Include URL sub-paths to scan. Example: /hidden

webScan.excludes[]

Array

Exclude URL sub-paths to scan. Example: /admin

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"maxScanDuration":{"duration":1,"unit":"HOUR"},"url":"https://localhost/mywebapp/login","includes":["/admin","/hidden","/admin.html"],"excludes":["/public/media","/static","/contaxt.html"]},"apiVersion":"1.0"}'

Response body

{"jobId":"7bb13c95-83bb-458d-b472-6d8e83ff550c"}

2.2.25.7. Web scan with api definition variant

Definition

Table 55. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 56. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.api.type

String

Type of the API definition files that will be provided

webScan.api.use

Array

Reference to the data section containing the API definition files. Always use 'sources' with 'files' instead 'folders'.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"api":{"type":"OPEN_API","use":["openApi-file-reference"]},"url":"https://localhost/mywebapp/login"},"apiVersion":"1.0"}'

Response body

{"jobId":"336fb177-98d5-494c-aff1-9cc61d2025b6"}

2.2.25.8. Web scan with client certificate definition variant

Definition

Table 57. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 58. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.clientCertificate.password

String

Password the client certificate file is protected with

webScan.clientCertificate.use

Array

Reference to the data section containing the client certificate definition file. Always use 'sources' with a single 'file' instead 'folders'.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"url":"https://localhost/mywebapp","clientCertificate":{"password":"example-cert-password","use":["client-certificate-file-reference"]}},"apiVersion":"1.0"}'

Response body

{"jobId":"b976c0d9-3633-4a96-8003-0eeefbe99e44"}

Definition

Table 59. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 60. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.login

Object

Webscan login definition

webScan.login.url

String

webScan.login.basic

Object

basic login definition

webScan.login.basic.user

String

username

webScan.login.basic.password

String

password

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"login":{"url":"https://localhost/mywebapp/login","basic":{"user":"username1","password":"password1"}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'

Response body

{"jobId":"a744c96b-d5d0-48e8-bc0e-7ddd1d75b62f"}

Definition

Table 61. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 62. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.login

Object

Webscan login definition

webScan.login.url

String

webScan.login.form

Object

form login definition

webScan.login.form.script

Object

script

webScan.login.form.script.pages[].actions[].type

String

action type: username, password, input, click, wait

webScan.login.form.script.pages[].actions[].selector

String

css selector

webScan.login.form.script.pages[].actions[].value

String

value

webScan.login.form.script.pages[].actions[].description

String

description

webScan.login.form.script.pages[].actions[].unit

String

the time unit to wait: millisecond, second, minute, hour, day.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"login":{"url":"https://localhost/mywebapp/login","form":{"script":{"pages":[{"actions":[{"type":"USERNAME","selector":"#example_login_userid","value":"username1","description":"the username field"},{"type":"INPUT","selector":"#example_login_email_id","value":"user@example.com","description":"The email id field."}]},{"actions":[{"type":"WAIT","value":"2345","unit":"MILLISECOND"},{"type":"PASSWORD","selector":"#example_login_pwd","value":"Super$ecret234!"},{"type":"CLICK","selector":"#example_login_button"}]}]}}},"url":"https://localhost/mywebapp"},"apiVersion":"1.0"}'

Response body

{"jobId":"ab7fafe6-162d-45c3-9cf7-c29026e9b937"}

2.2.25.11. Web Scan headers variant

Definition

Table 63. General request information
	Value
Path	/api/project/{projectId}/job
Method	POST
Status code	200 OK

Path parameters

Table 64. https://localhost:8081/api/project/{projectId}/job
Parameter	Description
`projectId`	The unique id of the project id where a new sechub job shall be created

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

webScan

Object

Webscan configuration block

webScan.url

String

Webscan URI to scan for

webScan.headers

Array

List of HTTP headers. Can be used for authentication or anything else.

webScan.headers[].name

String

Name of the defined HTTP header.

webScan.headers[].value

String

Value of the defined HTTP header. Either specify the header value directly here or reference a data section with 'use' e.g. if the value is to big, but never specify both.

webScan.headers[].use

Array

Reference to the data section containing a file with the value for this header, e.g if the value is to big for the sechub configuration. Always use 'sources' with a single 'file' instead 'folders'.

webScan.headers[].onlyForUrls[]

Array

Optional list of URLs this header shall be used for like: https://mywebapp.com/path/. Can contain wildcards like: https://mywebapp.com/path/<*>/with/wildcard

webScan.headers[].sensitive

Boolean

Defines header masking. If 'true' the header value will be replaced with '**' inside the report, 'false' will show the value as is. Default is set to 'true'.

Response fields

Path Type Description

jobId

String

A unique job id

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"webScan":{"url":"https://localhost/mywebapp","headers":[{"name":"api-token","value":"secret","onlyForUrls":["https://localhost/mywebapp/admin","https://localhost/mywebapp/<*>/profile","https://localhost/mywebapp/blog/<*>"],"sensitive":true,"use":["header-value-file-ref-for-big-tokens"]}]},"apiVersion":"1.0"}'

Response body

{"jobId":"e646cfbd-5527-4754-aa27-b524e411693c"}

2.2.26. User uploads source code

REST API for usecase UC_006-User uploads source code

Definition

Table 65. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}/sourcecode
Method	POST
Status code	200 OK

Path parameters

Table 66. https://localhost:8081/api/project/{projectId}/job/{jobUUID}/sourcecode
Parameter	Description
`projectId`	The id of the project where sourcecode shall be uploaded for
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/6d308234-2ad5-4628-a79f-e907b02ae48f/sourcecode?checkSum=checkSumValue' -i -X POST \
    -H 'Content-Type: multipart/form-data;charset=UTF-8' \
    -F 'file=PK  
      �<M                       test1.txtPK  ?
      �<M                     $               test1.txt
            ��IW�  ��IW�  ��IW� PK          [   '     '

Response body
(empty)

2.2.27. User approves sechub job

REST API for usecase UC_007-User approves sechub job

Definition

Table 67. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}/approve
Method	PUT
Status code	200 OK

Path parameters

Table 68. https://localhost:8081/api/project/{projectId}/job/{jobUUID}/approve
Parameter	Description
`projectId`	The id of the project where sechub job shall be approved
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/c289eafc-3409-421f-a65a-6efc02f14406/approve' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.28. User checks sechub job state

REST API for usecase UC_009-User checks sechub job state

Definition

Table 69. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 70. https://localhost:8081/api/project/{projectId}/job/{jobUUID}
Parameter	Description
`projectId`	The id of the project where sechub job was started for
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name

Description

Response fields

Path Type Description

jobUUID

String

The job uuid

created

String

Creation timestamp of job

started

String

Start timestamp of job execution

ended

String

End timestamp of job execution

owner

String

Owner / initiator of job

state

String

State of job

result

String

Result of job

trafficLight

String

Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/dd67a2c2-74ae-4032-8ea6-7e6c6561f099' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"jobUUID":"dd67a2c2-74ae-4032-8ea6-7e6c6561f099","owner":"CREATOR1","created":"","started":"2024-04-30T15:14:55.350966931","ended":"2024-04-30T15:29:55.350989543","state":"ENDED","result":"OK","trafficLight":"GREEN"}

2.2.29. User downloads sechub job report

REST API for usecase UC_010-User downloads sechub job report

2.2.29.1. JSON variant

Definition

Table 71. General request information
	Value
Path	/api/project/{projectId}/report/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 72. https://localhost:8081/api/project/{projectId}/report/{jobUUID}
Parameter	Description
`projectId`	The project Id
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/report/aa193217-8ee5-42f5-9788-6b38b24b2783' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

2.2.29.2. HTML variant

Definition

Table 73. General request information
	Value
Path	/api/project/{projectId}/report/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 74. https://localhost:8081/api/project/{projectId}/report/{jobUUID}
Parameter	Description
`projectId`	The project Id
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/report/2eabeea2-0b97-42dc-a6d3-e318d4ad1ca5' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/xhtml+xml'

2.2.30. User marks false positives for finished sechub job

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

Definition

Table 75. General request information
	Value
Path	/api/project/{projectId}/false-positives
Method	PUT
Status code	200 OK

Path parameters

Table 76. https://localhost:8081/api/project/{projectId}/false-positives
Parameter	Description
`projectId`	The projectId of the project where users adds false positives for

Request headers

Name

Description

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

type

String

The type of the json content. Currently only accepted value is 'falsePositiveJobDataList'.

jobData

Array

Job data list containing false positive setup based on former jobs

jobData[].jobUUID

String

SecHub job uuid where finding was

jobData[].findingId

Number

SecHub finding identifier - identifies problem inside the job which shall be markeda as a false positive. ATTENTION: at the moment only code scan false positive handling is supported. Infra and web scan findings will lead to a non accepted error!

jobData[].comment

String

A comment describing why this is a false positive

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0","type":"falsePositiveJobDataList","jobData":[{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"an optional comment why this is a false positive..."}]}'

Response body
(empty)

2.2.31. User unmarks existing false positive definitons

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

Definition

Table 77. General request information
	Value
Path	/api/project/{projectId}/false-positive/{jobUUID}/{findingId}
Method	DELETE
Status code	200 OK

Path parameters

Table 78. https://localhost:8081/api/project/{projectId}/false-positive/{jobUUID}/{findingId}
Parameter	Description
`projectId`	The project id
`jobUUID`	Job uuid
`findingId`	Finding id - in combination with job UUID this defines the false positive to remove

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/false-positive/f1d02a9d-5e1b-4f52-99e5-401854ccf936/42' -i -u 'user:secret' -X DELETE

Response body
(empty)

2.2.32. User fetches false positive configuration of project

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

Definition

Table 79. General request information
	Value
Path	/api/project/{projectId}/false-positives
Method	GET
Status code	200 OK

Path parameters

Table 80. https://localhost:8081/api/project/{projectId}/false-positives
Parameter	Description
`projectId`	The project id

Request headers

Name

Description

Response fields

Path Type Description

falsePositives

Array

Job data list containing false positive setup based on former jobs

falsePositives[].author

String

User id of author who created false positive

falsePositives[].created

String

Creation timestamp

falsePositives[].metaData

Object

Meta data for this false positive

falsePositives[].metaData.scanType

String

Scan type - e.g. codeScan

falsePositives[].metaData.name

String

Name of origin finding marked as false positive

falsePositives[].metaData.cweId

Number

CWE (common weakness enumeration). For code scans this is always set.

falsePositives[].metaData.cveId

String

CVE (common vulnerability and exposures). For infra scans this is always set.

falsePositives[].metaData.owasp

String

OWASP At least this field must be set for web scans when no cwe identifier is defined.

falsePositives[].metaData.severity

String

Severity of origin report entry marked as false positive

falsePositives[].metaData.code

Object

Code part. Only available for scan type 'codeScan'

falsePositives[].metaData.code.start

Object

entry point

falsePositives[].metaData.code.start.location

String

location of code

falsePositives[].metaData.code.start.relevantPart

String

relevant part of source vulnerability

falsePositives[].metaData.code.start.sourceCode

String

source code

falsePositives[].metaData.code.end

Object

end point (sink)

falsePositives[].metaData.code.end.location

String

location of code

falsePositives[].metaData.code.end.relevantPart

String

relevant part of source vulnerability

falsePositives[].metaData.code.end.sourceCode

String

source code

falsePositives[].jobData

Object

Job data parts, can be used as key to identify false positives

falsePositives[].jobData.jobUUID

String

SecHub job uuid where finding was

falsePositives[].jobData.findingId

Number

falsePositives[].jobData.comment

String

A comment from author describing why this was marked as a false positive

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/false-positives' -i -u 'user:secret' -X GET

Response body

{"falsePositives":[{"jobData":{"jobUUID":"f1d02a9d-5e1b-4f52-99e5-401854ccf936","findingId":42,"comment":"Only used in documentation build not in deployment"},"author":"developer1","metaData":{"scanType":"codeScan","name":"Absolute Path Traversal","severity":"MEDIUM","code":{"start":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"args","sourceCode":"\tpublic static void main(String[] args) throws Exception {"},"end":{"location":"java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java","relevantPart":"File","sourceCode":"\t\tFile documentsGenFolder = new File(path);"}},"cweId":36},"created":"2020-06-12 11:53:15"}]}

2.2.33. User uploads binaries

REST API for usecase UC_069-User uploads binaries

Definition

Table 81. General request information
	Value
Path	/api/project/{projectId}/job/{jobUUID}/binaries
Method	POST
Status code	200 OK

Path parameters

Table 82. https://localhost:8081/api/project/{projectId}/job/{jobUUID}/binaries
Parameter	Description
`projectId`	The id of the project for which the binaries are uploaded for
`jobUUID`	The SecHub jobUUID. During the job creation this unique job identifier is automatically generated by SecHub.

Request headers

Name Description

x-file-size

The file size of the tar-archive to upload in bytes. Needs to be a positive integer value.

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/job/f946c2e6-4c00-4372-b1a1-2f5ba9090ae5/binaries' -i -X POST \
    -H 'Content-Type: multipart/form-data;charset=UTF-8' \
    -H 'x-file-size: 10240' \
    -F 'file=test1.txt                                                                                           0000664 0001750 0001750 00000000000 13353454574 012170  0                                                                                                    ustar   albert                          albert                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 ' \
    -F 'checkSum=checkSumValue'

Response body
(empty)

2.2.34. User downloads job report in SPDX format

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

Definition

Table 83. General request information
	Value
Path	/api/project/{projectId}/report/spdx/{jobUUID}
Method	GET
Status code	200 OK

Path parameters

Table 84. https://localhost:8081/api/project/{projectId}/report/spdx/{jobUUID}
Parameter	Description
`projectId`	The project Id
`jobUUID`	The job UUID

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/report/spdx/2c623362-da14-4140-9199-8f6138179065' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json'

2.2.35. User self registration

REST API for usecase UC_001-User self registration

Definition

Table 85. General request information
	Value
Path	/api/anonymous/signup
Method	POST
Status code	200 OK

Request fields

Path Type Description

apiVersion

String

The api version, currently only 1.0 is supported

userId

String

Wanted userid, the userid must be lowercase only!

emailAddress

String

Email address

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/signup' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"apiVersion":"1.0","userId":"valid_userid","emailAddress":"valid_mailaddress@example.org"}'

Response body
(empty)

2.2.36. Admin lists open user signups

REST API for usecase UC_002-Admin lists open user signups

Definition

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

Request headers

Name

Description

Response fields

Path Type Description

[]

Array

List of user signups

[].userId

String

The user id

[].emailAddress

String

The email address

Example

Curl request

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

Response body

[{"userId":"johnsmith","emailAddress":"john.smith@example.com"},{"userId":"janesmith","emailAddress":"jane.smith@example.com"}]

2.2.37. Admin applies self registration

REST API for usecase UC_003-Admin applies self registration

Definition

Table 87. General request information
	Value
Path	/api/admin/signup/accept/{userId}
Method	POST
Status code	201 CREATED

Path parameters

Table 88. https://localhost:8081/api/admin/signup/accept/{userId}
Parameter	Description
`userId`	The userId of the signup which shall be accepted

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

REST API for usecase UC_019-Admin deletes user signup

Definition

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

Path parameters

Table 90. https://localhost:8081/api/admin/signup/{userId}
Parameter	Description
`userId`	The userId of the signup which shall be deleted

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.39. User requests new API token

REST API for usecase UC_024-User requests new API token

Definition

Table 91. General request information
	Value
Path	/api/anonymous/refresh/apitoken/{emailAddress}
Method	POST
Status code	200 OK

Path parameters

Table 92. https://localhost:8081/api/anonymous/refresh/apitoken/{emailAddress}
Parameter	Description
`emailAddress`	Email address for user where api token shall be refreshed.

Example

Curl request

$ curl 'https://sechub.example.com/api/anonymous/refresh/apitoken/emailAddress@example.com' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.40. Admin lists all running jobs

REST API for usecase UC_023-Admin lists all running jobs

Definition

Table 93. General request information
	Value
Path	/api/admin/jobs/running
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

[].jobUUID

String

The uuid of the running job

[].projectId

String

The name of the project the job is running for

[].owner

String

Owner of the job - means user which triggered it

[].status

String

A status information

[].since

String

Timestamp since when job has been started

[].configuration

String

Configuration used for this job

Example

Curl request

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

Response body

[{"jobUUID":"ae921708-6c4b-4a5e-a8ef-509f3e8c0e0e","projectId":"project-name","owner":"owner-userid","status":"RUNNING","since":"2024-04-30T15:29:59.365613511","configuration":"{ config data }"}]

2.2.41. Admin cancels a job

REST API for usecase UC_034-Admin cancels a job

Definition

Table 94. General request information
	Value
Path	/api/admin/jobs/cancel/{jobUUID}
Method	POST
Status code	200 OK

Path parameters

Table 95. https://localhost:8081/api/admin/jobs/cancel/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/cancel/4c2e06e5-bda5-4235-b58e-e61fb66083d8' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.42. Admin restarts a job

REST API for usecase UC_041-Admin restarts a job

Definition

Table 96. General request information
	Value
Path	/api/admin/jobs/restart/{jobUUID}
Method	POST
Status code	200 OK

Path parameters

Table 97. https://localhost:8081/api/admin/jobs/restart/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/restart/d0073ed1-3784-42ba-a3f8-d4a68178b60f' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.43. Admin restarts a job (hard)

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

Definition

Table 98. General request information
	Value
Path	/api/admin/jobs/restart-hard/{jobUUID}
Method	POST
Status code	200 OK

Path parameters

Table 99. https://localhost:8081/api/admin/jobs/restart-hard/{jobUUID}
Parameter	Description
`jobUUID`	The job UUID

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/jobs/restart-hard/e4017208-f80f-40d1-8466-0a8144b6941e' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.44. User defines mock data configuration for project

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

Definition

Table 100. General request information
	Value
Path	/api/project/{projectId}/mockdata
Method	PUT
Status code	200 OK

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/mockdata' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/json' \
    -d '{"codeScan":{"result":"RED"},"webScan":{"result":"YELLOW"},"infraScan":{"result":"GREEN"}}'

Response body
(empty)

2.2.45. User retrieves mock data configuration for project

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

Definition

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

Request headers

Name

Description

Example

Curl request

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

Response body

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

2.2.46. Admin updates mapping configuration

REST API for usecase UC_037-Admin updates mapping configuration

Definition

Table 102. General request information
	Value
Path	/api/admin/config/mapping/{mappingId}
Method	PUT
Status code	200 OK

Path parameters

Table 103. https://localhost:8081/api/admin/config/mapping/{mappingId}
Parameter	Description
`mappingId`	The mappingID, identifiying which mapping shall be updated

Request headers

Name

Description

Request fields

Path Type Description

entries.[].pattern

String

Pattern

entries.[].replacement

String

Replacement

entries.[].comment

String

Comment

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/mapping/checkmarx.newproject.teamid.mapping' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"entries":[{"pattern":"testproject_*","replacement":"8be4e3d4-6b53-4636-b65a-949a9ebdf6b9","comment":"testproject-team"},{"pattern":".*","replacement":"3be4e3d2-2b55-2336-b65a-949b9ebdf6b9","comment":"default-team"}]}'

Response body
(empty)

2.2.47. Admin fetches mapping configuration

REST API for usecase UC_038-Admin fetches mapping configuration

Definition

Table 104. General request information
	Value
Path	/api/admin/config/mapping/{mappingId}
Method	GET
Status code	200 OK

Path parameters

Table 105. https://localhost:8081/api/admin/config/mapping/{mappingId}
Parameter	Description
`mappingId`	The mapping Id

Request headers

Name

Description

Response fields

Path Type Description

entries.[].pattern

String

Pattern

entries.[].replacement

String

Replacement

entries.[].comment

String

Comment

Example

Curl request

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

Response body

{"entries":[{"pattern":"testproject_*","replacement":"8be4e3d4-6b53-4636-b65a-949a9ebdf6b9","comment":"testproject-team"},{"pattern":".*","replacement":"3be4e3d2-2b55-2336-b65a-949b9ebdf6b9","comment":"default-team"}]}

2.2.48. Admin creates an executor configuration

REST API for usecase UC_047-Admin creates an executor configuration

Definition

Table 106. General request information
	Value
Path	/api/admin/config/executor
Method	POST
Status code	201 CREATED

Request headers

Name

Description

Request fields

Path Type Description

name

String

A name for this configuration

productIdentifier

String

Executor product identifier

executorVersion

Number

Executor version

enabled

Boolean

Enabled state of executor, per default false

setup.baseURL

String

Base URL to the product

setup.credentials.user

String

User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable

setup.credentials.password

String

Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable

setup.jobParameters[].key

String

Job parameter key

setup.jobParameters[].value

String

Job parameter value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"name":"PDS gosec config 1","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productXYZ.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"},{"key":"example.key2","value":"Another value"}]}}'

Response body

27b8f5fc-3892-434e-8594-0d80a11e373f

2.2.49. Admin deletes executor configuration

REST API for usecase UC_048-Admin deletes executor configuration

Definition

Table 107. General request information
	Value
Path	/api/admin/config/executor/{uuid}
Method	DELETE
Status code	200 OK

Path parameters

Table 108. https://localhost:8081/api/admin/config/executor/{uuid}
Parameter	Description
`uuid`	The configuration uuid

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor/d1622a9a-60cd-451e-9e50-296894a03fc0' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.50. Admin fetches executor configuration list

REST API for usecase UC_049-Admin fetches executor configuration list

Definition

Table 109. General request information
	Value
Path	/api/admin/config/executors
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

type

String

Always executorConfigurationList as an identifier for the list

executorConfigurations[].uuid

String

The uuid of the configuration

executorConfigurations[].name

String

The configuration name

executorConfigurations[].enabled

Boolean

Enabled state of configuration

Example

Curl request

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

Response body

{"executorConfigurations":[{"uuid":"34a78392-d24d-4b8d-b92b-5f98a6aa69d8","name":"example configuration","enabled":true}],"type":"executorConfigurationList"}

2.2.51. Admin fetches executor configuration

REST API for usecase UC_050-Admin fetches executor configuration

Definition

Table 110. General request information
	Value
Path	/api/admin/config/executor/{uuid}
Method	GET
Status code	200 OK

Path parameters

Table 111. https://localhost:8081/api/admin/config/executor/{uuid}
Parameter	Description
`uuid`	The configuration uuid

Request headers

Name

Description

Response fields

Path Type Description

uuid

String

The uuid of this configuration

name

String

The name of this configuration

productIdentifier

String

Executor product identifier

executorVersion

Number

Executor version

enabled

Boolean

Enabled state of executor

setup.baseURL

String

Base URL to the product

setup.credentials.user

String

User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable

setup.credentials.password

String

Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable

setup.jobParameters[].key

String

Job parameter key

setup.jobParameters[].value

String

Job parameter value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor/e08f35c6-c0a5-45d5-8a80-d2b9e0b8c1db' -i -u 'user:secret' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value"}]},"executorVersion":1,"enabled":false,"uuid":"e08f35c6-c0a5-45d5-8a80-d2b9e0b8c1db"}

2.2.52. Admin updates executor configuration setup

REST API for usecase UC_051-Admin updates executor configuration setup

Definition

Table 112. General request information
	Value
Path	/api/admin/config/executor/{uuid}
Method	PUT
Status code	200 OK

Path parameters

Table 113. https://localhost:8081/api/admin/config/executor/{uuid}
Parameter	Description
`uuid`	The configuration uuid

Request headers

Name

Description

Request fields

Path Type Description

name

String

The name of this configuration

productIdentifier

String

Executor product identifier

executorVersion

Number

Executor version

enabled

Boolean

Enabled state of executor, per default false

setup.baseURL

String

Base URL to the product

setup.credentials.user

String

User name, either plain (not recommended) or with env:VARIABLENAME, in last case the user name will be from environment variable

setup.credentials.password

String

Password, either plain (not recommended) or with env:VARIABLENAME, in last case the password will be from environment variable

setup.jobParameters[].key

String

Job parameter key

setup.jobParameters[].value

String

Job parameter value

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/executor/0169bf99-fb43-4ecb-b4b1-451574318b23' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"name":"New name","productIdentifier":"PDS_CODESCAN","executorVersion":1,"enabled":false,"setup":{"baseURL":"https://productNew.example.com","credentials":{"user":"env:EXAMPLE_NEW_USENAME","password":"env:EXAMPLE_NEW_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]}}'

Response body
(empty)

2.2.53. Admin creates an execution profile

REST API for usecase UC_052-Admin creates an execution profile

Definition

Table 114. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	POST
Status code	201 CREATED

Path parameters

Table 115. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Request fields

Path Type Description

description

String

A short description for the profile

enabled

Boolean

Enabled state of profile, default is false

configurations[]

Array

Configurations can be linked at creation time as well - see update description

projectIds[]

Array

Projects can be linked by their ids at creation time as well - see update description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/new-profile-1' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"description":"a short description for profile","configurations":[],"projectIds":[],"enabled":false}'

Response body
(empty)

2.2.54. Admin deletes execution profile

REST API for usecase UC_053-Admin deletes execution profile

Definition

Table 116. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	DELETE
Status code	200 OK

Path parameters

Table 117. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/profile-to-delete-1' -i -u 'user:secret' -X DELETE \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.55. Admin updates execution profile

REST API for usecase UC_054-Admin updates execution profile

Definition

Table 118. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	PUT
Status code	200 OK

Path parameters

Table 119. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Request fields

Path Type Description

description

String

A short description for the profile

enabled

Boolean

Enabled state of profile, default is false

configurations[].uuid

String

Add uuid for configuration to use here

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/execution/profile/existing-profile-1' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"description":"changed description","configurations":[{"uuid":"fb93a42f-7399-44f6-be33-b2686be472fb","executorVersion":0,"enabled":false,"setup":{"credentials":{},"jobParameters":[]}}],"enabled":true}'

Response body
(empty)

2.2.56. Admin fetches execution profile

REST API for usecase UC_055-Admin fetches execution profile

Definition

Table 120. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}
Method	GET
Status code	200 OK

Path parameters

Table 121. https://localhost:8081/api/admin/config/execution/profile/{profileId}
Parameter	Description
`profileId`	The profile id

Request headers

Name

Description

Response fields

Path Type Description

description

String

A short description for the profile

enabled

Boolean

Enabled state of profile, default is false

configurations[].uuid

String

uuid of configuration

configurations[].name

String

name of configuration

configurations[].enabled

Boolean

enabled state of this config

configurations[].productIdentifier

String

executed product

configurations[].executorVersion

Number

executor version

projectIds[]

Array

Projects can be linked by their ids here

Example

Curl request

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

Response body

{"description":"a description","enabled":true,"configurations":[{"name":"New name","productIdentifier":"PDS_CODESCAN","setup":{"baseURL":"https://product.example.com","credentials":{"user":"env:EXAMPLE_USENAME","password":"env:EXAMPLE_PASSWORD"},"jobParameters":[{"key":"example.key1","value":"A value but changed. Remark: the other parameter (example.key2) has been removed by this call"}]},"executorVersion":1,"enabled":false,"uuid":"c92808e3-297b-43fd-97d2-f0c389c66be7"}],"projectIds":["project-1","project-2"]}

2.2.57. Admin fetches execution profile list

REST API for usecase UC_056-Admin fetches execution profile list

Definition

Table 122. General request information
	Value
Path	/api/admin/config/execution/profiles
Method	GET
Status code	200 OK

Request headers

Name

Description

Response fields

Path Type Description

type

String

Always executorProfileList as an identifier for the list

executionProfiles[].id

String

The profile id

executionProfiles[].description

String

A profile description

executionProfiles[].enabled

Boolean

Enabled state of profile

Example

Curl request

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

Response body

{"executionProfiles":[{"id":"profile1","description":"A short decription for profile1","enabled":false},{"id":"profile2","description":"A short decription for profile2","enabled":false}],"type":"executionProfileList"}

2.2.58. Admin assigns execution profile to project

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

Definition

Table 123. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}/project/{projectId}
Method	POST
Status code	201 CREATED

Path parameters

Table 124. https://localhost:8081/api/admin/config/execution/profile/{profileId}/project/{projectId}
Parameter	Description
`projectId`	The project id
`profileId`	The profile id

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.59. Admin unassigns execution profile from project

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

Definition

Table 125. General request information
	Value
Path	/api/admin/config/execution/profile/{profileId}/project/{projectId}
Method	DELETE
Status code	200 OK

Path parameters

Table 126. https://localhost:8081/api/admin/config/execution/profile/{profileId}/project/{projectId}
Parameter	Description
`projectId`	The project id
`profileId`	The profile id

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.60. Admin fetches auto cleanup configuration

REST API for usecase UC_064-Admin fetches auto cleanup configuration

Definition

Table 127. General request information
	Value
Path	/api/admin/config/autoclean
Method	GET
Status code	200 OK

Request headers

Name

Description

Example

Curl request

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

Response body

{"cleanupTime":{"unit":"MONTH","amount":0}}

2.2.61. Admin updates auto cleanup configuration

REST API for usecase UC_065-Admin updates auto cleanup configuration

Definition

Table 128. General request information
	Value
Path	/api/admin/config/autoclean
Method	PUT
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/config/autoclean' -i -u 'user:secret' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{"cleanupTime":{"unit":"MONTH","amount":0}}'

Response body
(empty)

2.2.62. Admin disables job processing in scheduler

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

Definition

Table 129. General request information
	Value
Path	/api/admin/scheduler/disable/job-processing
Method	POST
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/scheduler/disable/job-processing' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.63. Admin enables scheduler job processing

REST API for usecase UC_031-Admin enables scheduler job processing

Definition

Table 130. General request information
	Value
Path	/api/admin/scheduler/enable/job-processing
Method	POST
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

$ curl 'https://sechub.example.com/api/admin/scheduler/enable/job-processing' -i -u 'user:secret' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body
(empty)

2.2.64. Admin get scheduler status

REST API for usecase UC_032-Admin get scheduler status

Definition

Table 131. General request information
	Value
Path	/api/admin/scheduler/status/refresh
Method	POST
Status code	202 ACCEPTED

Request headers

Name

Description

Example

Curl request

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

Response body
(empty)

2.2.65. Admin lists status information

REST API for usecase UC_033-Admin lists status information

Definition

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

Request headers

Name

Description

Response fields

Path Type Description

[].key

String

Status key identifier

[].value

String

Status value

Example

Curl request

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

Response body

[{"key":"status.scheduler.enabled","value":"true"},{"key":"status.scheduler.jobs.all","value":"100"},{"key":"status.scheduler.jobs.initializing","value":"1"},{"key":"status.scheduler.jobs.ready_to_start","value":"19"},{"key":"status.scheduler.jobs.started","value":"20"},{"key":"status.scheduler.jobs.ended","value":"50"},{"key":"status.scheduler.jobs.cancel_requested","value":"2"},{"key":"status.scheduler.jobs.canceled","value":"8"}]

2.2.66. Admin fetches server runtime data

REST API for usecase UC_040-Admin fetches server runtime data

Definition

Table 133. General request information
	Value
Path	/api/admin/info/server
Method	GET
Status code	200 OK

Response fields

Path Type Description

serverVersion

String

The sechub server version.

Example

Curl request

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

Response body

{"serverVersion":"0.12.3"}

2.2.67. User lists jobs for project

REST API for usecase UC_071-User lists jobs for project

Definition

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

Path parameters

Table 135. https://localhost:8081/api/project/{projectId}/jobs
Parameter	Description
`projectId`	The id of the project where job information shall be fetched for

Request headers

Name

Description

Response fields

Path Type Description

page

Number

The page number

totalPages

Number

The total pages available

content[].jobUUID

String

The job uuid

content[].created

String

Creation timestamp of job

content[].started

String

Start timestamp of job execution

content[].ended

String

End timestamp of job execution

content[].executedBy

String

User who initiated the job

content[].executionState

String

Execution state of job

content[].executionResult

String

Execution result of job

content[].trafficLight

String

Trafficlight of job - but only available when job has been done. Possible states are GREEN, YELLOW, RED, OFF

content[].metaData.*

Object

Meta data of job - but only contained in result, when query parameter withMetaData is defined as 'true'.

Example

Curl request

$ curl 'https://sechub.example.com/api/project/project1/jobs?size=1&page=0&withMetaData=true&metadata.labels.stage=testing' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

Response body

{"page":0,"totalPages":1,"content":[{"jobUUID":"2a7ac811-798b-4f92-8df7-449b13f3d2f3","executedBy":"User1","created":"2024-04-30T15:12:55.476455968","started":"2024-04-30T15:14:55.47648388","ended":"2024-04-30T15:29:55.476494771","executionState":"ENDED","trafficLight":"GREEN","executionResult":"OK","metaData":{"labels":{"stage":"test"}}}]}

3. Reporting

This chapter describes the different SecHub report types and how to read them.

Job reports do only contain information of exact one scan job done by SecHub.

3.1. Job reports

Users can download the results of their finished scan jobs. SecHub provides these report formats:

HTML
human friendly report variant with less details
JSON
as an also machine readable format. It can be directly used by the SecHub IDE plugins (Eclipse, IntelliJ, VSCode/Codium)
SPDX JSON

3.1.1. HTML

The main purpose for the HTML report is to have a human friendly report which gives you a fast overview.

At the top left corner you see a traffic light showing either

GREEN
YELLOW or
RED.

You can open the details by clicking on "Open details". This allows you to see the full hierarchy from entry point down to data sink and can help you in analyzing this finding. It also shows a description and a possible solution (if there is one).

The next picture shows a report which resulted in a red traffic light.

At the top of the report you find the most critical parts - in this example it is a "red" finding with finding ID 19 which is a "Stored XSS".
The second finding with ID 20 is of the same type. Here the details view is opened so more details can be seen.

If available, you can find the corresponding CWE-Id (Common Weakness Enumeration) as a link to the knowledge base of MITRE in the Type column.

The SecHub client will exit with a non-zero return code per default only at a RED traffic light, but you can also configure the client to do this on color YELLOW.

3.1.2. JSON

This is the machine readable report format.

3.1.2.1. Example code scan report with yellow traffic light

{
  "jobUUID": "6cf02ccf-da13-4dee-b529-0225ed9661bd", (1)
  "trafficLight": "YELLOW", (2)
  "messages": [],
  "status": "SUCCESS",
  "reportVersion": "1.0",
  "result": {
    "count": 2,
    "findings": [
      {
        "id": 1, (3)
        "description": "",
        "name": "Absolute Path Traversal", (4)
        "severity": "MEDIUM", (5)
        "code": {
          "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java", (6)
          "line": 28, (7)
          "column": 35,
          "source": "\tpublic static void main(String[] args) throws Exception {",
          "relevantPart": "args",
          "calls": { (8)
            "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java",
            "line": 33,
            "column": 17,
            "source": "\t\tString path = args[0];",
            "relevantPart": "args",
            "calls": {
              "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java",
              "line": 33,
              "column": 10,
              "source": "\t\tString path = args[0];",
              "relevantPart": "path",
              "calls": {
                "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java",
                "line": 34,
                "column": 38,
                "source": "\t\tFile documentsGenFolder = new File(path);",
                "relevantPart": "path",
                "calls": {
                  "location": "java/com/mercedesbenz/sechub/docgen/AsciidocGenerator.java", (9)
                  "line": 34, (10)
                  "column": 29,
                  "source": "\t\tFile documentsGenFolder = new File(path);", (11)
                  "relevantPart": "File" (12)
                }
              }
            }
          }
        },
        "type": "codeScan",
        "cweId": 778
      },
      {
        "id": 2,
        "description": "",
        "hostnames": [],
        "name": "Insufficient Logging of Exceptions",
        "references": [],
        "severity": "INFO",
        "code": {
          "location": "java/com/mercedesbenz/sechub/docgen/usecase/UseCaseRestDocModelDataCollector.java",
          "line": 137,
          "column": 5,
          "source": "\t\t} catch (IOException e) {",
          "relevantPart": "catch"
        },
        "type": "codeScan",
        "cweId": 778
      }
    ]
  }
}

1	SecHub job UUID
2	Traffic light color of report - here YELLOW
3	Finding ID inside report
4	The name of the vulnerability in our case an `Absolute path traversal` where attackers could try to manipulate path input, so output could contain unwanted content/wrong file (e.g. a passwd file etc.)
5	The severity of this finding (will be used to calculate the traffic light color)
6	Entry point location in this case the Java class where the potential malicious input starts
7	Line number of entry point
8	Next call hierarchy element this is the next element of the call hierarchy, means what is called by entry point with potential malicious content as parameter. This is ongoing until last entry inside call hierarchy which is the so called "data sink"
9	Data sink location
10	Line number inside data sink
11	Source snippet
12	Relevant code part where the found vulnerability lies/could be exploited

4. Additional information

4.1. Use cases

4.1.1. Overview about usecase groups

4.1.1.1. Anonymous

All these usecases handling anonymous access.

UC_039-Check if the server is alive and running.

4.1.1.2. User administration

Usecases handling administration of users

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

4.1.1.3. Project administration

Usecases for project administration

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

4.1.1.4. User profile

User actions belonging to their profiles

UC_012-User clicks link to get new api token

4.1.1.5. Sechub execution

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

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

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

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

4.1.1.7. Job administration

Usecases about job administration

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

4.1.1.8. Technical

Usecases about technical operations being executed by sechub itself

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

4.1.1.9. Testing

Some use cases for testing

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

4.1.1.10. Configuration

Usecases for configuration parts

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

4.1.1.11. Other

All other use cases

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

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

UC_001-SIGNUP

Steps

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

4.1.3. UC_002-Admin lists open user signups

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

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

All self registrations are returned as json

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

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

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator accepts a persisted self registration entry by calling rest api

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.

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

Give user access

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

4.1.5. UC_004-Admin lists all users

An administrator downloads a json file containing all user ids

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

All userids of sechub users are returned as json

Service call

SUPERADMIN

All userids of sechub users are returned as json

4.1.6. UC_005-User creates a new sechub job

A user wants to create a new sechub job.

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

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

approve the job
upload source code for code scanning

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

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

Title

Role(s)

Description

Authenticated REST call

SUPERADMIN, USER

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

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

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

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

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

4.1.12. UC_011-User starts scan by client

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

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

It does automate following usecases:

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

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

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

Steps

Nr	Title	Role(s)	Next
1	create new job	SUPERADMIN, USER	2, 3
2	upload binaries	SUPERADMIN, USER	2
2	upload sourcecode	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

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

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

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator creates a new project by calling rest api

Create project

SUPERADMIN

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

4.1.15. UC_014-Admin lists all projects

An administrator downloads a json file containing all project ids

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

All project ids of sechub are returned as json

4.1.16. UC_015-Admin assigns user to project

An administrator assigns an user to an existing sechub project.

Event overview

"Overview of events happening at usecase UC_ADMIN_ASSIGNS_USER_TO_PROJECT

Involved messages

UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator does call rest API to assign user
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

4.1.17. UC_016-Admin unassigns user from project

An administrator unassigns an user from a sechub project.

Event overview

"Overview of events happening at usecase UC_ADMIN_UNASSIGNS_USER_FROM_PROJECT

Involved messages

UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator does call rest API to unassign user
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

4.1.18. UC_017-Admin shows user details

An administrator downloads a json file containing json containing user details

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Json returned containing details about user and her/his projects

Service fetches user details.

SUPERADMIN

The service will fetch user details for given user id

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

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

Title

Role(s)

Description

Rest API call

SUPERADMIN

Rest api called to remove user signup

Persistence

SUPERADMIN

Existing signup will be deleted

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

4.1.22. UC_021-Admin shows project details

An administrator downloads a json file containing json with project details

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Json returned containing details about project

Service fetches project details.

SUPERADMIN

The service will fetch project details

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

Title

Role(s)

Description

Rest call

SUPERADMIN

White list will be updated

Update project

SUPERADMIN

The service will update the Project whitelist.

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

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator lists all running jobs by calling rest api

Fetchjob information from database

Fetches stored job information from administration database.

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

Title

Role(s)

Description

Rest API call

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

4.1.26. UC_025-Admin shows scan logs for project

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

Steps

Title

Role(s)

Description

REST API call to get JSON list

SUPERADMIN

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

4.1.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 righs and triggers asynchronous events
3	Inform user that he/she became administrator		4
4	Inform SecHub admins that another user became administrator

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

4.1.30. UC_029-Admin lists all admins

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

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

All userids of sechub administrators are returned as json

Service call

SUPERADMIN

All userids of sechub administrators are returned as json

4.1.31. UC_030-Admin disables job processing in scheduler

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

Event overview

"Overview of events happening at usecase UC_ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

Involved messages

UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING
UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator wants to stop (pause) scheduler job processing
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

4.1.32. UC_031-Admin enables scheduler job processing

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

Event overview

"Overview of events happening at usecase UC_ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

Involved messages

UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING
UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator wants to start (unpause) scheduler job processing
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

4.1.33. UC_032-Admin get scheduler status

An administrator wants to update information about scheduler status

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

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

4.1.34. UC_033-Admin lists status information

An administrator fetches current known status information about sechub

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator wants to list status information about sechub

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

4.1.36. UC_035-User defines mock data configuration for project

User retrieves project mockdata - see define project mockdata

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

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

4.1.37. UC_036-User retrieves mock data configuration for project

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

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

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

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

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

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

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

Of course you can reduce mock to wanted parts only:

Example mock configuration for code scan only

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

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

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

4.1.39. UC_038-Admin fetches mapping configuration

An administrator fetches mapping configuration by its ID.

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator wants to fetch a mapping configuration

Service call

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

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

Title

Role(s)

Description

REST API call

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

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

Title

Role(s)

Description

REST API Call

SUPERADMIN

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

4.1.42. UC_041-Admin restarts a job

Administrator restarts job

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

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

So the admin must be able to restart a job.

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

The restart will

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

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

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

Event overview - variant: crashed jvm with product result

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

Involved messages

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

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Triggeres job restart (soft)
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

4.1.43. UC_042-Admin restarts a job (hard)

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

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

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

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

The restart will

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

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

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

Event overview - variant: crashed jvm with product result

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

Event overview

"Overview of events happening at usecase UC_ADMIN_RESTARTS_JOB_HARD

Involved messages

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

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Triggeres job restart (hard)
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

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

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

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

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

Steps

Title

Role(s)

Description

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

SUPERADMIN, USER

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

Title

Role(s)

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

Title

Role(s)

Description

Rest call

SUPERADMIN

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

Service call

SUPERADMIN

Service updates existing executor configuration

Service call

SUPERADMIN

Service updates existing executor configuration

4.1.53. UC_052-Admin creates an execution profile

An administrator creates an execution profile

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator adds a new product execution profile by calling REST API

Service call

SUPERADMIN

Service creates a new product executor configuration

4.1.54. UC_053-Admin deletes execution profile

An administrator deletes execution profile

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator deletes an existing product execution profile by calling REST API

Service call

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

4.1.62. UC_061-Admin changes project description

An administrator changes the project description

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Changes project description. Json returned containing details about changed project

Service changes project description.

SUPERADMIN

The service will change project description.

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

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

4.1.63.2. Conststraints

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

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

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

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

4.1.65. UC_064-Admin fetches auto cleanup configuration

An administrator feches current auto cleanup configuration.

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Administrator fetches auto cleanup configuration

Fetches auto cleanup config

Fetches auto cleanup configuration from database

4.1.66. UC_065-Admin updates auto cleanup configuration

An administrator changes auto cleanup configuration.

Event overview

"Overview of events happening at usecase UC_ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

Involved messages

UC_065-ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

Steps

Nr	Title	Role(s)	Next	Description
1	Rest call	SUPERADMIN	2	Administrator changes auto cleanup configuration
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

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

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

4.1.69. UC_068-Sechub schedule domain auto cleanup

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

Steps

Nr	Title	Role(s)	Next	Description
1	Scheduling		2	Checks for parts to auto clean.
2	Delete old data			deletes old job information

4.1.70. UC_069-User uploads binaries

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

The binaries must be inside a valid tar file.

Steps

Title

Role(s)

Description

Authenticated REST call

SUPERADMIN, USER

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

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

Title

Role(s)

Description

REST API call to get SPDX JSON report

SUPERADMIN, USER

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

4.1.73. UC_072-Admin shows user details for email address

An administrator fetches user details for an email address.

Steps

Title

Role(s)

Description

Rest call

SUPERADMIN

Json returned containing details about user and her/his projects

Service fetches user details.

SUPERADMIN

The service will fetch user details for given user email address

4.1.73.1. Overview

4.1.73.1.1. Diagram

4.1.73.1.2. List of all messages

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

4.1.73.2. Message ANALYZE_SCAN_RESULTS_AVAILABLE

Sequence diagram of messaging ANALYZE_SCAN_RESULTS_AVAILABLE

4.1.73.3. Message AUTO_CLEANUP_CONFIGURATION_CHANGED

Sequence diagram of messaging AUTO_CLEANUP_CONFIGURATION_CHANGED

Use cases related to this message

UC_065-ADMIN_UPDATES_AUTO_CLEANUP_CONFIGURATION

4.1.73.4. Message BINARY_UPLOAD_DONE

Sequence diagram of messaging BINARY_UPLOAD_DONE

4.1.73.5. Message JOB_CANCELLATION_RUNNING

Sequence diagram of messaging JOB_CANCELLATION_RUNNING

4.1.73.6. Message JOB_CREATED

Sequence diagram of messaging JOB_CREATED

4.1.73.7. Message JOB_DONE

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.8. Message JOB_EXECUTION_STARTING

Sequence diagram of messaging JOB_EXECUTION_STARTING

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.9. Message JOB_FAILED

Sequence diagram of messaging JOB_FAILED

4.1.73.10. Message JOB_RESTART_CANCELED

Sequence diagram of messaging JOB_RESTART_CANCELED

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.11. Message JOB_RESTART_TRIGGERED

Sequence diagram of messaging JOB_RESTART_TRIGGERED

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.12. Message JOB_RESULTS_PURGED

Sequence diagram of messaging JOB_RESULTS_PURGED

Use cases related to this message

UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.13. Message JOB_RESULT_PURGE_DONE

Sequence diagram of messaging JOB_RESULT_PURGE_DONE

4.1.73.14. Message JOB_RESULT_PURGE_FAILED

Sequence diagram of messaging JOB_RESULT_PURGE_FAILED

4.1.73.15. Message JOB_STARTED

Sequence diagram of messaging JOB_STARTED

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.16. Message MAPPING_CONFIGURATION_CHANGED

Sequence diagram of messaging MAPPING_CONFIGURATION_CHANGED

4.1.73.17. Message PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE

Sequence diagram of messaging PRODUCT_EXECUTOR_CANCEL_OPERATIONS_DONE

4.1.73.18. Message PROJECT_ACCESS_LEVEL_CHANGED

Sequence diagram of messaging PROJECT_ACCESS_LEVEL_CHANGED

4.1.73.19. Message PROJECT_CREATED

Sequence diagram of messaging PROJECT_CREATED

4.1.73.20. Message PROJECT_DELETED

Sequence diagram of messaging PROJECT_DELETED

4.1.73.21. Message PROJECT_OWNER_CHANGED

Sequence diagram of messaging PROJECT_OWNER_CHANGED

4.1.73.22. Message PROJECT_WHITELIST_UPDATED

Sequence diagram of messaging PROJECT_WHITELIST_UPDATED

4.1.73.23. Message REQUEST_JOB_CANCELLATION

Sequence diagram of messaging REQUEST_JOB_CANCELLATION

4.1.73.24. Message REQUEST_JOB_RESTART

Sequence diagram of messaging REQUEST_JOB_RESTART

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB

4.1.73.25. Message REQUEST_JOB_RESTART_HARD

Sequence diagram of messaging REQUEST_JOB_RESTART_HARD

Use cases related to this message

UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.26. Message REQUEST_PURGE_JOB_RESULTS

Sequence diagram of messaging REQUEST_PURGE_JOB_RESULTS

Use cases related to this message

UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.27. Message REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING

Sequence diagram of messaging REQUEST_SCHEDULER_DISABLE_JOB_PROCESSING

Use cases related to this message

UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

4.1.73.28. Message REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING

Sequence diagram of messaging REQUEST_SCHEDULER_ENABLE_JOB_PROCESSING

Use cases related to this message

UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

4.1.73.29. Message REQUEST_SCHEDULER_JOB_STATUS

Sequence diagram of messaging REQUEST_SCHEDULER_JOB_STATUS

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.30. Message REQUEST_SCHEDULER_STATUS_UPDATE

Sequence diagram of messaging REQUEST_SCHEDULER_STATUS_UPDATE

4.1.73.31. Message REQUEST_USER_ROLE_RECALCULATION

Sequence diagram of messaging REQUEST_USER_ROLE_RECALCULATION

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

4.1.73.32. Message SCAN_DONE

4.1.73.33. Message SCAN_FAILED

Sequence diagram of messaging SCAN_FAILED

4.1.73.34. Message SCHEDULER_JOB_PROCESSING_DISABLED

Sequence diagram of messaging SCHEDULER_JOB_PROCESSING_DISABLED

Use cases related to this message

UC_030-ADMIN_DISABLES_SCHEDULER_JOB_PROCESSING

4.1.73.35. Message SCHEDULER_JOB_PROCESSING_ENABLED

Sequence diagram of messaging SCHEDULER_JOB_PROCESSING_ENABLED

Use cases related to this message

UC_031-ADMIN_ENABLES_SCHEDULER_JOB_PROCESSING

4.1.73.36. Message SCHEDULER_JOB_STATUS

Sequence diagram of messaging SCHEDULER_JOB_STATUS

4.1.73.37. Message SCHEDULER_STARTED

Sequence diagram of messaging SCHEDULER_STARTED

4.1.73.38. Message SCHEDULER_STATUS_UPDATE

Sequence diagram of messaging SCHEDULER_STATUS_UPDATE

4.1.73.39. Message SOURCE_UPLOAD_DONE

Sequence diagram of messaging SOURCE_UPLOAD_DONE

4.1.73.40. Message START_SCAN

Sequence diagram of messaging START_SCAN

Use cases related to this message

UC_041-ADMIN_RESTARTS_JOB
UC_042-ADMIN_RESTARTS_JOB_HARD

4.1.73.41. Message UNSUPPORTED_OPERATION

Sequence diagram of messaging UNSUPPORTED_OPERATION

4.1.73.42. Message USER_ADDED_TO_PROJECT

Sequence diagram of messaging USER_ADDED_TO_PROJECT

Use cases related to this message

UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT

4.1.73.43. Message USER_API_TOKEN_CHANGED

Sequence diagram of messaging USER_API_TOKEN_CHANGED

4.1.73.44. Message USER_BECOMES_SUPERADMIN

Sequence diagram of messaging USER_BECOMES_SUPERADMIN

4.1.73.45. Message USER_CREATED

Sequence diagram of messaging USER_CREATED

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP

4.1.73.46. Message USER_DELETED

Sequence diagram of messaging USER_DELETED

4.1.73.47. Message USER_EMAIL_ADDRESS_CHANGED

Sequence diagram of messaging USER_EMAIL_ADDRESS_CHANGED

4.1.73.48. Message USER_NEW_API_TOKEN_REQUESTED

Sequence diagram of messaging USER_NEW_API_TOKEN_REQUESTED

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP

4.1.73.49. Message USER_NO_LONGER_SUPERADMIN

Sequence diagram of messaging USER_NO_LONGER_SUPERADMIN

4.1.73.50. Message USER_REMOVED_FROM_PROJECT

Sequence diagram of messaging USER_REMOVED_FROM_PROJECT

Use cases related to this message

UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

4.1.73.51. Message USER_ROLES_CHANGED

Sequence diagram of messaging USER_ROLES_CHANGED

Use cases related to this message

UC_003-ADMIN_ACCEPTS_SIGNUP
UC_015-ADMIN_ASSIGNS_USER_TO_PROJECT
UC_016-ADMIN_UNASSIGNS_USER_FROM_PROJECT

4.1.73.52. Message USER_SIGNUP_REQUESTED

Use cases related to this message

UC_001-SIGNUP

SecHub Server Rest API Documentation

1. About

2. SecHub REST API

2.1. SecHub configuration JSON

2.1.1. API version

2.1.2. Server

2.1.3. Project

2.1.4. Code scan

2.1.4.1. Upload source files from file system

2.1.4.1.1. Using data section

2.1.4.1.2. fileSystem inside the codeScan section (deprecated)

2.1.5. License scan

2.1.5.1. Example binary license scan

2.1.5.2. Example source license scan

2.1.5.3. Example source licence scan with sources code scan combined

2.1.6. Secret scan

2.1.6.1. Example source secret scan

2.1.6.2. Example binary secret scan

2.1.6.3. Example source secret scan combined with code scan

2.1.7. Web scan

2.1.7.1. URL

2.1.7.1.1. Example anonymous

2.1.7.2. Login

2.1.7.2.1. Options

2.1.7.2.2. Example basic authentication

2.1.7.2.3. Example client certificate authentication

2.1.7.2.4. Example form based login by script

2.1.7.2.5. Example OpenAPI scan

2.1.7.2.6. Example combination of openAPI definition and client certificate authentication

2.1.7.2.7. Example Header scan

2.1.7.2.8. Example Header scan with value from data section

2.1.8. Infrastructure scan

2.1.8.1. URIs

2.1.8.1.1. Example infrascan one URI

2.1.8.2. IPs

2.1.8.2.1. Example infrascan one IP

2.1.9. Data section

2.1.10. MetaData

2.1.10.1. Labels

2.2. Rest API documentation

2.2.1. Overview

2.2.1.1. Anonymous

2.2.1.2. User administration

2.2.1.3. Project administration

2.2.1.4. User profile

2.2.1.5. Sechub execution

2.2.1.6. Sign up

2.2.1.7. Job administration

2.2.1.8. Testing

2.2.1.9. Configuration

2.2.1.10. Other

2.2.2. Check if the server is alive and running.

2.2.2.1. HEAD variant

2.2.2.2. GET variant

2.2.3. Admin lists all users

2.2.4. Admin assigns user to project

2.2.5. Admin unassigns user from project

2.2.6. Admin shows user details

2.2.7. Admin deletes a user

2.2.8. Admin shows project details

2.2.9. Admin downloads all details about a scan job

2.2.10. Admin grants admin rights to user

2.2.11. Admin revokes admin rights from an admin

2.2.12. Admin lists all admins

2.2.13. Admin changes owner of a project

2.2.14. Admin updates user email address

2.2.15. Admin shows user details for email address

2.2.16. Admin creates a project

2.2.17. Admin lists all projects

2.2.18. Admin deletes a project

2.2.19. Update project whitelist

2.2.20. Admin shows scan logs for project

2.2.21. Update project metadata

2.2.22. Admin changes project description

2.2.23. Admin changes project access level

2.2.24. User clicks link to get new api token

2.2.25. User creates a new sechub job

2.2.25.1. Code Scan variant

2.2.25.2. Code Scan using data section variant

2.2.25.3. Secret scan variant

2.1.4.1.1. Using `data` section

2.1.4.1.2. `fileSystem` inside the `codeScan` section (deprecated)