Integration

On this page, you will find an adequate checklist and step-by-step instructions to ensure the successful integration of your service with the Security Bot (SecBot) solution.

Configuration Files

The service (/.env.dev) and workflow (/app/config.yml) configuration files are updated to meet your environment’s peculiarities and issue processing needs.

If you have made additional alterations, rebuild SecBot and start it again.

$ docker-compose stop
$ docker-compose up --build
$ docker-compose up -d

Authorization

All external units that SecBot communicates with via APIs require authorization. Therefore, the user that performs the communication should have the respective tokens.

For GitLab

Sign in to your account
Click the profile icon in the upper-right corner and then click Edit profile
Click Access Token on the User Settings left-side menu
On the open page, enter your Token name, check the Expiration date, select read_api under Select scopes, and then click the Create personal access token button below

Copy Your new personal access token generated by GitLab and ensure you securely store it, as it will not be displayed again.

For DefectDojo

Log in under the admin’s (superuser’s) account
Point to the Users left-side menu and then click Users
On the open page, click the Settings toolbar button and then click New User
On the Add User page, enter the following parameters of the user that will communicate with the API:
1. Username and Password under Default Information
2. Maintainer as the Global role under Global Role
Click the Submit button and make sure that the User has been added successfully

Log in under the added user’s account
Click the profile icon in the upper-right corner and then click API v2 Key
On the open page, copy Your current API key generated by DefectDojo and ensure you securely store it.

For Slack

Go to https://api.slack.com to sign in to your workspace
Create an app; to do it,
1. Click the Your Apps menu
2. Click the Create New App button on the open page
3. Choose From scratch in the open Create an app dialog box
4. Enter your App Name and Pick the workspace where you want to install this app in the following Name app & choose workspace dialog box
5. Click the Create App button
Click the OAuth & Permissions left-side menu under Features on the app’s dashboard
Scroll down to the Scopes section and click the Add an Oath Scope button under Bot Token Scopes to select chat:write
Scroll up to the OAuth Tokens for Your Workspace section and click the Install to Workspace button
- Allow the app to access the workspace if requested
Copy your Bot User OAuth Token generated by Slack and ensure you securely store it.

Input Entity Sources

The SecBot instance responsible for receiving requests to process data triggers as soon as a relevant input event comes up. Thus, you are expected to specify these triggers for supported development and distribution platforms (Inputs).

For GitLab

Sign in under an admin’s account
Click the System Hooks left-side menu to add new or update existing system hooks
On the open page, enter in the URL text box the reference to the method used to receive information on changes made to the repository in your environment
- [host]/v1/gitlab/webhook
Enter the authentication token for your requests in the Secret token text box
Select the types of input events you want to be processed under Trigger, for example, any supported Input entity type like Push events, Tag push events, and Merge request events

Click the Add system hook or Save changes button below.

API

Communication with SecBot’s API involves providing input entities or receiving check results via the dedicated endpoints (instances). Follow

[host]:5000/docs and
[host]:5001/docs, respectively.

In the first case, mind the

Input entity (input event) type you will specify as the x-gitlab-event header parameter and the
respective payload in the request body.

A specific result is retrieved by security_check_id, which is formed by concatenating the following pieces:

input platform (e.g. git) prefix,
sha256 of the project path, and
complete commit hash.

# security_check_id example

GIT_LOCAL_d42052411d2729e637980c355cf6a8ea8e41b8688b98c34a125b71b7f2c7f76e

Pipeline

Integration of SecBot into your pipeline as an additional stage is an option we suggest that you consider. Depending on the status received upon checks, this stage might

get passed (‘success’),
stay pending (‘not_started’ or ‘in_progress’), or
fail (‘error’ or ‘fail’).

The following excerpt demonstrates a comprehensive example of how this integration can be implemented.

# Excerpt from .../pipeline.yml

...
.gate-sec-scripts:
  before_script:
    - apk add curl jq
    - SECURITY_CHECK_URL="https://[gateway_url]/v1/security/gitlab/check"
    - SECURITY_CHECK_UID="GIT_LOCAL_$(echo -n "${CI_SERVER_HOST}:${CI_PROJECT_PATH}_${CI_COMMIT_SHA}" | sha256sum | head -c64)"
  script:
    - SECURITY_CHECK_STATUS=$(curl -k -s -w " %{http_code}" $SECURITY_CHECK_URL/${SECURITY_CHECK_UID})
    - SECURITY_CHECK_STATUS_JSON=$(echo $SECURITY_CHECK_STATUS | awk '{print $1}')
    - SECURITY_CHECK_STATUS_CODE=$(echo $SECURITY_CHECK_STATUS | awk '{print $2}')
    - |
      if [ "$SECURITY_CHECK_STATUS_CODE" != "200" ]; then
        echo " Something went wrong, status: $SECURITY_CHECK_STATUS"
        exit 1
      fi
    - SECURITY_CHECK_STATUS_JSON_STATUS_DESCRIPTION=''
    - SECURITY_CHECK_STATUS_JSON_STATUS=$(echo $SECURITY_CHECK_STATUS_JSON | jq -r '.status')
    - |
      if [ $SECURITY_CHECK_STATUS_JSON_STATUS = "fail" ]; then
        SECURITY_CHECK_STATUS_JSON_STATUS_DESCRIPTION="--> Vulnerabilities found"
      elif [ $SECURITY_CHECK_STATUS_JSON_STATUS = "success" ]; then
        SECURITY_CHECK_STATUS_JSON_STATUS_DESCRIPTION="--> No vulnerabilities found"
      fi
    - echo " Response Code --> $SECURITY_CHECK_STATUS_CODE"
    - echo " Status --> $SECURITY_CHECK_STATUS_JSON_STATUS $SECURITY_CHECK_STATUS_JSON_STATUS_DESCRIPTION"
...