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

Documentation version: Client 1.8.1 modified (commit c39468e) - Build date: 20241021165905

2. SecHub client

2.1. In a nutshell

The SecHub client program is an executable binary which can be used from command line or in a build tool of your choice.

It’s very easy to use and you do not have to handle all the REST-API calls by yourself.

Currently the client only supports basic authentication, but of course always only over https.

2.2. Download

Download the binary for your operating system where you want to trigger SecHub scanning. You will have no dependencies, just place the single binary file to a location inside your path variable.

Direct download link to the latest client release: https://mercedes-benz.github.io/sechub/latest/client-download.html For documentation, please look at SecHub web page .

2.3. Supported Platforms

The SecHub Client is available for a number of platforms. A platform is a combination of an operating system and a CPU architecture.

Table 1. Supported platforms
Name OS CPU Architecture Description

darwin-amd64

macOS

AMD and Intel 64-bit

The macOS client.

darwin-arm64

macOS

ARM

Support for recent Macs with ARM architecture.

linux-386

Linux

AMD and Intel 32-bit

Universal client for Linux as operating system. Statically linked - no dependencies. Also for older hardware.

linux-amd64

Linux

AMD and Intel 64-bit

The Linux client, unless you are using older hardware or an ARM system. Dynamically linked.

linux-arm

Linux

ARM 32-bit

For ARM 32-bit systems. For example, single board computers such as the Raspberry PIs, older Nvidia Jetson boards and many more.

linux-arm64

Linux

ARM 64-bit

For ARM 64-bit systems, such as ARM based servers and some single board computers. Examples include newer models of the Nvidia Jetson series, newer Raspberry PI models, servers from the Marvell ThunderX series and Amazon AWS EC2 A1, T4g, M6g, C6g, and R6g instances.

windows-386

Windows

AMD and Intel 32-bit

For older hardware running Windows as operating system.

windows-amd64

Windows

AMD and Intel 64-bit

The Windows client, unless you are using older 32-bit hardware.

In case your platform is not included in the table, you might be able to compile the SecHub Client for your platform. The SecHub Client is written in the Go programming language. Go supports more platforms. For a full list of supported platforms have a look at the Go documentation: Optional environment variables.

2.4. Usage

2.4.1. Show help

sechub help

will print out a simple help of all command line options. At the end you will find a link to the latest config and variable examples.

2.4.2. Actions

2.4.3. Parameter overview for client actions

Here is an overview of the mandatory parameters for each action:

action

mandatory parameters

scan

server + user + api token + projectID + configFile

scanAsync

server + user + api token + projectID + configFile

getStatus

server + user + api token + projectID

getReport

server + user + api token + projectID

listJobs

server + user + api token + projectID

defineFalsePositives

server + user + api token + projectID

getFalsePositives

server + user + api token + projectID

interactiveMarkFalsePositives

server + user + api token + projectID + (file only if no report file is in current dir)

interactiveUnmarkFalsePositives

server + user + apiToken + projectID

markFalsePositives

server + user + api token + projectID + file

unmarkFalsePositives

server + user + api token + projectID + file

help

version
2.4.3.1. scan

This is the recommended scan action: You only have to make one single client call to trigger a scan and get the report.

The client performs these steps for you:

  1. create a scan job on the SecHub server

  2. upload necessary data (e.g. zipped sourcefiles for source scans)

  3. approve the job as ready to start

  4. wait until the job is done

  5. download the report file

On "red" (critical or high findings) the SecHub client exits with a non-zero status so your build will break (depends on your build tool).
For security reasons always pass your API-token via the environment variable SECHUB_APITOKEN.

Minimum call syntax

Prerequisite is a configuration file sechub.json in current directory.
See here for details: Configuration file

sechub scan
If you prefer the report in HTML format:
sechub -reportformat html scan
With -output ${file-or-directory} you can define where to place the report.
Can be a directory, a file name or a file path.
Default: sechub_report_${your-project}_${jobUUID}.{json|html|spdx} in current directory
2.4.3.2. scanAsync

Does scan asynchronous:

  • Identical to action scan but does not wait until the job has finished on the SecHub server

  • Returns the SecHub job UUID of the newly created scan job.

This can be interesting if you have long running scans and you want have a fast continous integration build - but then you have to manually check the job state, fetch reports and you get no automated build break!

