Integrations

Introduction

We provide several integrations to various tools to ease the use of our services in your workflow.

With the help of our integrations to issue/ticket systems your developers can easily be kept up-to-date about relevant vulnerabilities affecting your products and start dealing with them. Furthermore, thanks to integrations with different CI/build systems you will always know the security of your products at any given time. Lastly, with the help of our integrations to collaborations tools you can easily discuss and monitor the latest vulnerabilities.

Locally/custom pipelines

Debricked CLI

We provide a Command Line Tool (CLI) for interacting with Debricked. It supports uploading and checking your dependency files for vulnerabilities from your console. This could be useful when you want to check whether your dependency files are vulnerable before uploading them to your repository or in a custom CI pipeline. This tool also powers some of our integrations, such as the Bitbucket “pipe” integration.

Installation

  1. a) Install using composer (recommended, omit global if you want to install into current project) composer global require debricked/cli, or
    b) Download it manually from GitHub
  2. Done! You can now run any of the available commands using ~/.composer/vendor/debricked/cli/bin/console *command*

Available commands

All commands have a help command available listing possible arguments and options by passing the flag “help”, for example:

bin/console debricked:scan --help
All-in-one vulnerability scan

Combines uploading dependency files with monitoring their vulnerability status.

bin/console debricked:scan *username* *password* *product_name* *release_name*
Upload dependency files and trigger a vulnerability scan
bin/console debricked:find-and-upload-files *username* *password* *product_name* *release_name*
Check vulnerability scan
bin/console debricked:check-scan *username* *password* *upload_id*

Issue/ticket systems

Jira

We natively integrate with Jira using their Rest API available in Jira version 6 and newer. We support both the self-hosted version and Jira cloud.

In order to use our integration you need to be logged in as a company admin and then head over to website settings. At the website settings page you need to:
1. Click at the Integrations tab
2. Expand the Ticket/issue systems accordion
3. Scroll down to the Atlassian’s Jira API connections headline
4. Hit the plus button
5. Enter your ticket system host (The base address to your Jira instance)
6. Enter your Project ID. If you you don’t know your Project ID (Not the same as Project Key) you can get it by visiting jira_address.com/rest/api/2/project/your_project_key in a browser which supports displaying JSON (such as Firefox). Where jira_address is your system host entered in previous step and your_project_key is your Project Key which you can find in the projects overview, see image:
Jira projects overview
7. Enter any labels, comma separated, you want to add to created issues.
8. You can specify to create issues only for selected products which have one or more of the tags specified. By default issues are created when any product receives a (new) vulnerability.
9. Specify which action(s) should trigger a ticket to be created/updated. For each triggering action you can specify to add specific labels, these labels are then removed whenever another action is triggered (if multiple triggers are configured).
10. Enter your Jira username.
11. Enter your Jira API token. You can get a token by following this guide Atlassian – API tokens.
12. Optionally you can specify a Security ID to assign to all created and updated issues.
13. Enter the ID for “open” transition. You can get the ID by vising an existing issue in your chosen project and hover over the different statuses. While hovering the ID will be available in the displayed URL after the query parameter “action=”, see image:
Jira transition ID
14. Enter the ID for “close” transition. Get the ID in the same way as you did in 13., but for closing status.
15. Enter the ID for issue type you want to assign to new issues. In order to find the right ID you need to, similar to step 6, visit your Jira instance at your_jira.com/rest/api/2/issuetype/ in a supported browser.

See image for an example configuration:
Jira integration configuration example

GitLab

Getting started with GitLab is very easy and requires only a handful of things to be filled in. Our integration uses GitLab’s Rest API V4, available in GitLab 9.0 and newer.

In order to use our integration you need to be logged in as a company admin and then head over to website settings. At the website settings page you need to:
1. Click at the Integrations tab
2. Expand the Ticket/issue systems accordion
3. Scroll down to the Atlassian’s Jira API connections headline
4. Hit the plus button
5. Enter your ticket system host (The base address to your GitLab instance)
6. Enter your project ID, either its ID or its URL/namespace, see example image at the end.
7. Enter any labels, comma separated, you want to add to created issues.
8. You can specify to create issues only for selected products which have one or more of the tags specified. By default issues are created when any product receives a (new) vulnerability.
9. Specify which action(s) should trigger a ticket to be created/updated. For each triggering action you can specify to add specific labels, these labels are then removed whenever another action is triggered (if multiple triggers are configured).
10. Enter your private token/personal access token. You can create an access token by going to your GitLab profile, click Access Tokens and then create a token. It is important that the access token has the api scope checked.

