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: Server 2.3.1 modified (commit 7de5e5c) - Build date: 2024-11-27 09:48 (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)
This Diagram roughly explains how SecHub functions, behind the scenes.
This tutorial is tested on Debian/Ubuntu! |
2. Prerequisites
You are going to need:
Optional:
-
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
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/
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. 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 Palette
(Usually can be opened with Ctrl+Shift+P
) type install vsix
, and in the pop-up menu, choose the plugin.