GitHub

This guide walks you through setting up Endura pipeline security for GitHub Actions. You will learn how to run the Runtime Sensor on both GitHub-hosted and self-hosted runners, configure the GitHub integration for automatic pipeline discovery, instrument your GitHub Actions workflows to use the Sensor, and apply security policies to your pipelines.

Prerequisites

Before proceeding, ensure you have:

• Team Server installed and running with valid credentials for accessing the web interface. If you have not deployed Team Server yet, see the Team Server documentation for deployment options.
• Administrative access to your GitHub organization for creating access tokens and configuring workflows.
• For self-hosted runners: root or sudo access to the runner hosts (for installing the Runtime Sensor).
• For GitHub-hosted runners: an Endura license key and Sensor token stored as encrypted repository or organization secrets (used to install the Sensor at workflow runtime).

Configure the GitHub Integration

The GitHub integration enables Team Server to discover and ingest your GitHub repositories as pipelines. This section covers creating a GitHub personal access token and configuring the integration in Team Server.

Create a GitHub Personal Access Token

GitHub personal access tokens allow Team Server to authenticate with the GitHub API to discover repositories and workflow runs.

Setup Instructions:

1. Log in to GitHub as the account that will own the integration token
2. Click your profile photo in the top-right corner and click Settings
3. In the left sidebar, click Developer settings
4. Click Personal access tokens, then choose one of the following:
   • Fine-grained tokens (recommended): grant the token Read-only access to the relevant organizations and repositories, with the Actions and Metadata repository permissions set to Read-only
   • Tokens (classic): select the repo scope (for private repositories) and the read:org scope so Team Server can enumerate organizations and repositories
5. Set an expiration appropriate to your security requirements, and document a token rotation schedule
6. Click Generate token
7. Copy the token value immediately; it will not be shown again

Add the Integration in Team Server

With the GitHub personal access token created, configure the integration in Team Server.

Setup Instructions:

1. Log in to Team Server
2. Click Integrations in the main navigation menu
3. Click GitHub under the Discover sub-navigation menu
4. Click Get Started (if no GitHub integration exists) or Create (if you already have one or more GitHub integrations configured)
5. Configure the integration:
   • URL: Enter the base URL of your GitHub instance. Use https://github.com for GitHub.com, or your server URL for GitHub Enterprise Server (e.g., https://github.example.com)
   • Token: Paste the personal access token you created in GitHub
6. Click Test to verify the connection to GitHub
7. After a successful test, the Organizations field populates with the organizations your token can access. Select one or more organizations to monitor
8. Click Save to create the integration

Once the integration is created, Team Server immediately begins discovering and ingesting the repositories in the selected organizations as pipelines. View the discovered pipelines by clicking Pipelines in the main navigation menu.

Enable Scheduled Discovery

The initial integration setup performs a one-time discovery of GitHub repositories. To automatically discover new repositories and workflow runs on an ongoing basis, configure the scheduled discovery jobs in your Team Server configuration.

Add the discover_github_pipelines and discover_github_builds jobs to the scheduler section of your Team Server configuration file (config/production.yaml):

scheduler:
  jobs:
    discover_github_pipelines:
      run: "discover_github_pipelines"
      schedule: "0 0 * * * * *"
    discover_github_builds:
      run: "discover_github_builds"
      schedule: "0 */15 * * * * *"

The schedule field uses a 7-field cron format: second minute hour day month day-of-week year. The examples above run pipeline discovery every hour and build discovery every 15 minutes.

A complete scheduler configuration including the GitHub discovery jobs alongside the required Team Server jobs:

scheduler:
  output: stdout
  jobs:
    discover_github_pipelines:
      run: "discover_github_pipelines"
      schedule: "0 0 * * * * *"
    discover_github_builds:
      run: "discover_github_builds"
      schedule: "0 */15 * * * * *"
    calculate_statistics:
      run: "calculate_statistics"
      schedule: "0 0 5 * * * *"
    update_status:
      run: "update_status"
      schedule: "0 */5 * * * * *"

