1. About

About SecHub

SecHub stands for "Security Hub" and serves as an unified API to scan for various security issues. With SecHub, users don’t need to worry about the specific scanning product used on the server side; they simply configure their desired security goals.

The SecHub server alone does NOT provide a security infrastructure but orchestrates different security products/tools.

Please check our ready to use security open source tools: PDS solutions for integration with SecHub server.

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

You can get more documentation from the SecHub web page .

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

About documentation

This documentation is part of SecHub.

Key Value Information

LICENSE

MIT License

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

Documentation version: Server 2.14.0 - Build date: 2025-09-01 14:49 (UTCZ)

2. SecHub Tutorials

The SecHub tutorials are step by step user guides for different tasks.
Examples show setups and use cases for different purposes. For detailed technical documentation please see the technical documentation.

2.1. Integrate new SecHub module

In the following the necessary steps to integrate a new module in the SecHub project are described. SecHub uses Gradle and the Gradle wrapper.

  1. Create new SecHub module

    Create your project structure like this: sechub/<your module name>/src/main/java/com.mercedesbenz.sechub.<your package name>/<your source code> analogue your test are placed in the test directory

  2. Modify your build.gradle file

    Copy the build.gradle code from another similar project (e.g. a wrapper module)
    Add your main class to the manifest and modify all project specific variables.

  3. Modify dependencies in your build.gradle
    Add the dependencies you need, they are global managed in sechub/gradle/libraries.gradle, you can add new dependencies to the libraries.gradle or use existing dependencies

  4. Create a getVersion method if needed
    The getVersion Method needs to be implemented in buildSrc/src/main/groovy/VersionData.groovy
    Then you can use it in your build.gradle eg.: version = versionData.getMyNewProductVersion()

  5. Implement your build tasks in sechub/gradle/build-versioning.gradle

  6. Include your task in sechub/settings.gradle

  7. Test if your task is listed with executing ./gradlew tasks
    You should see your newly created task now

  8. Build your module
    Run your task defined in your build.gradle with ./gradlew <my new task>

2.2. Create a PDS solution for a product

The following user guide is an instruction to create and test a PDS solution for a new module eg. a scan tool or a wrapper. You need to install docker and docker compose.

Requirements: You need to install docker and docker compose. ubuntu22.04 install docker compose

  1. Create a new folder in sechub/pds-solutions/<your pds solution>
    The folder should be named as your new product e.g. if your product name is example-product then you create sechub/pds-solutions/example-product/

  2. Copy following files/ folders from another PDS-solution:
    The README.adoc, the 01-start* script, the docker folder, the docker compose yaml used in the 01-script and the env file (if your product requires environment variables are needed) e.g. copy from sechub/pds-solutions/gosec
    Your structure should look like presented below:

    .
├── 01-start-single-docker-compose.sh
├── docker
│   ├── mocks
│   │   ├── some_mock_report.json
│   ├── pds-config.json
│   ├── scripts
│   │   ├── <my product>.sh
│   │   └── <my product mock>.sh
│   └── <my product>-Debian.dockerfile
├── docker-compose_pds_<my product>.yaml
├── env
└── README.adoc

  3. Rename all folders to fit your product name (Replace <my product> with e.g. myScanner )

  4. Modify all files (<my product>-Debian.dockerfile, scripts, yaml, env …​ ) to fit your product needs

  5. Modify the sechub/sechub-pds-solutions/<my product>/docker/scripts/<my product>.sh
    This script is executed for every incoming PDS job. The script is referenced in your pds-config.json.

  6. Modify your pds-config.json
    You can add additional optional or required parameters. They have the form pds.productname.variablename and accessible as environment variables like this PDS_PRODUCTNAME_VARIABLENAME
    Example pds-config.json:

    {
  "apiVersion": "1.0",
  "serverId": "<MYPRODUCT>_CLUSTER",
  "products": [
    {
      "id": "PDS_<MYPRODUCT>",
      "path": "/pds/scripts/<my product>.sh",
      "scanType": "codeScan",
      "description": "Example description."
    },
    {
      "id": "PDS_<MYPRODUCT>_MOCK",
      "path": "/pds/scripts/<my product mock>.sh",
      "scanType": "codeScan",
      "description": "Runs mock report. It returns a fixed result file.",
      "parameters" : {
        "optional" : [
          {
            "key" : "pds.<my product>.mock.type",
            "description" : "Type of the returned mock data, options: spdx, cycloneDX",
            "default" : "spdx"
          }
        ]
      }
    }
  ]
}

2.2.1. Test PDS standalone with pds-tools