Minimum call syntax

sechub scanAsync
2.4.3.3. getStatus

Will fetch the job status and return result as json

Minimum call syntax

sechub getStatus
Defaults to latest job.
You can select the job by providing the wanted job UUID by adding -jobUUID ${jobUUID}
This action respects defined label definitions as filter criteria.
2.4.3.4. getReport

Will fetch the report as json. (result will only exist when job is done)

Minimum call syntax

sechub getReport
Defaults to latest finished job.
You can select the job by providing the wanted job UUID by adding -jobUUID ${jobUUID}
This action respects defined label definitions as filter criteria.
With -output ${file-or-directory} you can define where to place the report.
Can be a directory, a file name or a file path.
Default: sechub_report_${your-project}_${jobUUID}.{json|html|spdx} in current directory
2.4.3.5. listJobs

Lists the last jobs and their state.

Minimum call syntax

sechub listJobs
This might be useful for an overview or
when you want to see your project’s scan job queue or
to find out the job UUID of a certain job.
This action respects defined label definitions as filter criteria.
2.4.3.6. defineFalsePositives

This will define the false positives list of your project.
Default definition file to read from is sechub-false-positives.json - format is same as for markFalsePositives.

The client will compare against the already defined false-positives on the server and
- add missing false-positive definitions
- remove the ones which are not in the definition file

Minimum call syntax

sechub defineFalsePositives
With -file ${file} you can define where to read from.
Default: sechub-false-positives.json in current directory
It’s a good idea to add your false-positives definition file in your source code repository. So everybody can easily have an overview about the declared false-positives.
2.4.3.7. getFalsePositives

This will fetch the false positives list of your project as JSON.

Minimum call syntax

sechub getFalsePositives
With -output ${file-or-directory} you can define where to place the result.
Can be a directory, a file name or a file path.
Default: sechub-false-positives-${your-project}.json in current directory
2.4.3.8. interactiveMarkFalsePositives

Instead of creating a json file to mark false positives, you can also do this interactively: Go to the project directory containing sechub.json and a report file from a recent scan and run sechub interactiveMarkFalsePositives.

You can select the report file using the -file option of the client. Otherwise the project’s latest report file in the current directory is automatically selected.

For each finding in the reports file, you are prompted: "Add this as false positive?" Your choices are:

  • y Yes - Mark as false positive. You are prompted for an optional comment line which can help to understand later why this has been marked.

  • n No - Do nothing and go to next item.

  • s Skip following findings - Finish the marking and add the marked items to the false positives list on the SecHub server.

  • c Cancel - Quit and upload nothing

You can download and view your current false positives list with getFalsePositives

See also example for interactiveMarkFalsePositives

2.4.3.9. interactiveUnmarkFalsePositives

Instead of creating a json file to unmark false positives, you can also do this interactively: Go to the project directory containing sechub.json and run sechub interactiveUnmarkFalsePositives

SecHub client will download the current false positives list and interactively ask each entry: "Do you want to remove this false positive?" Your choices are:

  • y Yes - Unmark this false positive.

  • n No - Do nothing and go to next item.

  • s Skip the rest - End the asking here and remove the marked items from the false positives list on the SecHub server.

  • c Cancel - Quit and change nothing

See also example for interactiveMarkFalsePositives

2.4.3.10. markFalsePositives

Read your report carefully and decide which of the findings you consider as "false positives" (FP).

Create a json file as described below and start action markFalsePositives.

Minimum call syntax

sechub -file ${json-file} markFalsePositives

Defining false positives is done by declaring false positive information in a JSON file

  • by referencing job results from former SecHub job UUID and the corresponding finding entry (by id) and/or

  • by specifying a project data section where specific patterns that match false positive findings are declared

and post it to the SecHub server REST API.

The jobData approach is very generic and easy to use: It references a SecHub report. Every false-positive in any kind of scan can be handled like that.

The projectData approach is more powerful for the user because wildcards can be used.

Each entry can be updated or removed by the given id.
Declaring a projectData entry with an already existing id, will update its content with the new data.

Example JSON using job results