After updating the configuration, restart Team Server for the changes to take effect. For restart procedures specific to your deployment method, see:

• Docker Deployment
• Podman Deployment
• Kubernetes Deployment

For additional configuration details, see the Team Server Configuration Guide.

Install the Runtime Sensor on Self-Hosted Runners

If your workflows run on self-hosted runners, install the Runtime Sensor once on each runner host. The Sensor monitors build execution and enforces security policies at runtime. If you use GitHub-hosted runners, skip this section; the Sensor is installed within the workflow instead (see GitHub-Hosted Runners).

Installation Overview

Install the Runtime Sensor on each self-hosted runner host:

1. Identify all hosts running self-hosted runners that execute the workflows you want to monitor
2. Install the appropriate Runtime Sensor package for each host’s Linux distribution
3. Configure the Sensor to communicate with Team Server

For detailed installation instructions specific to your Linux distribution, see the Runtime Sensor documentation.

Runner Groups

GitHub organizes self-hosted runners into runner groups for access control and workload distribution. When deploying the Runtime Sensor:

• Identify all runner groups that run workflows you want to monitor
• Install the Sensor on every runner host within those groups
• When adding new runners to a group, include Sensor installation in your runner provisioning process

For auto-scaling or ephemeral self-hosted runners (e.g., runners provisioned on demand), bake Sensor installation into the runner image or provisioning scripts so new runners automatically receive the Sensor.

Configure GitHub Actions Workflows

With the integration configured, instrument your GitHub Actions workflows to communicate with the Sensor. Choose the pattern that matches your runner type.

Self-Hosted Runners

When the Sensor is already installed on the runner host, your workflow only needs to bracket the build with endura job start and endura job stop. Add the start command as the first step and the stop command as a final step guarded with if: always() so it runs even when a preceding step fails.

jobs:
  build:
    runs-on: [self-hosted, linux]
    steps:
      - name: Start Endura Job
        run: endura job start

      # ... your existing build steps ...
      - uses: actions/checkout@v4
      - name: Build
        run: make build

      - name: Stop Endura Job
        if: always()
        run: endura job stop

Key points:

• runs-on targets your self-hosted runners (using a label such as self-hosted and any additional labels you assign).
• The Start Endura Job step must be the first step in the job.
• The Stop Endura Job step must be the last step and use if: always() so it runs on both successful and failed jobs.

GitHub-Hosted Runners

GitHub-hosted runners are ephemeral, so the Sensor is installed and started inside the workflow run. Add a step that installs and starts the Sensor and then starts the Endura job, and a final step (guarded with if: always()) that stops the job and the Sensor.

name: CI
on:
  push:
    branches:
      - main
  workflow_dispatch:

defaults:
  run:
    shell: bash

env:
  ENDURA_TEAM_SERVER: https://teamserver.example.com
  ENDURA_BATCHER_AUTOFLUSH: true

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Start Runtime Sensor and Job
        run: |
          curl -sSf https://repo.endurasecurity.com/install/endura-sensor/testing.sh | sudo -E sh
          sudo -E endura sensor start -d
          echo "started endura sensor: $(sudo -E endura sensor status)"
          ENDURA_JOB_ID=$(endura job start)
          echo "started endura job with id ${ENDURA_JOB_ID}"
        env:
          ENDURA_LICENSE_KEY: ${{ secrets.ENDURA_LICENSE_KEY }}
          ENDURA_SENSOR_TOKEN: ${{ secrets.ENDURA_SENSOR_TOKEN }}

      - name: Checkout Code
        uses: actions/checkout@v4

      # ... your existing build steps ...
      - name: Build
        run: make build

      - name: Stop Endura Job and Sensor
        if: always()
        run: |
          endura job stop
          sudo -E endura sensor stop

The environment variables configure the Sensor that the workflow installs at runtime:

These are the variables most relevant to CI/CD instrumentation. For the complete list of sensor environment variables and their defaults, see the Runtime Sensor Configuration reference.

