TeamCity

This guide walks you through setting up Endura pipeline security for JetBrains TeamCity. You will learn how to install the Runtime Sensor on TeamCity Build Agent hosts, configure the TeamCity integration for automatic pipeline discovery, instrument your TeamCity builds 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 TeamCity instance for creating access tokens and configuring build steps.
• Root or sudo access to the hosts where TeamCity Build Agents are installed (for installing the Runtime Sensor).

Configure the TeamCity Integration

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

Create a TeamCity Access Token

TeamCity access tokens allow Team Server to authenticate with the TeamCity API to discover projects and builds.

Setup Instructions:

1. Log in to your TeamCity instance
2. Click your username icon in the bottom-left corner and click Profile
3. Navigate to Access Tokens in the left sidebar
4. Click Create access token
5. Configure the token:
   • Token name: Enter a descriptive name (e.g., “Endura Team Server”)
   • Expire in: Select an appropriate expiration period based on your security requirements. For production use, consider setting a reasonable expiration (e.g., 1 year) and documenting a token rotation schedule.
   • Permissions scope: Select one of the following:
     • Same as current user: Grants the token the same permissions as your user account. This is the simplest option if your account has read access to all projects.
     • Limit per project: Restricts the token to specific projects. Use this for finer-grained access control. Team Server requires read access to query the API and discover all projects you want to monitor.
6. Click Create
7. Copy the Token value immediately—it will not be shown again

Add the Integration in Team Server