{
  "apiVersion": "1.0", (1)
  "type": "falsePositiveDataList", (2)
  "jobData": [ (3)
    {
      "jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd", (4)
      "findingId": 1, (5)
      "comment": "Can be ignored because not in deployment" (6)
    },
    {
      "jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd",
      "findingId": 15
    }
  ]
}
1 apiVersion (mandatory) - API version
2 type (mandatory) - must be falsePositiveDataList
3 jobData - List of job data that is used to mark a single finding as a false positive
4 jobData.jobUUID (mandatory) SecHub Job-UUID of the report where the finding was
5 jobData.findingId (mandatory) Finding ID which shall be marked as false positive
6 jobData.comment (optional) A comment describing the reason why this is a false positive

Example JSON using project data

{
  "apiVersion": "1.0", (1)
  "type": "falsePositiveDataList", (2)
  "projectData": [ (3)
    {
      "id": "unique-id", (4)
      "comment": "It was verified that there is no SQL-injection",
      "webScan": { (5)
          "cweId": 89, (6)
          "urlPattern": "https://*.example.com/rest/products/search?*", (7)
          "methods": [ "GET", "DELETE" ] (8)
      }
    }
  ]
}
1 apiVersion (mandatory) - API version
2 type (mandatory) - must be falsePositiveDataList
3 projectData - List that can be used to mark more than a single finding as a false positive. Currently only available for web scans.
4 projectData.id that identifies this entry. If the same id is used again, the existing false positive entry will be overwritten. The id is also mandatory to unmark this entry.
5 projectData.webScan (optional) section can be used to define false positive patterns for web scans (DAST). It provides more possibilities to the user than above jobData.
6 projectData.webScan.cweId is used to mark a certain type of finding as false positive.
When handling web scan project data this will be treated as a mandatory field.
Please insert here the cweId from the original report.
If there was no cweId in the original report, then it must be omitted or set to zero "cweId": 0.
7 projectData.webScan.urlPattern (mandatory) specifies an URL pattern to identify a false positive. Asterisks can be used as wildcards e.g. if you have different environments like DEV, INT, PROD or you have variable parts like in API calls or query paramaters https://.example.com/rest//search?*.
8 projectData.webScan.methods (optional) Can be used to further restrict the false positive matching, to specific request methods protocols, like GET, POST, etc.

Important information on the wildcard approach in projectData, regarding web scans:
- To be marked as a false positive a finding must match the given cweId and the urlPattern
- Wildcards (*) can be used inside urlPattern.
- Wildcards match anything until the next NON-wildcard character.
- Multiple wildcards can be used in one urlPattern.
- An optional list of (HTTP) methods can be specified to limit the false positive entry to certain methods, e.g if you specify "methods": [ "GET", "DELETE" ] like in the example above that means even if the cweId and the urlPattern are matching, if the finding was found with a POST request it would not be a false positive. When leaving methods out, this false positive entry apply to any method.
- An urlPattern which contains only wildcards (*) is not allowed.

markFalsePositives only adds new false positives.
Providing an empty list here does NOT delete the already declared false positives!
If you want this, please use defineFalsePositives.
See also interactiveMarkFalsePositives for an easy way to declare false positives.
2.4.3.11. unmarkFalsePositives

Remove formerly defined false positives.

It works similar to markFalsePositives: Just define a JSON file, select the file by the -file argument and start action unmarkFalsePositives.

Minimum call syntax

sechub -file ${json-file} unmarkFalsePositives

The JSON scheme is identical to markFalsePositives

Mandatory fields for unmarkFalsePositives:
- for jobData: jobUUID and findingId
- for projectData: id

Example JSON with both: jobData and projectData

{
  "apiVersion": "1.0",
  "type": "falsePositiveDataList",
  "jobData": [
    {
      "jobUUID": "6cfa2ccf-da13-4dee-b529-0225ed9661bd",
      "findingId": 1
    }
  ],
  "projectData": [
    {
      "id": "unique-id"
    }
  ]
}
interactiveMarkFalsePositives might be easier to use

2.4.4. Configuration overview

Basically parameters can be passed to the SecHub client in three ways:

  • commandline options (overrides below)

  • environment variables (overrides config file)

  • configuration file (default sechub.json)

In below table, there is an overview of what can be defined where.

scope

cmdline option

environment variable

JSON config file

api token

-apitoken (!! not recommended !!)

SECHUB_APITOKEN

append SCM history

-addScmHistory

SECHUB_ADD_SCM_HISTORY

code scan config

codeScan

JSON config file

-configfile

file

-file

job uuid

-jobUUID

