Jenkins

This guide walks you through setting up Endura pipeline security for Jenkins. You will learn how to install the Runtime Sensor on Jenkins controller and agent hosts, configure the Jenkins integration for automatic pipeline discovery, instrument your Jenkins pipelines 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 Jenkins instance for creating API tokens and configuring pipelines.
• Root or sudo access to the Jenkins controller and agent hosts (for installing the Runtime Sensor).

Configure the Jenkins Integration

The Jenkins integration enables Team Server to discover and ingest your Jenkins jobs as pipelines. This section covers creating a Jenkins API token and configuring the integration in Team Server.

Create a Jenkins API Token

Jenkins API tokens, paired with a username, allow Team Server to authenticate with the Jenkins API to discover jobs and builds.

Setup Instructions:

1. Log in to Jenkins as the account that will own the integration token
2. Click your username in the top-right corner, then click Configure (or go to Manage Jenkins > Users > select the user > Configure)
3. In the API Token section, click Add new Token
4. Enter a descriptive name (e.g., “Endura Team Server”) and click Generate
5. Copy the token value immediately; it will not be shown again
6. Note the username associated with this account; you will need both the username and token for the integration

Add the Integration in Team Server

With the Jenkins username and API token ready, configure the integration in Team Server.

Setup Instructions:

1. Log in to Team Server
2. Click Integrations in the main navigation menu
3. Click Jenkins under the Discover sub-navigation menu
4. Click Get Started (if no Jenkins integration exists) or Create (if you already have one or more Jenkins integrations configured)
5. Configure the integration:
   • URL: Enter the base URL of your Jenkins instance (e.g., https://jenkins.example.com)
   • Username: Enter the username of the account that owns the API token
   • Token: Paste the API token you created in Jenkins
6. Click Test to verify the connection to your Jenkins instance
7. If the test succeeds, click Save to create the integration

Once the integration is created, Team Server immediately begins discovering and ingesting all Jenkins jobs 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 Jenkins jobs. To automatically discover new jobs and builds on an ongoing basis, configure the scheduled discovery jobs in your Team Server configuration.

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

scheduler:
  jobs:
    discover_jenkins_pipelines:
      run: "discover_jenkins_pipelines"
      schedule: "0 0 * * * * *"
    discover_jenkins_builds:
      run: "discover_jenkins_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 Jenkins discovery jobs alongside the required Team Server jobs:

scheduler:
  output: stdout
  jobs:
    discover_jenkins_pipelines:
      run: "discover_jenkins_pipelines"
      schedule: "0 0 * * * * *"
    discover_jenkins_builds:
      run: "discover_jenkins_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

The Runtime Sensor must be installed on the same hosts where your Jenkins builds run. The Sensor monitors build execution and enforces security policies at runtime.

Installation Overview

Install the Runtime Sensor on every host that executes build work: the Jenkins controller (if it runs builds) and all agents:

1. Identify the Jenkins controller and all agent hosts that execute the jobs 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.

Agents and Labels

Jenkins distributes build work across agents (also called nodes), and uses labels to control which agents run which jobs. When deploying the Runtime Sensor:

• Identify the agents (and their labels) that run jobs you want to monitor
• Install the Sensor on every agent host that executes those builds
• Ensure your pipelines target labeled agents that have the Sensor installed (using agent { label '...' } in your Jenkinsfile)

For dynamic or cloud-provisioned agents (e.g., Kubernetes, EC2, or Docker agents), bake Sensor installation into the agent image or provisioning configuration so new agents automatically receive the Sensor.

Configure Jenkins Pipelines

With the integration configured and the Runtime Sensor installed, you need to instrument your Jenkins pipelines to communicate with the Sensor. The recommended approach uses a declarative Jenkinsfile with a dedicated start stage and a post block that always stops the Endura job.

Instrument a Declarative Pipeline

Add a stage that starts the Endura job before your build stages and a post { always { ... } } block that stops it afterward, even if a preceding stage fails.

The following example shows a Jenkinsfile instrumented for Endura:

pipeline {
    agent { label 'endura' }   // target an agent with the Sensor installed

    environment {
        BUILD_BRANCH = "${env.BRANCH_NAME}"
    }

    stages {
        stage('Start Endura Job') {
            steps {
                sh 'endura job start'
            }
        }

        // ... your existing build stages ...
        stage('Build') {
            steps {
                sh 'make build'
            }
        }
    }

    post {
        always {
            sh 'endura job stop'
        }
    }
}

Key points:

• The agent directive must target an agent (by label) that has the Sensor installed.
• The environment block maps the branch name into BUILD_BRANCH. For multibranch pipelines, env.BRANCH_NAME holds the branch; for other jobs, use env.GIT_BRANCH.
• The Start Endura Job stage must be the first stage.
• The post { always { ... } } block runs endura job stop after the pipeline finishes, whether it succeeds or fails.

Verify the Configuration

Run a build to verify your configuration is working correctly.

Setup Instructions:

1. Trigger a build of your pipeline in Jenkins
2. Wait for the build to complete
3. Log in to Team Server
4. Click Pipelines in the main navigation menu
5. Locate your Jenkins job 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 build you just triggered

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

Standardize Pipelines with Shared Libraries

For organizations managing many pipelines, adding the Endura stages to every Jenkinsfile individually does not scale. Jenkins Shared Libraries let you define reusable pipeline logic in a central repository and apply it across all pipelines.

Define a custom step in your shared library that wraps build work with the Endura start and stop commands. Create vars/enduraJob.groovy in your library repository:

// vars/enduraJob.groovy
def call(Closure body) {
    try {
        sh 'endura job start'
        body()
    } finally {
        sh 'endura job stop'
    }
}

Pipelines then wrap their build steps with the enduraJob step:

pipeline {
    agent { label 'endura' }
    environment {
        BUILD_BRANCH = "${env.BRANCH_NAME}"
    }
    stages {
        stage('Build') {
            steps {
                enduraJob {
                    sh 'make build'
                }
            }
        }
    }
}

Setup Instructions:

1. Create a repository for your shared library containing vars/enduraJob.groovy
2. In Jenkins, navigate to Manage Jenkins > System
3. Under Global Pipeline Libraries, click Add and configure the library (name, default version, and source repository)
4. Enable Load implicitly so the library is automatically available to all pipelines without an explicit @Library annotation
5. Save the configuration

With the library loaded implicitly, every pipeline can use the enduraJob wrapper, and updates to the library propagate to all pipelines automatically.

Container-Based Builds

Jenkins can run build stages inside Docker containers using the docker agent. When using container-based builds, the Sensor configuration requires additional steps since the container does not have the Sensor pre-installed.

Requirements for Container Builds

For container-based builds to work with Endura:

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

Configure the Container Socket Mount and CLI Install

Mount the Sensor’s communication socket using the args of the docker agent, and install the Endura CLI inside the container before signaling the job start:

pipeline {
    agent {
        docker {
            image 'node:20'
            args '-v /run/endura/sensor.sock:/run/endura/sensor.sock'
        }
    }

    environment {
        BUILD_BRANCH = "${env.BRANCH_NAME}"
    }

    stages {
        stage('Start Endura Job') {
            steps {
                sh 'curl -sSf https://repo.endurasecurity.com/install/endura-sensor/testing.sh | sh'
                sh 'endura job start'
            }
        }

        // ... your existing build stages ...

    }

    post {
        always {
            sh 'endura job stop'
        }
    }
}

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

Downstream and Multibranch Pipelines

Jenkins pipelines can trigger downstream jobs, and multibranch pipelines run a separate pipeline per branch. Each pipeline runs independently. When instrumenting these with Endura:

• Instrument each pipeline (or use the shared library enduraJob wrapper) that performs build work
• Each pipeline 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 set of jobs so that each 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 → observe → 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 build in Jenkins that exercises your pipeline’s typical behavior
2. Open the completed build in Jenkins and click Console Output
3. Locate the output where endura job stop ran (the post block, or the end of the enduraJob wrapper)
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., “Jenkins - MyJob Build Policy”)
   • Description: Enter a brief description (e.g., “Security policy for the MyJob CI/CD pipeline”)
   • Version: Enter 1.0
   • Policy: Paste the derived policy you copied from the Jenkins console output
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 Jenkins 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 Jenkins job 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 builds with the policy in observe mode
2. After each build, check for violations in Team Server:
   • Navigate to Pipelines and select your Jenkins job
   • 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 Jenkins 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 Jenkins build fails
• Violation details are reported to Team Server for review
• Notifications are sent via configured channels (e.g., Slack)

Next Steps

With Jenkins pipeline security configured, consider the following:

• Configure additional pipelines: Apply the same process to other Jenkins jobs and pipelines
• 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