With the TeamCity 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 TeamCity under the Discover sub-navigation menu
4. Click Get Started (if no TeamCity integration exists) or Create (if you already have one or more TeamCity integrations configured)
5. Configure the integration:
   • URL: Enter the base URL of your TeamCity instance (e.g., https://teamcity.example.com)
   • Token: Paste the access token you created in TeamCity
6. Click Test to verify the connection to your TeamCity 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 TeamCity projects as pipelines. View the discovered pipelines by clicking Pipelines in the main navigation menu.

Enable Scheduled Pipeline Discovery

The initial integration setup performs a one-time discovery of TeamCity projects. To automatically discover new projects on an ongoing basis, configure the scheduled discovery job in your Team Server configuration.

Add the discover_team_city_pipelines job to the scheduler section of your Team Server configuration file (config/production.yaml):

scheduler:
  jobs:
    discover_team_city_pipelines:
      run: "discover_team_city_pipelines"
      schedule: "0 0 4 * * * *"

The schedule field uses a 7-field cron format: second minute hour day month day-of-week year. The example above runs discovery daily at 4:00 AM.

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

scheduler:
  output: stdout
  jobs:
    discover_team_city_pipelines:
      run: "discover_team_city_pipelines"
      schedule: "0 0 4 * * * *"
    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 TeamCity Build Agents run. The Sensor monitors build execution and enforces security policies at runtime.

Installation Overview

Install the Runtime Sensor on each host running a TeamCity Build Agent:

1. Identify all hosts running TeamCity Build Agents
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.

Agent Pools

TeamCity organizes Build Agents into agent pools for workload distribution and access control. When deploying the Runtime Sensor:

• Identify all agent pools that run builds you want to monitor
• Install the Sensor on every agent within those pools
• When adding new agents to a pool, include Sensor installation in your agent provisioning process

To view your agent pools and their members:

1. In TeamCity, navigate to Agents > Agent Pools
2. Click on each pool to see its assigned agents
3. Note the hostnames or IP addresses for Sensor installation

For dynamic or auto-scaling agent pools, integrate Sensor installation into your agent image or provisioning scripts to ensure new agents automatically receive the Sensor.

Configure TeamCity Builds

With the integration configured and the Runtime Sensor installed, you need to instrument your TeamCity builds to communicate with the Sensor. This involves adding environment variables and build steps that signal the start and end of each build.

Add Build Parameters

TeamCity provides several built-in variables, but some key values needed by the Endura Sensor must be explicitly mapped. Configure these parameters to capture important build metadata.

Setup Instructions:

1. Log in to TeamCity
2. Navigate to Projects
3. Select the project or build configuration where you want to add the parameters:
   • To apply parameters to all builds across all projects: Select the Root Project
   • To apply parameters to all builds within a specific project: Select the target project
   • To apply parameters to a single build configuration: Navigate to the specific build configuration
4. Click Settings
5. Click Parameters
6. Click Add new parameter for each of the following:

7. Click Save after adding each parameter

Add the Start Endura Job Build Step

The “Start Endura Job” build step notifies the Sensor that a build is beginning. This step must execute before all other build steps.

Setup Instructions:

1. Navigate to your Build Configuration
2. Click Build Steps in the left sidebar
3. Click Add build step
4. Configure the build step:
   • Runner type: Command Line
   • Step name: Start Endura Job
   • Run: Custom script
   • Custom script:

     endura job start
5. Click Save
6. Use the Reorder build steps option to ensure this step appears first in the build step sequence

Add the Stop Endura Job Build Step

The “Stop Endura Job” build step notifies the Sensor that the build has completed. This step must execute after all other build steps and should run regardless of whether preceding steps succeeded or failed.

Setup Instructions:

1. Navigate to your Build Configuration
2. Click Build Steps in the left sidebar
3. Click Add build step
4. Configure the build step:
   • Runner type: Command Line
   • Step name: Stop Endura Job
   • Run: Custom script
   • Custom script:

     endura job stop
   • Execute step: Always, even if build stop command was issued
5. Click Save
6. Use the Reorder build steps option to ensure this step appears last in the build step sequence

Verify the Configuration

Run a build to verify your configuration is working correctly.

Setup Instructions:

1. Navigate to your Build Configuration in TeamCity
2. Click Run to trigger a build
3. Wait for the build to complete
4. Log in to Team Server
5. Click Pipelines in the main navigation menu
6. Locate your TeamCity project in the pipeline list
7. Click the Edit (pencil icon) button for the pipeline
8. Click the Builds tab
9. 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.

Using Build Configuration Templates

For organizations managing many build configurations, TeamCity templates provide a scalable way to standardize build steps and parameters across multiple configurations. TeamCity allows you to configure template steps to run before or after all build configuration steps, ensuring the Endura job start and stop steps are always positioned correctly.

Setup Instructions:

1. Navigate to Projects, select your project, and click Settings
2. Click Create template under Build Configuration Templates
3. Provide a name and description for the template and click Create
4. Add the environment variable parameters as described in Add Build Parameters
5. Add the “Start Endura Job” and “Stop Endura Job” build steps as described in Add the Start Endura Job Build Step and Add the Stop Endura Job Build Step
6. Configure the build step placement:
   • Click Reorder build steps
   • In the reorder dialog, you will see a placeholder representing all build configuration steps (the steps defined in configurations that use this template)
   • Drag “Start Endura Job” above the placeholder so it runs first
   • Drag “Stop Endura Job” below the placeholder so it runs last
   • Click Save
7. Attach the template to existing build configurations:
   • Navigate to Projects and select the build configuration you want to attach
   • Click Edit Configuration (or click the build configuration name and go to Settings)
   • Click the Actions menu in the upper right corner
   • Select Attach to template
   • Choose your Endura template from the list and click Attach
   • Repeat for each build configuration you want to instrument

Builds attached to the template automatically inherit all parameters and build steps. The step placement configuration ensures “Start Endura Job” always runs before the build configuration’s own steps, and “Stop Endura Job” always runs after them.

Container-Based Build Agents

TeamCity supports running builds inside Docker containers, which provides isolated and reproducible build environments. 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 Build Agent host (the machine running the TeamCity 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

When configuring your TeamCity build to run inside a container, you must mount the Sensor’s communication socket. Add the following volume mount to your container configuration:

/var/run/endura/sensor.sock:/var/run/endura/sensor.sock

Setup Instructions:

1. Navigate to your Build Configuration
2. Click Build Features in the left sidebar (or the container settings for your runner)
3. Locate the Docker or container configuration section
4. Add the volume mount: /var/run/endura/sensor.sock:/var/run/endura/sensor.sock
5. Click Save

The exact location of this setting depends on how you configure container builds in TeamCity (Docker Wrapper, Container Wrapper build feature, or custom Docker commands).

Modify the Start Endura Job Step

For container-based builds, the “Start Endura Job” step must first install the Endura CLI inside the container before signaling the job start.

Setup Instructions:

1. Navigate to your Build Configuration
2. Click Build Steps in the left sidebar
3. Edit the Start Endura Job step (or create it if it doesn’t exist)
4. Update the Custom script to:

   curl -sSf https://repo.endurasecurity.com/install/endura-sensor/testing.sh | sh
   endura job start
5. Click Save
6. Ensure this step runs first and executes inside the container

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

Build Chains and Composite Builds

TeamCity supports build chains where multiple build configurations are linked through snapshot dependencies, and composite builds that aggregate results from multiple builds. When using these features with Endura:

Snapshot Dependencies

When Build B depends on Build A via a snapshot dependency:

• Each build in the chain operates independently from Endura’s perspective
• Each build configuration should have its own “Start Endura Job” and “Stop Endura Job” steps
• Each build can have its own security policy, or multiple builds can share a policy

Composite Builds

Composite builds aggregate multiple builds without running build steps themselves:

• Configure “Start Endura Job” and “Stop Endura Job” steps in the underlying build configurations, not in the composite build configuration
• The composite build configuration itself does not need Endura build steps since it doesn’t execute any build logic

Build Chains Best Practices

• Create separate policies for each build configuration in the chain, especially if they perform different types of work (e.g., compile vs. test vs. deploy)
• Use TeamCity templates to standardize Endura build steps across all configurations in a chain
• When deriving policies, trigger the full chain to ensure all builds are 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 TeamCity that exercises your pipeline’s typical behavior
2. Navigate to the completed build in TeamCity
3. Click Build Log to view the build output
4. Expand the Stop Endura Job step
5. Look for the text # ENDURA DERIVED POLICY in the logs
6. 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., “TeamCity - MyProject Build Policy”)
   • Description: Enter a brief description (e.g., “Security policy for the MyProject CI/CD pipeline”)
   • Version: Enter 1.0
   • Policy: Paste the derived policy you copied from the TeamCity build 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 TeamCity 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 TeamCity project 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 TeamCity project
   • 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 TeamCity 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 TeamCity build fails
• Violation details are reported to Team Server for review
• Notifications are sent via configured channels (e.g., Slack)

Next Steps

With TeamCity pipeline security configured, consider the following:

• Configure additional pipelines: Apply the same process to other TeamCity projects and build configurations
• 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

For troubleshooting common issues, see the Pipeline Security Troubleshooting Guide.