Requires: sechub-solution-shared/scripts/01-test-pds.sh
(example with codeScan and source upload)

  1. Start your PDS solution with the 01-start-single-docker-compose.sh

  2. Export environment variables

    export PDS_SERVER=https://localhost:8444; export PDS_USERID=admin; export PDS_APITOKEN="pds-apitoken"; export PDS_PRODUCT_IDENTFIER=PDS_YOURPRODUCT

  3. Download PDS-Tools from release page https://github.com/mercedes-benz/sechub/releases

  4. Create a sechub.json like the following

    {
  "apiVersion": "1.0",
  "codeScan": {
    "use": [
      "test-sources"
    ]
  },
  "data": {
    "sources": [
      {
        "name": "test-sources",
        "fileSystem" : {
        "folders" : [ "some_source" ]
      }
      }
    ]
  }
}

  5. Create "some_source" file you want to test your product

  6. Create a pds-config.json like the following

    {
    "apiVersion" : "1.0",
    "sechubJobUUID": "288607bf-ac81-4088-842c-005d5702a9e9",
    "productId": "PDS_YOURPRODUCT",
    "parameters" : [ {
      "key" : "pds.scan.configuration",
      "value" : "{\n  \"codeScan\" : {\n    \"use\" : [ \"test-sources\" ]\n  },\n  \"data\" : {\n    \"sources\" : [ {\n      \"fileSystem\" : {\n        \"files\" : [ ],\n        \"folders\" : [ \"some_source\" ]\n      },\n      \"name\" : \"test-sources\"\n    } ],\n    \"binaries\" : [ ]\n  },\n  \"apiVersion\" : \"1.0\"\n}"
  } ]
}

  7. Put the sechub.json and the "some_source" file in a new folder <testfolder>

  8. Execute the pds-tools

    java -jar sechub-pds-tools-cli-<version>.jar generate -p <testfolder>/sechub.json -s codeScan

    The pds-tools will create a tmp folder for you in /tmp/pds_solution_genxxx/pdsJobData

  9. Copy from /tmp/pds_solution_genxxx/pdsJobData the parameter and overwrite it in your pds-config.json

  10. Copy the /tmp/pds_solution_genxxx/sourcecode.zip into your directory

  11. Execute 01-test-pds.sh with your sourcode.zip your pds-cofig.json

    ./01-test-pds.sh sourcecode.zip pds-config.json

    Single PDS setup:

    Diagram
    Figure 1. PDS user message handling

2.2.2. Test PDS solution with SecHub Server and Client

  1. Create json product executor for your product in sechub-solution/setup-pds/executors
    Tip: you can copy another executor and modify it to your needs

  2. Create setup-<my product>.sh in sechub-solution/setup-pds/
    Tip: copy another setup script and modify

  3. Create 05-start-single-sechub-network-docker-compose.sh and 05-stop-single-sechub-network-docker-compose.sh in your sechub solution directory sechub-pds-solutions/<my product>/
    Copy the files from another pds solution and modify. Your product folder should look like below:

    .
├── 01-start-single-docker-compose.sh
├── 05-start-single-sechub-network-docker-compose.sh
├── 05-stop-single-sechub-network-docker-compose.sh
├── docker
│   ├── mocks
│   │   ├── mockedResult.sarif
│   ├── pds-config.json
│   ├── scripts
│   │   ├── <my product mock>.sh
│   │   └── <my product>.sh
│   └── <my product>-Debian.dockerfile
├── docker-compose_pds_<my product>_external-network.yaml
├── docker-compose_pds_<my product>.yaml
├── env
└── README.adoc

  4. Create the docker-compose_pds_<my product>_external-network.yaml file Tip: copy files from another pds solution and modify

  5. Start the SecHub Server in sechub-solution/ with the 01-start-single-docker-compose.sh

    cd sechub-solution/
./01-start-single-docker-compose.sh

  6. Start your PDS solution with 05-start-single-sechub-network-docker-compose.sh in your PDS solution

    ./05-start-single-sechub-network-docker-compose.sh

  7. Export SecHub environment variables

    export SECHUB_USERID=admin; export SECHUB_APITOKEN='myTop$ecret!'; export SECHUB_SERVER=https://localhost:8443; export SECHUB_TRUSTALL=true; export SECHUB_WAITTIME_DEFAULT=3

  8. Run the setup pds script in sechub-solution/setup-pds/

    cd sechub-solution/
./setup-pds/<my product>.sh

  9. Download the latest SecHub Client from the release page releases

  10. Create sechub.json like the following

    {
  "apiVersion": "1.0",
  "codeScan": {
    "use": [
      "test-sources"
    ]
  },
  "data": {
    "sources": [
      {
        "name": "test-sources",
        "fileSystem" : {
        "folders" : [ "some_source" ]
      }
      }
    ]
  }
}

  11. Execute a scan with SecHub Client and test file "some_source" and sechub.json

    sechub -project <project_name> scan

  12. Download latest report with the client

    sechub -project <project_name> getReport

    PDS setup in a local SecHub network:

    plantuml::diagrams/diagram_tutorials_test_pds_solution_with_sechub.puml [format=svg, title="PDS user message handling"]