label definitions

-label

SECHUB_LABELS

metaData.labels

max. poll interval

-wait

SECHUB_WAITTIME_DEFAULT

network timeout

-timeout

output folder or file

-output

project id

-project

SECHUB_PROJECT

project

quiet mode

-quiet

SECHUB_QUIET

report format

-reportformat

scan for secrets

secretScan

server url

-server

SECHUB_SERVER

server

stop on yellow

-stop-on-yellow

temporary dir

-tempdir

SECHUB_TEMP_DIR

trust all certificates

SECHUB_TRUSTALL

user id

-user

SECHUB_USERID

user

web scan config

webScan

DEV: debug http traffic

SECHUB_DEBUG_HTTP

DEV: enable debugging

SECHUB_DEBUG

DEV: ignore default excludes

SECHUB_IGNORE_DEFAULT_EXCLUDES

DEV: initial wait interval

SECHUB_INITIAL_WAIT_INTERVAL

DEV: keep temporary files

SECHUB_KEEP_TEMPFILES

2.4.5. Commandline Options

  • -addScmHistory
    Secrets scan only: Upload SCM directories like .git for scanning.
    Can also be defined via environment variable SECHUB_ADD_SCM_HISTORY=true.

  • -apitoken <string>
    The user’s api token - mandatory. Please try to avoid -apitoken parameter for security reasons!!
    Use environment variable SECHUB_APITOKEN instead! (see: Environment variables)

  • -configfile <filepath>
    Path to SecHub JSON config file. Defaults to sechub.json in current directory.

  • -file <filepath>
    Defines file to read from for actions defineFalsePositives, markFalsePositives, interactiveMarkFalsePositives, unmarkFalsePositives

  • -jobUUID <string>
    SecHub job uuid. Optional for actions getStatus or getReport

  • -label <label definition>
    Define a SecHub label for scan or filtering. (Example: "key1=value1") Repeat to define multiple labels.

  • -output <path to folder or file>
    Where to place reports, false-positive files etc. Can be a directory, a file name or a file path (defaults to current working directory and default file names)

  • -project <string>
    Unique project id - mandatory, but can also be defined in config file or via environment variable.

  • -quiet
    Quiet mode - Suppress all informative output. Can also be defined via environment variable SECHUB_QUIET=true.
    Only print filenames written to, errors and explicitely requested informations (job-UUID, version, status).

  • -reportformat <format>
    Output format for reports. Currently supported: [json, html, spdx-json]. If an unsupported format string is provided, "json" will always be the fallback.

  • -server <url>
    Server url of SecHub server to use - e.g. https//example.com:8081. Mandatory, but can also be defined in config file or via environment variable.

  • -stop-on-yellow
    A yellow traffic light in the report will result in a non-zero return code.

  • -tempdir <path to folder>
    Temporary files will be placed here. (defaults to current working directory)

  • -timeout <seconds>
    Timeout for network communication in seconds. (default 120)

  • -user <string>
    Username - mandatory, but can also be defined in config file or via environment variable.

  • -wait <seconds>
    Maximum wait time in seconds (default 60). Will be used for periodic status checks when action=scan and for retries of HTTP calls.

2.4.6. Environment variables

Additionally to above cmdline options, you can set some values also via environment variables which can be helpful when you have different SecHub environments (like: dev, int, prod)

  • SECHUB_ADD_SCM_HISTORY
    (true or false / unset) Secrets scan only: Upload SCM directories like .git for scanning. (same as -addScmHistory option)

  • SECHUB_APITOKEN
    The SecHub api token for SECHUB_USERID. (same as -apitoken option)

  • SECHUB_LABELS
    Define one or more labels for scan or filtering. The labels will appear in your SecHub report. Separate multiple labels with ",". (see also -label option)
    Example: export SECHUB_LABELS="key1=test 1,key2=test 2"

  • SECHUB_PROJECT
    The SecHub project id. (same as -project option)

  • SECHUB_QUIET
    Quiet mode (true or false / unset) - Suppress all informative output. (same as -quiet option)

  • SECHUB_SERVER
    The SecHub server url. (same as -server option)

  • SECHUB_TEMP_DIR
    Temporary files will be placed here. Make sure that the folder exists and is writeable. (same as -tempdir option)

  • SECHUB_TRUSTALL
    When set to true, then HTTPS certificate checking will be disabled. May be useful when using self-signed certificates. Please try to avoid this setting for security reasons.

  • SECHUB_USERID
    The SecHub username. (same as -user option)

  • SECHUB_WAITTIME_DEFAULT
    Maximum wait time in seconds (default 60). Will be used for automatic status checks etc. when action=scan.

  • SECHUB_WHITELIST_ALL
    When set to true then ignore the default whitelist for source files and add every file. You may want to define excludes in your sechub.json file. !! Handle with care !!