Verify the Configuration

Run a workflow to verify your configuration is working correctly.

Setup Instructions:

1. Commit and push the instrumented workflow, or trigger it manually from the Actions tab in GitHub
2. Wait for the workflow run to complete
3. Log in to Team Server
4. Click Pipelines in the main navigation menu
5. Locate your repository in the pipeline list
6. Click the Edit (pencil icon) button for the pipeline
7. Click the Builds tab
8. Verify that a new build entry appears for the workflow run you just triggered

If the build appears in Team Server, your configuration is working correctly. Proceed to create and assign security policies.

Standardize Workflows at Scale

For organizations managing many repositories, adding the Endura steps to every workflow individually does not scale. GitHub provides several mechanisms to centralize and reuse workflow logic. Each works with both runner types: encapsulate the self-hosted or GitHub-hosted instrumentation shown above so individual repositories adopt it with a single reference.

Composite Actions

Package the Endura start and stop logic as a composite action published in a central repository, then reference it from any workflow:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Start Endura Job
        uses: your-org/endura-actions/start@<commit-sha>

      # ... your existing build steps ...

      - name: Stop Endura Job
        if: always()
        uses: your-org/endura-actions/stop@<commit-sha>

Maintaining the action in one place lets you update the instrumentation for all consuming repositories by publishing a new version.

Reusable Workflows

Define a reusable workflow (on: workflow_call) in a central repository that wraps build work with the Endura start and stop steps. Repositories then call it with a single uses: reference, inheriting the instrumentation automatically.

Organization-Wide Distribution and Enforcement

• Starter workflows: Publish starter workflows in your organization’s .github repository so new repositories can adopt an Endura-instrumented workflow with one click.
• Required workflows: Use required workflows / repository rulesets to enforce an Endura-instrumented workflow across all repositories in the organization. This guarantees the Sensor instrumentation runs regardless of each repository’s own workflow definitions.

Container-Based Jobs on Self-Hosted Runners

On self-hosted runners, GitHub Actions can run jobs inside a container. When using container-based jobs, the Sensor (installed on the host) must be reachable from inside the container.

Requirements for Container Jobs

For container-based jobs to work with Endura:

1. The Runtime Sensor must be installed on the self-hosted runner host (the machine running the runner and Docker daemon)
2. The Sensor socket must be mounted into the job container to enable communication between the containerized job and the host Sensor
3. The Endura CLI must be installed inside the container at the start of each job

Configure the Container Socket Mount

Mount the Sensor’s communication socket using the container options:

jobs:
  build:
    runs-on: [self-hosted, linux]
    container:
      image: node:20
      options: --volume /run/endura/sensor.sock:/run/endura/sensor.sock
    steps:
      - name: Start Endura Job
        run: |
          curl -sSf https://repo.endurasecurity.com/install/endura-sensor/testing.sh | sh
          endura job start

      # ... your existing build steps ...

      - name: Stop Endura Job
        if: always()
        run: endura job stop

The installation script installs the Endura CLI inside the container, which then communicates with the Runtime Sensor on the host via the mounted socket.

Multi-Job Workflows

GitHub Actions workflows can contain multiple jobs, including jobs linked with needs: dependencies. Each job runs in its own runner context. When instrumenting these workflows with Endura:

• Add the Endura instrumentation to each job that performs build work
• Each job operates independently from Endura’s perspective and can have its own security policy
• Create separate policies for jobs that perform different types of work (e.g., build vs. test vs. deploy)
• When deriving policies, run the full workflow so that every job is exercised

Create and Assign Security Policies

With your builds reporting to Team Server, you can now create security policies tailored to your pipeline’s behavior. Endura’s derive mode makes this process straightforward by automatically generating a policy based on observed runtime behavior.

Understand Policy Modes

Security policies operate in one of three modes:

The recommended workflow is: derive then observe then enforce.

Derive a Baseline Policy

