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 1.9.0 - Build date: 20240430152944

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.

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

1.2. Instructions

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

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

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

1.2.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!

1.2.5. 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
curl -L -o sechub-cli.zip https://github.com/mercedes-benz/sechub/releases/download/v$CLIENT_VERSION-client/sechub-cli-$CLIENT_VERSION.zip

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

# Extract
unzip sechub-cli.zip

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

# For linux arm-64
sudo cp platform/linux-arm64/sechub /usr/local/bin


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

1.2.6. Scanning

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",
  "codeScan": {
    "fileSystem": {
      "folders": [
        "."
      ]
    },
    "excludes": []
  }
}
' > sechub.json

And to do a scan, type sechub -project test-gosec scan, this will create a JSON file, which contains a report of the findings from the scan. If you want HTML output, add -reportformat html as an option: sechub -project test-gosec -reportformat html scan

The output you get, should be simillar to this(if you choose JSON output):

{
   "result": {
      "count": 4,
      "findings": [
         {
            "id": 3,
            "description": "The used method does not auto-escape HTML. This can potentially lead to 'Cross-site Scripting' vulnerabilities, in case the attacker controls the input.",
            "name": "The used method does not auto-escape HTML. This can potentially lead to 'Cross-site Scripting' vulnerabilities, in case the attacker controls the input.",
            "severity": "HIGH",
            "code": {
               "location": "source/app/app.go",
               "line": 17,
               "column": 13,
               "source": "return template.HTML(s)"
            },
            "type": "codeScan",
            "cweId": 79
         },
         {
            "id": 2,
            "description": "Use of weak cryptographic primitive",
            "name": "Use of weak cryptographic primitive",
            "severity": "HIGH",
            "code": {
               "location": "source/app/app.go",
               "line": 90,
               "column": 13,
               "source": "hash := md5.Sum([]byte(password)) // CWE-327"
            },
            "type": "codeScan",
            "cweId": 326
         },
         {
            "id": 4,
            "description": "Blocklisted import crypto/md5: weak cryptographic primitive",
            "name": "Blocklisted import crypto/md5: weak cryptographic primitive",
            "severity": "HIGH",
            "code": {
               "location": "source/app/app.go",
               "line": 7,
               "column": 5,
               "source": "\"crypto/md5\""
            },
            "type": "codeScan",
            "cweId": 327
         },
         {
            "id": 1,
            "description": "Potential hardcoded credentials",
            "name": "Potential hardcoded credentials",
            "severity": "HIGH",
            "code": {
               "location": "source/app/app.go",
               "line": 76,
               "column": 5,
               "source": "loginPassword := \"21232f297a57a5a743894a0e4a801fc3\" // CWE-257"
            },
            "type": "codeScan",
            "cweId": 798
         }
      ]
   },
   "jobUUID": "3368defe-7a45-448f-bee1-b069e754ca52",
   "reportVersion": "1.0",
   "messages": [],
   "trafficLight": "RED",
   "status": "SUCCESS"
}

1.2.7. Install SecHub’s VSCodium Plugin (OPTIONAL)

SecHub’s VSCodium Plugin helps you to work faster with the SecHub report. You can go to the exact code line and fix the problem.

You can get the plugin from here.

And to install it, open VSCodium and in the Command Pallete (Usually can be opened with Ctrl+Shift+P) type install vsix, and in the pop-up menu, choose the plugin.