Settings for debugging/client development:

  • SECHUB_DEBUG
    When set to true then log as much as possible (but not HTTP request contents)

  • SECHUB_DEBUG_HTTP
    When set to true then log HTTP request contents.

  • SECHUB_IGNORE_DEFAULT_EXCLUDES
    When set to true then default exclude folders {"**/test/**", "**/.git/**", "**/node_modules/**"} will be included for code scan. In this case, you should declare your own exclude list in the config json.

  • SECHUB_INITIAL_WAIT_INTERVAL
    Initial wait time (floating point number) until SecHub client polls the first time if the report is ready (sechub scan). Meant for local integration tests.

  • SECHUB_KEEP_TEMPFILES
    When set to true then sourcecode-<projectID>.zip files for code scan will not be removed, so you can check, what was uploaded to the SecHub server.

2.4.7. Proxy support

The environment variables http_proxy, https_proxy and no_proxy (or the uppercase versions thereof) can be set to use a proxy for accessing the SecHub server. (https_proxy takes precedence over http_proxy for https requests.)

Syntax: [<scheme>://][<username>:<password>@]<proxy host>[:<proxy port>]

The environment values may be either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.

Examples (Linux/Mac):

export http_proxy=http://scott:tiger@proxy.example.org:3128

export http_proxy=http://localhost:3128 (e.g. when using a local CNTLM proxy)

2.4.8. Debugging

For troubleshooting, you can

  • set environment variable SECHUB_DEBUG to true
    Now you will see in detail what the client does and also the html calls sent to and received from SecHub server.

  • set environment variable SECHUB_DEBUG_HTTP to true
    Now you will see the complete HTTP communication including headers.
    (basic-auth headers (security) and contents of uploads (binary data) are filtered out)

  • set environment variable SECHUB_KEEP_TEMPFILES to true
    Now sourcecode-<projectID>.zip files for code scan or binaries-<projectID>.tar will not be removed, so you can check, what was uploaded to the SecHub server.

2.5. 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.5.1. API version

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

2.5.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.5.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.5.4. Code scan

codeScan defines the settings for code scans.

2.5.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.5.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.5.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.5.5. License scan

licenseScan defines the settings for license scans.

2.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.7. Web scan

webScan defines the settings for web scans (DAST).

2.5.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.5.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/<*>"].
2.5.7.2. Login

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.5.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.5.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.5.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://productfailure.demo.example.org",
    "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.
2.5.7.2.4. Example form based login by script
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.5.7.2.5. Example form based login with TOTP

The TOTP configuration is generally never used without any other login mechanism. It is meant to be used as an additional authentication factor. In this example TOTP is used in combination with form based login, which is left out in the example for better readability.

Most of the time it is enough to specify a seed for the TOTP configuration in SecHub. The optional values validityInSecods, tokenLength and hashAlgorithm have defaults which will be used if nothing is specified. The defaults are well-known and any authentication provider or application should provide the optional data if it uses anything other than the defaults. 
{
  "apiVersion" : "1.0",
  "webScan" : {
    "url" : "https://productfailure.demo.example.org",
    "login" : {
      "url" : "https://productfailure.demo.example.org/login",
      "form" : {
        "script" : {
          "pages" : [ {
            "actions" : [ {
              "type" : "username",
              "selector" : "#example_login_userid",
              "value" : "{{ .LOGIN_USER }}"
            }, {
              "type" : "password",
              "selector" : "#example_login_pwd",
              "value" : "{{ .LOGIN_PWD }}"
            }, {
              "type" : "click",
              "selector" : "#next",
              "description" : "Click to go to next page"
            } ]
          } ]
        }
      },
      "totp" : { (1)
        "seed" : "example-seed", (2)
        "validityInSeconds" : 60, (3)
        "tokenLength" : 8, (4)
        "hashAlgorithm" : "HMAC_SHA256" (5)
      }
    }
  }
}
1 Start of TOTP configuration.
2 The seed is the only mandatory field for the TOTP configuration. It represents the secret key used to generate TOTP values.
3 The validityInSecods is an optional field, which represents the maximum amount of seconds a TOTP is valid. This depends on the authentication provider or the application, providing the seed to the user. If no specific validityInSecods is provided do not configure this value and SecHub will use the default.
4 The tokenLength is an optional field, which represents the length of the TOTP the authentication provider or the application expects. As before, this depends on the authentication provider or the application, providing the seed to the user. If no specific tokenLength is provided do not configure this value and SecHub will use the default.
5 The hashAlgorithm is an optional field, representing the hash algorithm, which is used by the authentication provider or the application during the computation of the TOTP. As before, this depends on the authentication provider or the application, providing the seed to the user. If no specific hashAlgorithm is provided do not configure this value and SecHub will use the default.
The currently available hash algorithms are:

  • HMAC_SHA1

  • HMAC_SHA256

  • HMAC_SHA512
2.5.7.2.6. 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)
      "apiDefinitionUrl" : "https://productfailure.demo.example.org/api/v1/swagger/?format=openapi" (4)
    }
  }
}
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
4 you can also use apiDefinitionUrl to specify an URL to read the API definition from. Currently you can combine importing openApi definitions from files and URLs, but most of the time it does not make sense to combine this two options.
2.5.7.2.7. 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",
      "apiDefinitionUrl" : "https://productfailure.demo.example.org/api/v1/swagger/?format=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.5.7.2.8. 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.5.7.2.9. 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.5.8. Infrastructure scan

