# Team Onboarding - GitHub App

Jump to

  1. For admins
    1. Connect Repos
    2. Set up automation rules
  2. For users
    1. How to access
    2. Where to find Debricked
    3. How to make checks pass

# For admins

# Connect repos

The Debricked GitHub app has two main configurations that affect how you connect repos. It can be configured to:

  1. Connect to all repos in your organization
  2. Connect only to selected repos

# Configuration 1 - All repos

Steps

  1. Push a commit to the repo you want to connect
  2. That's it!

Commits are automatically picked up and scanned by the Debricked GitHub app.

As the scan is completed, results will be available in the GitHub check for the commit and in the Debricked UI - and all future pushes will be scanned automatically.

# Configuration 2 - Select repos

Steps

  1. Navigate to Github -> Settings -> Applications and choose configure Debricked
  2. Select the repos you want to connect from the dropdown and click save
  3. Push a commit to the now connected repo

Commits are now automatically picked up and scanned by the Debricked GitHub app.

As the scan is completed, results will be available in the GitHub check for the commit and in the Debricked UI - and all future pushes will be scanned automatically.

Configure Debricked GitHub App

# Set up automation rules

Your automations controls what developers see and act on. Setting good automation rules means creating and enforcing beneficial behaviours. All repos gets a set of default rules as they are connected.

Steps

  1. In debricked.com (opens new window), navigate to your repos automation page
  2. Review the default rules and disable or delete unwanted rules
  3. Modify existing rules or create your own custom rules to fit your use case

See Getting Started With Automations to learn all about automations.

# For users

# How to access

  1. Visit debricked.com (opens new window)
  2. Click on login with GitHub
  3. Grant Debricked the right to SSO login
  4. Select your company's organization
  5. Select your email address
  6. Enter your name and complete the signup

Sign-up flow GitHub

# Where to find Debricked

# GitHub Checks

In the GitHub check you can see the scan results, and progress. You find it by clicking the symbol next to the commit hash. Find GitHub Check

The contents of the GitHub Check are:

  • The amount of vulnerabilities found in the repo
  • Which automation rules were checked
  • Which automations were triggered
  • What triggered the automations

You can always click on the vulnerabilty identifier or the dependency name to get more information, suggested fixes and fix Pull Requests

Example of a rule that fails the GitHub check: Rule Failing GitHub Check

There are three main types of automation rules

  • Rules that fail the GitHub Check
  • Rules that throw a warning in the GitHub Check
  • Rules that do not affect the GitHub check (such as rules sending an email)

# Debricked UI

The UI contains everything you want to know about your dependencies and their vulnerabilities.

Get suggestions on fixes, automatic fix Pull Requests, detailed descriptions of vulnerabilites. Configure your automations, find high risk licenses and review if you're affected by discovered vulnerabilities.

# Pull Requests (PRs)

The Opened PRs contains useful details about the vulnerability(ies) it fixes, their severity and links to further reading. Pull Request Message

# Emails

Don't want to check the GitHub checks? Get emails showing you exactly what trigged a rule instead.

# How to make checks pass

What is required to make a check pass is dependent on the rule that failed. Based on the rule you may need to fix or review a vulnerability, or if there's a license violation - remove a dependency all together.

You can fix vulnerabilities in 2 ways, explained next.

# Fix vulnerabilities using Pull Requests

Pull Requests are currently only available for JavaScript (Yarn and npm)

There are two types of Pull Requests openened by Debricked.

  1. Lock file-fixes
  2. Deep fixes

Lock file fixes work by updating indirect dependencies (dependencies of dependencies) within the version range as specified by their parent dependency. This minimizes risk of breaking changes, but doesn't cover all cases.

Deep fixes work by figuring out which version of the direct dependency (the one you imported) contains a safe version of the vulnerable indirect dependency. This is useful in cases where the fixed version is outside of the allowed version range, as it's not possible to update the indirect dependency directly in those cases.

Deep Fix Visualization

To learn more about how PRs work, visit our blogpost on the subject (opens new window).

Steps

  1. Navigate to the repo in the Debricked UI
  2. Click on Open PR and select a target branch
  3. Click confirm
  4. Run the changes through your tests and merge

This opens a PR with all possible lock file fixes and often allows you to fix a large chunk of your vulnerabilties in one PR.

  1. Go back to the repo in the Debricked UI
  2. Go into each vulnerability and click Open PR from there
  3. Click confirm

This opens deep fixes for the vulnerabilities that were not solved by the lock file fix. Make sure to properly test the changes, as there's a risk of breaking changes due to possibly large version jumps required to fix vulnerabilities.

Open Deep Fix PR

# Fix vulnerabilities using Suggested Fix

Suggested fix can be used when PRs are not supported for your package manager. It shows you which version you need to update the vulnerable dependency to - equivalent to the lock fixes, but not necessarily within the set version range.

Steps

  1. Navigate to a vulnerability in the Debricked UI
  2. Open Suggested Fix
  3. Review if the suggestion is within the specified version range

If it is, update the dependency using your package manager. If not:

  1. Find the direct dependency of the vulnerable dependency
  2. Find a version of the direct dependency that contains the safe version of the vulnerable dependency
  3. Update the direct dependency using your package manager

Suggested Fix

# Review Vulnerabilities

Steps

  1. Navigate to the vulnerability in the Debricked UI
  2. Set a review status by marking the vulenrability as vulnerable or unaffected in the review status section.

Review Status Section