SecHub Getting Started Guide

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 2.4.1 - Build date: 2024-12-18 14:20 (UTCZ)

1. Introduction

This tutorial teaches you how to scan a project using SecHub.

You will learn:

How to run SecHub and GoSec+PDS locally
Scan a vulnerable application written in Go
Install and use SecHub’s extension for VsCodium (Optional)

Figure 1. Setup Overview

This Diagram roughly explains how SecHub functions, behind the scenes.

This tutorial is tested on Debian/Ubuntu!
It should also work on different Linux distributions.

2. Prerequisites

You are going to need:

docker (Version 23.0.0 used in the tutorial, newer versions will also work) (e. g. Debian, / Ubuntu)
docker compose (v2.15.1 or newer)
git
jq
SecHub Client

Optional:

VSCodium
SecHub Extension for VSCodium

3. Setup server environment

3.1. Clone the repository

In your terminal type:

git clone https://github.com/mercedes-benz/sechub.git
cd sechub

This makes a local copy of the SecHub project on your computer and goes to the project’s folder

3.2. Start SecHub Server

The SecHub server is responsible for taking jobs and passing them to the PDS server for processing. Once the job finishes on the PDS side, they are fetched and processed by SecHub

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

This starts the server.

3.3. Start GoSec+PDS Server

The PDS server, which contains the security tool GoSec, will check the actual code for vulnerabilities and output a result of them.

Start another terminal in the root directory of SecHub and type:

./sechub-pds-solutions/gosec/05-start-single-sechub-network-docker-compose.sh

This will prepare some environment files and will start a container based on SecHub’s custom PDS+GoSec image. In the container, GoLang and GoSec will be installed and the server will be started.

3.4. Setup Project

After starting all servers, some environment variables have to be set. Specifically SECHUB_SERVER, SECHUB_USERID, SECHUB_APITOKEN, SECHUB_TRUSTALL and SecHub’s CLI tools have to be added to the PATH variable to be able to do scans. In another, we set local credentials because everything is hosted locally:

export SECHUB_SERVER=https://localhost:8443
export SECHUB_USERID=admin
export SECHUB_APITOKEN='myTop$ecret!'
export SECHUB_TRUSTALL=true
export PATH="$PATH:$(pwd)/sechub-cli/build/go/platform/linux-amd64:$(pwd)/sechub-developertools/scripts"

After setting the variables, you can run this script, which will first check if you have set the variable correctly. Then it will create a project, and create a user who will be assigned to the project. (Created user/project can be changed in the 8000-setup-gosec.sh file)

./sechub-solution/setup-pds/setup-gosec.sh

After running it, you should get a similar output if everything is working correctly:

user: gosec
project: test-gosec
Adding user: gosec
HTTP/1.1 200
HTTP/1.1 201
Creating project test-gosec.
{
  "apiVersion": "1.0",
  "name": "test-gosec",
  "owner": "gosec",
  "description": "Created by sechub-api.sh at 2023-01-01 12:00 CET"
}
HTTP/1.1 201
{
  "configurations": [
    {
      "uuid": "d23dc9ab-4a3d-4924-8d77-8026069cbd91"
    }
  ],
  "description": "Created by sechub-api.sh at 2023-01-01 12:00 CET",
  "enabled": true
}
HTTP/1.1 201
{
  "id": "pds-gosec",
  "description": "Created by sechub-api.sh at 2023-01-01 12:00 CET",
  "enabled": true,
  "configurations": [
    {
      "name": "pds-gosec",
      "productIdentifier": "PDS_CODESCAN",
      "setup": {
        "baseURL": "https://pds-gosec:8444",
        "credentials": {
          "user": "techuser",
          "password": "pds-apitoken"
        },
        "jobParameters": [
          {
            "key": "pds.config.productidentifier",
            "value": "PDS_GOSEC"
          },
          {
            "key": "pds.config.use.sechub.storage",
            "value": "false"
          },
          {
            "key": "pds.mocking.disabled",
            "value": "true"
          },
          {
            "key": "sechub.productexecutor.pds.timeout.minutes",
            "value": "60"
          },
          {
            "key": "sechub.productexecutor.pds.timetowait.nextcheck.milliseconds",
            "value": "500"
          },
          {
            "key": "sechub.productexecutor.pds.trustall.certificates",
            "value": "true"
          }
        ]
      },
      "executorVersion": 1,
      "enabled": true,
      "uuid": "d23dc9ab-4a3d-4924-8d77-8026069cbd91"
    }
  ],
  "projectIds": []
}
Created executor and profile
project: test-gosec
profile: pds-gosec
Assigned profile pds-gosec to project test-gosec

Setup of GoSec complete:

- user: gosec
- project: test-gosec

Now you are ready to do scans!

4. Scan using SecHub Client

4.1. Install SecHub Client

The SecHub Client is needed to scan. In later sections of this guide, the client is used to scan an example. The command below, will download the latest version and put it in your /usr/local/bin folder.

# Get latest version
CLIENT_VERSION=`curl -s https://mercedes-benz.github.io/sechub/latest/client-download.html | grep https://github.com/mercedes-benz/sechub/ | awk -F '-' '{print $NF}' | sed 's/.zip">//'`

# Download the zipped binary
wget https://github.com/mercedes-benz/sechub/releases/download/v$CLIENT_VERSION-client/sechub-cli-$CLIENT_VERSION.zip

# Verify the binary
wget https://github.com/mercedes-benz/sechub/releases/download/v$CLIENT_VERSION-client/sechub-cli-$CLIENT_VERSION.zip.sha256
sha256sum --check sechub-cli-$CLIENT_VERSION.zip.sha256

# Extract
unzip sechub-cli-$CLIENT_VERSION.zip

# Depending on your architecture and OS, you will have to copy a different binary file:
# Example for Linux x86-64
sudo cp platform/linux-amd64/sechub /usr/local/bin

# Cleanup
rm -rf sechub-cli-$CLIENT_VERSION.zip sechub-cli-$CLIENT_VERSION.zip.sha256 platform/

4.2. Scan

Now you can go to another project’s directory and do a scan for vulnerabilities. In this example, we will use vulnerable-go, but you are free to use any other project!

Before starting the scan, you need a sechub.json in the root directory of the project you are scanning, which tells which files to be scanned, and which to be skipped. You can either copy the one in SecHub’s folder or create your own.

Here’s a bare-bones example:

echo '
{
  "apiVersion": "1.0",
  "project": "test-gosec",
  "codeScan": { "use": [ "sourcecode" ] },
  "data": {
    "sources": [
      {
        "name": "sourcecode",
        "fileSystem": { "folders": [ "." ] }
      }
    ]
  }
}
' > sechub.json

Now you can do a scan, type sechub scan, this will create a file which contains a report of the findings from the scan (JSON format). If you want the report in HTML format instead, add -reportformat html as an option: sechub -reportformat html scan

5. Optional

5.1. SecHub’s IDE plugins

SecHub’s IDE plugins help you to work faster with the SecHub report. You can jump to the exact code lines and fix the problem.

5.1.1. Eclipse Plugin

You can get the SecHub plugin the usual way from the Eclipse Marketplace.

5.1.2. IntelliJ Plugin

You can get the SecHub plugin the usual way from the IntelliJ Marketplace.

5.1.3. VS-Codium / Visual Studio Code Plugin

You can get the plugin from the OpenVSX Registry.

To install it, search for sechub in the Extensions manager and choose the one from "mercedes-benz".

For Visual Studio Code users: Download the Plugin and install it manually from file.