infraScan (optional) defines the infrastructure scan settings.

2.5.8.1. URIs

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

2.5.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.5.8.2. IPs

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

2.5.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.5.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:

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.5.9.1. Remote Data

Instead of configuring the file system and uploading local data, it is also possible to define a remote data section to automatically retrieve the data to be scanned from remote locations. In a PREPARE phase the PDS prepare will download the data from the remote location and upload it to a shared storage. From there any other PDS solution can access the data for scanning. The type is not mandatory, but it is recommended to set it to git or docker to make it clear what type of remote data is being used.

Scan types (codeScan, licenseScan etc.), includes or excludes as well as false positives can be defined as usual.

2.5.9.1.1. Example source remote data scan
Codes scan configuration for remote git sources without credentials
{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [ {
      "name" : "firmware-images",
      "remote" : {
        "location" : "https://path-to-my-git-exmaple/repository.git", (1)
        "type" : "git" (2)
      }
    } ]
  },
  "codeScan" : {
    "use" : [ "firmware-images"]
  }
}
1 location: The URL to remote data. (for example a git repository or a docker registry)
2 type: The type of the remote data. Currently supported are git or docker.
2.5.9.1.2. Example source remote data scan with credentials
Code scan configuration for remote git sources with credentials
{
  "apiVersion" : "1.0",
  "data" : {
    "sources" : [ {
      "name" : "firmware-images",
      "remote" : {
        "location" : "https://path-to-my-git-exmaple/repository.git", (1)
        "type" : "git", (2)
        "credentials" : {
          "user" : { (3)
            "name" : "my-username", (4)
            "password" : "my-password" (5)
          }
        }
      }
    } ]
  },
  "codeScan" : {
    "use" : [ "firmware-images"]
  }
}
1 location: The URL to remote data. (for example a git repository or a docker registry)
2 type: The type of the remote data. Currently supported are git or docker.
3 user: Defines user credentials
4 name: The username to access remote data
5 password: The API token or password that grant access to remote data
2.5.9.1.3. Example binaries remote data scan with credentials
Codes scan configuration for remote git sources with credentials
{
  "apiVersion" : "1.0",
  "data" : {
    "binaries" : [ {
      "name" : "firmware-images",
      "remote" : {
        "location" : "https://path-to-your-image:tag", (1)
        "type" : "docker", (2)
        "credentials" : {
          "user" : {
            "name" : "my-username",
            "password" : "my-password"
          }
        }
      }
    } ]
  },
  "codeScan" : {
    "use" : [ "firmware-images"]
  }
}
1 location: The URL to remote data. (for example a git repository or a docker registry)
2 type: The type of the remote data. Currently supported are git or docker.

