Code Setup

GitHub

Overview

Heeler connects at the organization level and uses GitHub Apps. The Heeler GitHub app requires these permissions:

• Read-Only Metadata: A mandatory permission for GitHub applications to gather information about the repositories in your environment.

• Read-Only Content: Permission to read the contents of repositories in order to run checks and correlate services.

• Read and Write Checks: Permission to run checks against Pull Requests and update Check Status upon check completion.

• Read and Write Pull Requests: Permission to track the Pull Request process and open pull requests to fix security issues.

• Heeler Subscribes to webhook events for “Pull Request”, “Release”, and “Push”. These allow for Heeler to have real-time processing of repository changes and manage Pull Request processes.

Requirements

• To install the Heeler GitHub app, you must be an organization owner or have administrative permissions for the repositories you wish to connect to Heeler.

Setup

1. Select the icon from the top navigation
2. Select Connections -> Code Organizations then select 'Add Code Organization'

3. You will be redirected to GitHub to authorize the Heeler GitHub App.

4. Select whether you want Heeler to secure all repositories or limit to a specific set of repositories.

5. Click Save and that's it, Heeler is now connected to your GitHub repositories.

---

GitLab

Overview

Heeler connects to GitLab at the group level and integrates into GitLab Pipelines to automate assessment code and dependencies. The permission scopes required by Heeler are:

• GitLab role: Reporter

• read_api : This is a mandatory permission to allow Heeler to gather information about the groups and projects in your environment.

• read_repository : This is a mandatory permission to read contents of the repositories in order to run security analysis and correlate Heeler Services to source code repositories.

Requirements

• A GitLab group with access to the projects you want Heeler to analyze

• Ability to create Gitlab Group access token

• Group access token with required permission scopes

Create GitLab Access Token

Connect Heeler to GitLab

1. Select the icon from the top navigation
2. Select Connections -> Code Organizations then select 'Add Code Organization'

3. Enter a name that helps tie the token to the Group

4. Copy the GitLab Project access token to Heeler

5. Upon saving the name and token, copy the Installation Token to create the CI/CD Variable

Create GitLab CI/CD Variable

Use the Installation Token provided in the Heeler GitLab setup for the value of the variable. The token enables secure communication between the Heeler image and platform.

Setup Heeler Job Config for CI/CD Pipeline

Job Config YAML

stages:
  - heeler

heeler-gitlab-job:
  stage: heeler
  image: <path to registry for Heeler image>
  script:
    - echo "Running sca scan..."
    - /app/heeler-gitlab-job sca
    - echo "Running oss analysis..."
    - /app/heeler-gitlab-job oss
    - echo "Running sast scan..."
    - /app/heeler-gitlab-job sast
    - echo "Running fingerprint..."
    - /app/heeler-gitlab-job fingerprint --sourceid gitlab-test
    - echo "Heeler CI/CD scan complete"
  artifacts:
    paths:
      - ./heeler-sast-scan.json
      - ./heeler-sca-scan.json
      - ./heeler-oss-results.json
    access: all
    expire_in: 30 days

Add the job configuration to the desired CI/CD pipeline.

Description of jobs

• SCA Scan - enumerates packages and vulnerabilities with output to heeler-sca-scan.json

• SAST Scan - scans source code for secrets, PII, and security defects with output to heeler-sast-scan.json

• OSS Analysis - runs license checks, dependency scorecard, and malicious package analysis with output to heeler-oss-results.json