Warning

The access token must have the api scope.

See image for an example configuration:

GitLab integration configuration example

GitHub

With our issue integration to GitHub our GitHub bot will automatically create GitHub issues for you whenenver you have a new vulnerability or take certain actions on your projects’ vulnerabilities.

  1. Start by installing our GitHub app, see instructions for the CI integration.
  2. Head over to the service settings page as a company admin.
  3. Click at the Integrations tab
  4. Expand the CI (Continuous Integration) systems accordion
  5. Enter any labels, comma separated, you want to add to created issues.
  6. You can specify to create issues only for selected products which have one or more of the tags specified. By default issues are created when any product/repository associated with your GitHub account/organisation receives a (new) vulnerability.
  7. Specify which action(s) should trigger a issue to be created/updated. For each triggering action you can specify to add specific labels, these labels are then removed whenever another action is triggered (if multiple triggers are configured).

See image for an example configuration:

GitHub issue integration configuration example

CI/Build systems

GitHub

With our CI integration to GitHub you can automatically upload your latest commits and pull requests to Debricked. Best of all, it only takes a couple of minutes to set up!
Status of a single commit

Installation

  1. Start by heading over to https://github.com/apps/debricked/.
  2. Click on install button in the top right corner.
    GitHub App - Homepage
  3. Choose your personal account or your organisations’ account.
    GitHub App - Choose where to install
  4. If you haven’t entered your password in a while you might be have to re-enter your personal account password.
    GitHub App - Confirm your password
  5. a) If installing to a personal account or an organisation account where you are an admin, you will be able to select which, or all, repositories which you want to install the integration to.
    GitHub App - Install to personal account
    b) If not, you will still be able to select which, or all, repositories which you want to install the integration to, but an organisation admin will have to approve your installation request.
    GitHub App - Request to install to organisation
  6. If installation was successful, you or your organisation admin will be redirected to Debricked’s service settings. A popup will be shown letting you trigger a first time scan of your repositories.
    Debricked - Manual scan of GitHub repositories

Triggering manual scan and verifying installation

If installation was added successfully, you should now have a new installation entry on the Integrations, GitHub CI tab, see image below. You can also manually trigger new scans by hitting the “Open repository scanner” button.
Debricked - Service settings

Bitbucket

With our CI integration to Bitbucket you can automatically upload your latest commits and pull requests to Debricked or whenever you run your pipeline. Just like with GitHub integration it just takes a few minutes to set up!

  1. Start by heading over to our Bitbucket pipe, it contains instructions on how to configure your Bitbucket pipeline to take advantage of Debricked’s pipe.
  2. Go to your repository and configure your bitbucket-pipelines.yml file.
  3. Commit the changes to your bitbucket-pipelines.yml and watch the pipeline run! Example output:

Bitbucket Debricked Pipe - Example run

For more information on Bitbucket Pipes, please visit https://confluence.atlassian.com/bitbucket/pipes-958765631.html. You can also take a look at our example repository which uses the Debricked pipe in the pipeline.

BitBake

Planned

GitLab

With our CI integration to GitLab you can automatically upload your latest commits and pull requests to Debricked or whenever you run your pipeline. Just like our other CI integrations it just takes a few minutes to set up!

  1. Go to your repository and add the following to your .gitlab-ci.yml file:
# Vulnerability scanning
test:vulnerabilities:
    stage: test

    image:
        name: debricked/debricked-scan
        entrypoint: ["/gitlab-ci.sh"]

    script: echo "Done"

    variables:
        USERNAME: $DEBRICKED_USERNAME # Your Debricked username
        PASSWORD: $DEBRICKED_PASSWORD # Your Debricked password
        # For all options, please check https://bitbucket.org/debricked/debricked-scan
  1. Configure your DEBRICKED_USERNAME and DEBRICKED_PASSWORD variables by heading over to your repository -> Settings -> CI/CD -> Environment variables, see image below:
    GitLab CI - Environment variables setup
  2. Commit your changes to .gitlab-ci.yml and watch the CI run!
    GitLab CI - Example run
Tip

Our GitLab integration support the same options as our Bitbucket integration, read more about the options here https://bitbucket.org/debricked/debricked-scan

Travis

Planned

Jenkins

Planned

Collaboration tools

Slack

Planned

My XYZ is not supported!

If your favourite tool is not listed above you can either suggest it to us at our feedback page or create a custom integration using our Rest API.

Need assistance?

Contact our technical support at oscar.reimer@debricked.com

Updated on 2019-06-18

Was this article helpful?

Related Articles