2.5.10. MetaData

The SecHub configuration file can have optional meta data.

The SecHub configuration is stored encrypted in database and access is restricted, even for administrators. But the meta data can be fetched by users of the project or administrators without additional audit logging.

Because of this you should never store sensitive information inside the meta data!
2.5.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.5.11. Code scan: accepted source code files

The client will per default only include "wellknown" source files. This is done by inspecting the filename ending. The accepted defaults are shown in next table.

All files having file endings not listed here, will be ignored and not uploaded to SecHub server.
Except the source data definition is also used for secrets scanning. Then every file is being uploaded.
You can also define additional source file endings - see config file example .
Language(s) File extensions

Apex

.apex
.apexp
.apxc
.component
.-meta.xml
.object
.page
.report
.tgr
.trigger
.workflow

ASP (Active Server Pages)

.asp

ASP

.ascx
.aspx

Azure

.bicep

C/C++

.ac
.am
.c
.c++
.cc
.cmake
.cpp
.cxx
.ec
.h
.h++
.hh
.hpp
.hxx
.pc
.pro

C#, VB.NET, Visual Basic, VB Script

.asax
.bas
.cls
.cs
.cshtml
.csproj
.ctl
.dsr
.frm
.master
.sln
.vb
.vbp
.vbs
.xaml

Certificates for secrets scans

.crt,
.cer,
.csr,
.der,
.pem,
.pfx,
.p12,
.p7b,
.p7c,
.CRT,
.CER,
.CSR,
.DER,
.PEM,
.PFX,
.P12,
.P7B,
.P7C

Cobol

.cbl
.cob
.cpy
.eco
.pco
.sqb

Docker

Dockerfile
.dockerfile

Go, Protobuf

.go

Groovy

.groovy
.gsh
.gsp
.gvy
.gy

HTML

.htm
.html

Java ecosystem

.app
.cmp
.evt
.gradle
.hbs
.java
.javasln
.jsf
.jsp
.jspf
.mf
.project
.properties
.tag
.tld
.vm
.xhtml

JavaScript

.handlebars
.jade
.js
.json
.jsx
.pug
.vue
.xsaccess
.xsapp
.xsjs
.xsjslib

Kotlin

.ftl
.kt
.kts
,mustache

Kubernetes, Helm, Docker-Compose

.yaml
.yml
.tpl

Lua

.lua

Objective C, Swift

.m
.plist
.swift
.xib

Perl

.pl
.plx
.pm
.psgi

php

.ctp
.php
.php3
.php4
.php5
.php5.6
.phtm
.phtml
.tpl
.twig

PL/SQL

.pck
.pkb
.pkh
.pks
.pls
.sql

Python, Django

.csv
.gtl
.latex
.py
.py2
.py3
.pyi
.python
.tex
.txt

Ruby

.erb
.lock
.rb
.rhtml
.rjs
.rxml

Rust

.rs
.rlib

Scala

.conf
.sc
.scala

Terraform

.tf
.tfvars

Typescript/Angular

.ts
.tsx

Others

.build
.cgi
.config
.inc
.xml

2.5.12. Inject variables into configuration files (For advanced users)

All environment variables are available inside your configuration file in Go template syntax:

{{ .ENV_VARIABLE_NAME }}

For example: When you have defined USED_API_VERSION with value 1.0, you can inject it into a json config file like this:

{
  "apiVersion": "{{ .USED_API_VERSION }}"
}

2.6. Examples

The next subsections contain some SecHub configuration examples. You can use them as templates for your own files.

First: Define your SecHub environment variables:

export SECHUB_SERVER=https://sechub.example.org
export SECHUB_USERID=alice
export SECHUB_APITOKEN=EXAMPLE4aa82407da7e06bdbEXAMPLE
export SECHUB_PROJECT=myproject
Please replace the example values with your real ones to get them working.

2.6.1. Start a source code scan

sechub scan

with corresponding 'sechub.json' config file: see source scan example .

2.6.2. Start a web scan

sechub scan

with corresponding 'sechub.json' config file: see web scan example (anonymous)

2.6.3. Start a scan for secrets

sechub scan

with corresponding 'sechub.json' config file: see examples for secret scans

2.6.4. Start an infra scan

sechub scan

with corresponding sechub.json config file: infrastructure scan example .

2.6.5. Mark false positives

