Protecting GitHub with SGNL

Introduction

Protected Systems are applications, services, or infrastructure that you want to protect with SGNL. In this guide, we’ll enhance access control for your GitHub Enterprise, Organization, and/or Repositorires by integrating them with SGNL’s Continuous Access Evaluation platform.

With this integration, GitHub need not know about the policies, systems of record, or any of the data in SGNL - it simply needs to pass to SGNL:

• Who/What is requesting the access (The Principal)
• (Optional) What is attempting to be accessed (The Asset)
• (Optional) What operation is being attempted on the asset (The Action)
• An access token that ensures the Protected System is a legitimate caller into SGNL

Prerequisites

• A GitHub Environment with GitHub Actions enabled and a User Account that can create and modify GitHub Workflows
• A self-hosted runner in GitHub running Linux, details for deploying a self-hosted runner are available from GitHub’s Documentation
• (For GitHub Enterprise Server) A connection between your Enterprise Server and GitHub.com with GitHub Connect
• A SGNL Client
• A SGNL User Account with Admin privileges
• At least 1 system of record integrated to SGNL, containing principals and (optionally) assets that will be evaluated in access evaluations
• (Optional) 1 or more policies that you want assigned to the integration

Creating a Protected System in SGNL

1. Log-In to your SGNL Client with an Admin Account
2. From the left navigation pane, select Protected Systems and Add, or simply click Add from the SGNL Dashboard
3. Select ‘GitHub’ from the Development category in the list of integrations
4. Give your integration a descriptive display name and description
5. Specify the Default Policy to be applied to GitHub
   • Deny: If no policies provide a decision for an access request, SGNL will respond to the access request with a Deny decision
   • Allow: If no policies provide a decision for an access request, SGNL will respond to the access request with an Allow decision
6. Next, you’ll need to configure which identifier GitHub is using to describe your user/principal
   • In the case of GitHub, this is probably your GitHub username (as is configured in the GitHub action), however this may be an email address or Username that can be found in your IdP
7. You’ll also need to define an asset to protect
   • This might be as simple as the names of the GitHub Repositories you’re protecting
8. Once configured, click Continue to save your GitHub configuration and move on to other configuration steps

Configuring Authentication

1. Authentication ensures that only authorized systems can make requests into SGNL, as well as verifying the identity of an integration in order to effectively evaluate Policies - to access Authentication settings, open your GitHub protected system and select the Authentication tab

   

2. Click Generate Token

3. Give your token a descriptive name so that you know how it’s being used in the future and click to Generate Token

   

4. On the next screen, copy the token - this will be used by GitHub to make access requests to SGNL using the SGNL Access Service API

   Note: The value of this token is not available again after this screen, so ensure you securely store it for steps later in this guide

   

Integrating GitHub with SGNL using GitHub Actions

The SGNL Policy Action GitHub Action enables you to call the SGNL Access API from a GitHub Actions workflow. You can use this policy check to determine if the GitHub user is allowed to execute or trigger the workflow in question based on a policy definition in SGNL.

Configure Repository Settings

1. To get started, sign-in to your GitHub environment with a account that has the Role: Admin for a Repository you’d like to protect
2. Go to Settings for the Repository, and select ‘Secrets and variables’ from the left menu
3. Select Actions and create a New Repository Secret with the name of SGNL_TOKEN, with the value of the Access Token you securely copied from SGNL in the last section

Configure your Workflow

1. From within the chosen repository, select Actions from your top navigation menu and on the left-hand side, click ‘New Workflow’ to create a new workflow
2. Choose to ‘set up a workflow yourself’
3. A sample workflow is below that is triggered when Pull Requests are Opened, Synchronized, or ReOpened - where a request is made to the SGNL service for the GitHub User for the given Repository (it is recommended to familiarize yourself with GitHub’s Workflow Syntax) pull_request.yml

name: SGNL Pre-Check On PR Changes

on:
  pull_request:
    types: 
      - opened
      - synchronize
      - reopened

jobs:
  sgnl_check:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: SGNL Policy Check
      id: sgnl
      uses: https://github.com/SGNL-ai/policy-action@v1
      with:
        token: ${{ secrets.SGNL_TOKEN }}
        principalId: ${{ github.actor }}
        action: 'deploy'
        assetId: ${{ github.repository }}
        bypassMode: false
  
    - name: Print SGNL Output
      id: sgnl_output
      run: >
        echo "Decision '${{ steps.sgnl.outputs.decision }}', 
        Reason '${{ steps.sgnl.outputs.reason }}'"

1. The workflow will use the Secret stored in the GitHub secret store in order to call into the SGNL Platform and perform an access evaluation, with the result being made available in the Worklow Run Logs

Run SGNL-ai/policy-action@v1
  with:
    token: ***
    principalId: marc-sgnl
    action: deploy
    assetId: SGNL-ai/sgnl-github-demo
    bypassMode: false
    domain: access.sgnlapis.cloud

Run echo "Decision 'true',  Reason ''"
  echo "Decision 'true',  Reason ''"
  shell: /usr/bin/bash -e {0}
Decision 'true',  Reason ''

1. The Workflow can be extended beyond Pull Requests to encompass an organization’s whole continuous deployment pipeline, with SGNL brokering the issuance of short-term, scoped credentials for Action deployments to CSP environments. If you’d like to learn more, contact your Account team or Get a Demo

Assigning Policies

1. Once the Integration is created, you can start assigning versions of Policies to the integration - to get started, select Policies from the tabs in your newly created integration

   

2. Select ‘Assign Policies’

3. Select:

   • The Policies you want to apply to the integration with the check box
   • The version of the Policy you want applied

   

4. Click Next once you have the Policies and Versions configured as is appropriate

5. Select the Enforcement mode for the Policies you chose in the previous step

   • Simulated: Policy Versions that are being simulated will only log their access decision in the SGNL logs and will not impact the access decision that SGNL hands back to an integration. Simulated policies are useful for performing what-if analysis of new policy versions as well as debugging policy changes.

     Note: It’s considered best practice to start with policies in Simulated mode, to verify that policies have been created an applied as expected

   • Enforced: Policy Versions that are being enforced will impact the access decisions that SGNL hands back to an integration. Enforced Policies will determine access for an integration

   

6. Select your desired Enforcement mode and select Assign

7. Versions of Policies will now be Assigned to your integration

   

Next Steps

Once your Protected System is configured, it’s time to start testing. You can learn more about managing, troubleshooting, and auditing policies in our Policy Section.