When the Runtime Sensor runs without an assigned policy (or with a policy in derive mode), it monitors all runtime behavior and outputs a derived policy when the build completes.

Setup Instructions:

1. Run a workflow in GitHub that exercises your pipeline’s typical behavior
2. Open the completed workflow run from the Actions tab in GitHub
3. Expand the step that runs endura job stop in the job logs
4. Look for the text # ENDURA DERIVED POLICY in the logs
5. Copy the entire policy that follows this marker; this is your baseline policy derived from actual runtime behavior

The derived policy contains rules based on what your pipeline actually did during execution: processes spawned, files accessed, network connections made, and more.

Create the Policy in Team Server

With the derived policy copied, create a formal policy in Team Server.

Setup Instructions:

1. Log in to Team Server
2. Click Policies in the main navigation menu
3. Click the Create button
4. Fill in the policy details:
   • Name: Enter a descriptive name (e.g., “GitHub - my-org/my-repo Build Policy”)
   • Description: Enter a brief description (e.g., “Security policy for the my-repo CI/CD pipeline”)
   • Version: Enter 1.0
   • Policy: Paste the derived policy you copied from the GitHub workflow log
5. Review the policy and make any necessary adjustments (see the section below on refining policies)
6. Change the mode from derive to observe
7. Click Create

Assign the Policy to Your Pipeline

Link the policy to your GitHub pipeline so the Sensor enforces it during builds.

Setup Instructions:

1. In Team Server, navigate to Policies in the main navigation menu
2. Locate your policy in the policy list
3. Click the Assign Policy button (link icon) in the Actions column
4. Search for your repository by name
5. Select the pipeline by clicking its checkbox
6. Click Assign to 1 Pipeline (or the appropriate count if assigning to multiple pipelines)

Refine the Policy

Derived policies capture exact behavior, which may be overly specific. Before moving to enforce mode, review and refine the policy:

Common refinements:

• Consolidate file paths: If a process writes many files to a directory (e.g., /home/user/workspace/build/), replace individual file entries with a directory pattern using wildcards
• Remove ephemeral paths: Build artifacts in temporary directories may have unique names per build. Use patterns like /tmp/* instead of specific paths
• Group similar operations: Multiple similar rules can often be consolidated into more general patterns
• Remove redundant entries: The derived policy may include duplicate or overlapping rules

Testing in observe mode:

1. Run several workflows with the policy in observe mode
2. After each run, check for violations in Team Server:
   • Navigate to Pipelines and select your repository
   • Click Edit (pencil icon)
   • Click the Builds tab and select the latest build
   • Click Violations to see any policy violations
3. For each violation, determine whether it represents:
   • Legitimate behavior: Update the policy to allow it
   • Unexpected behavior: Investigate the cause before deciding
4. Iterate until builds complete without unexpected violations

Enable Policy Enforcement

Once your policy is refined and builds run cleanly in observe mode, enable enforcement.

Setup Instructions:

1. In Team Server, click Policies in the main navigation menu
2. Locate your GitHub policy
3. Click the Edit Policy (pencil icon) button
4. Update the policy:
   • Change Version from 1.0 to 1.1 (or your next version number)
   • Change mode from observe to enforce
5. Click Save
6. Enter a description of your change when prompted (e.g., “Enabled enforcement after observe mode testing”). Team Server maintains policy version history for audit purposes
7. Click Save to confirm

When a violation occurs in enforce mode:

• The Sensor takes immediate action (blocks the operation or terminates the offending process)
• The GitHub workflow run fails
• Violation details are reported to Team Server for review
• Notifications are sent via configured channels (e.g., Slack)

Next Steps

With GitHub pipeline security configured, consider the following:

• Configure additional pipelines: Apply the same process to other repositories and workflows
• Explore policy capabilities: See the Security Policies documentation for detailed information on policy syntax, advanced rules, and best practices
• Set up notifications: Configure Slack integration to receive real-time alerts on policy violations
• Review audit history: Use Team Server’s policy version history to track changes and maintain compliance documentation