2.6.5.1. markFalsePositives
sechub -file mark-fp.json markFalsePositives

with a corresponding mark-fp.json - see Mark false positives JSON format

2.6.5.2. interactiveMarkFalsePositives
sechub interactiveMarkFalsePositives

/  ___|         | | | |     | |
\ `--.  ___  ___| |_| |_   _| |__
 `--. \/ _ \/ __|  _  | | | | '_ \
/\__/ /  __/ (__| | | | |_| | |_) |
\____/ \___|\___\_| |_/\__,_|_.__/ Client Version 0.29.0-20220401111823

Using latest report file "sechub_report_mytestproject_0a84899f-1305-41e0-a2d5-e7c31d6185fd.json".
------------------------------------------------------------------
1: Side Channel Data Leakage, severity: HIGH
src/main/java/com/example/testapp/invoice/application/InvoiceApplicationService.java, line 651 column 17
        Invoice creditNote = getInvoice(invoiceId).orElseThrow(InvoiceNotFoundException::new);
------------------------------------------------------------------
Add this as false positive? ('y' Yes, 'n' No, 's' Skip following findings, 'c' Cancel) y
Please add a single line comment:
Can be ignored in our case
------------------------------------------------------------------
2: Unsafe Object Binding, severity: MEDIUM
src/main/java/com/example/testapp/api/ServiceOrderController.java, line 33 column 59
    public void saveAttachment(@RequestBody AttachmentDto attachmentDto){
------------------------------------------------------------------
Add this as false positive? ('y' Yes, 'n' No, 's' Skip following findings, 'c' Cancel) n
------------------------------------------------------------------
3: Unsafe Object Binding, severity: MEDIUM
src/main/java/com/example/testapp/api/CouponController.java, line 30 column 78
    public CouponVerifyResponseDto couponVerify(@RequestBody CouponVerifyDto couponVerifyDto) {
------------------------------------------------------------------
Add this as false positive? ('y' Yes, 'n' No, 's' Skip following findings, 'c' Cancel) s
- Successfully uploaded SecHub false-positives list for project "mytestproject" to server.

2.6.6. Unmark false positives

2.6.6.1. unmarkFalsePositives
sechub -file mark-fp.json unmarkFalsePositives

with a corresponding mark-fp.json - see Unmark false positives JSON format

2.6.6.2. interactiveUnmarkFalsePositives
sechub interactiveUnmarkFalsePositives
 _____           _   _       _
/  ___|         | | | |     | |
\ `--.  ___  ___| |_| |_   _| |__
 `--. \/ _ \/ __|  _  | | | | '_ \
/\__/ /  __/ (__| | | | |_| | |_) |
\____/ \___|\___\_| |_/\__,_|_.__/ Client Version 0.29.0-20220401111823

- Fetching false-positives list for project "mytestproject".
------------------------------------------------------------------
Side Channel Data Leakage, codeScan severity: HIGH
  Origin: Finding ID 1 in job 0a84899f-1305-41e0-a2d5-e7c31d6185fd
  File: src/main/java/com/example/testapp/invoice/application/InvoiceApplicationService.java
  Code:         Invoice creditNote = getInvoice(invoiceId).orElseThrow(InvoiceNotFoundException::new);
(Added by testuser at 2020-08-20 12:43:03; comment: "Can be ignored in our case")
------------------------------------------------------------------
Do you want to remove this false positive? ('y' Yes, 'n' No, 's' Skip the rest, 'c' Cancel) y
------------------------------------------------------------------
Side Channel Data Leakage, codeScan severity: HIGH
  Origin: Finding ID 2 in job 0c86134c-2305-41e0-a2d5-e7c31df45d15
  File: src/main/java/com/mercedesbenz/otr/invoice/application/ApplicationService.java
  Code:         Invoice invoice = getInvoice(invoiceId).orElseThrow(InvoiceNotFoundException::new);
(Added by testuser at 2020-08-20 12:43:03; comment: "Another explanation example")
------------------------------------------------------------------
Do you want to remove this false positive? ('y' Yes, 'n' No, 's' Skip the rest, 'c' Cancel) s
Applying false-positives to be removed for project "vpc_cn":
- JobUUID 0a84899f-1305-41e0-a2d5-e7c31d6185fd: finding #1
Transfer completed

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.

sechub report html example1

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