Welcome to the StepSecurity Documentation hub!

Here, you'll find all the information you need to get started with StepSecurity, implement its powerful features, and manage your security operations efficiently. Our documentation is designed to help you navigate the platform effortlessly and maximize your use of StepSecurity's tools.

What is StepSecurity?

StepSecurity is a comprehensive security platform for GitHub Actions Security, safeguarding the following layers:

• Action Runners

• GitHub Action Workflow Files

• Third party Github Actions

StepSecurity effortlessly discovers, tracks, and remediates GitHub Action workflows across many repositories.

Trusted by Leading Open-Source Projects & Enterprises

Harden-Runner, one of StepSecuity's core solutions is trusted by over 6,000 leading open-source projects and enterprises, including industry giants like Microsoft, Google, Kubernetes, and more.

Here are some case studies that show how StepSecurity detected real-life security attacks and helped organizations strengthen their CI/CD pipelines:

• Harden-Runner Detects CI/CD Supply Chain Attack in Google’s Open-Source Project Flank

• StepSecurity Detects CI/CD Supply Chain Attack in Microsoft’s Open-Source Project Azure Karpenter Provider in Real-Time

• How Coveo Strengthened GitHub Actions Security with StepSecurity

• Hashgraph Achieves Comprehensive CI/CD Security Without Compromising Development Speed

The Actions section focuses on managing and securing the GitHub Actions used in your workflows.

It includes features to evaluate the security of third-party actions, monitor their usage, and ensure they comply with your organization's security policies.

This guide will walk you through the setup process, whether you’re using the Community Tier or Enterprise Tier.

Follow the steps ahead to quickly get started and enhance the security of your CI/CD pipelines.

You can authenticate with the StepSecurity app using one of the following methods:

GitHub Authentication

Sign in using your GitHub account. This is the recommended method if you are managing GitHub repositories or organizations through StepSecurity. Simply click the “Sign in with GitHub” button on the login page and authorize access.

Email and Password with MFA

You can create a StepSecurity account using your email address and a secure password. After registering, you’ll receive a verification email to activate your account.

Multi-Factor Authentication (MFA) is enabled by default and cannot be disabled, ensuring strong account security from day one.

Single Sign-On (SSO)

If your organization has enabled SSO, you can sign in using your enterprise identity provider, follow this guide to get started.

StepSecurity integrates directly into your existing GitHub workflows to help you secure your CI/CD pipelines—without getting in your way.

As a developer, you don’t need to change how you work. StepSecurity brings visibility, automation, and guardrails into your repositories through features like Harden-Runner, StepSecurity Maintained Actions, GitHub Checks, and automated pull requests. These tools help detect anomalies, enforce policies, and suggest safer alternatives to risky actions.

On this page, you’ll learn how to:

• Review and merge security-related pull requests created by StepSecurity

• Understand and act on GitHub Checks triggered by Harden-Runner

• Interact with StepSecurity insights directly from your PRs and workflow runs

Step 1: Navigate to Secure Workflow on your browser

Step 2: Paste Your Workflow File

• Copy your GitHub Actions workflow file and paste it into the editor on the StepSecurity tool interface.

Step 3: Click on the “Secure Workflow” Button

• Click the “Secure Workflow” button.

• The tool will automatically enhance the security of your workflow by applying recommended settings:

  • Restrict permissions for [[GITHUB_TOKEN]].

  • Add Harden-Runner for the GitHub-hosted runner.

  • Pin actions to full-length commit SHAs.

Step 4: Review and Apply the Suggested Changes

• The tool will show a diff view of your original workflow versus the secure version.

• Key enhancements include:

  • Adjusted permissions to follow the principle of least privilege.

  • Integration of the StepSecurity Harden Runner with an audit egress policy.

  • Pinning all GitHub Actions to specific commit SHAs for better security

Step 5: Save and Commit the Changes

• After reviewing the updates, copy the secure workflow provided by the platform.

• Apply the updated workflow manually to your repository by pasting it into the appropriate file in your project.

As a developer, if your workflow run is cancelled and you see the message:

“The run was canceled by @stepsecurity-app[bot]”

it means the run violated a security policy configured by your StepSecurity administrator for your organization.

To understand the different scenarios where these policies may be triggered, explore the interactive demo below:

StepSecurity enables developer self-service by surfacing actionable security findings directly in their existing workflows. This eliminates the need for back-and-forth with security teams and accelerates remediation.

We offer two key features to support this:

GitHub Checks

GitHub Checks integrate security insights directly into your pull requests, making issues visible at the point of change. Developers can review findings and take appropriate action as needed.

What it does:

• Shows Harden-Runner findings in the GitHub Checks UI.

• Detects anomalous outbound network calls during CI/CD runs.

• Provides clear Pass/Fail statuses after workflows complete.

Follow this interactive walkthrough to see how it works:

Policy Driven PRs

Policy-driven automation lets StepSecurity automatically generates Pull Requests to fix security findings. Developers can then review the proposed changes and merge the PRs if they meet their standards.

Follow this interactive walkthrough to see how it works:

Adding Harden-Runner to GitHub-Hosted Runners

You can integrate Harden-Runner into your workflows in three ways:

1. Secure Workflow (Recommended for Specific Workflow Files)

Use Secure Workflow to quickly and securely add Harden-Runner to individual workflows via an interactive setup.

Follow the interactive demo for Secure Workflow:

2. Secure Repo (Recommended for Entire Repositories)

Apply Harden-Runner across all workflows in your repository with a single configuration using Secure Repo.

Follow the interactive demo for Secure Repo:

3. Policy Driven PRs (Recommended for Production)

Policy-driven automation lets StepSecurity automatically generate GitHub Issues or Pull Requests to enable runtime monitoring (Harden-Runner) across your organization.

Follow this interactive walkthrough to see how it works:

Adding Harden-Runner to Self-Hosted Runners

To configure a self-hosted runner in StepSecurity, please contact us for setup assistance.

To get started with the Enterprise Tier, install the StepSecurity App, and your 14-day free trial will begin.

After installation, open the app and go to the Get Started section to set up and secure your CI/CD pipelines

Welcome to StepSecurity Community Tier! Here’s everything you need to know to get started:

Public Repositories Only: The Community Tier works exclusively with public repositories. If you’d like to use StepSecurity with private repositories, consider upgrading to the Enterprise Tier, which includes a 14-day free trial.

How to Get Started

There are three ways to set up security using StepSecurity Community Tier:

You can restrict network connections to explicitly allowed endpoints using two approaches:

• Job-Level Restrictions

• Cluster-Level Restrictions

Job-Level Block Policy

There are two ways to enforce network restrictions at the job level:

1. Manual Workflow File Updates

2. Using Policy Store

1. Manual Workflow File Updates

This approach does not require access to the StepSecurity backend. All configurations live within the workflow file itself, allowing you to maintain your existing change management processes and developer workflows.

Follow this interactive demo to see how to restrict network connections using job level block policy:

2. Using Policy Store

Use the Policy Store if:

• You don’t want endpoint definitions cluttering your workflow files

• You want to reuse a policy across multiple workflows

This method centralizes policy management and promotes reuse, consistency, and maintainability across your organization.

Follow this interactive demo to see how to restrict network connections using policy store:

Cluster-Level Block Policy

When deploying ARC Harden-Runner, you can enforce network restrictions at the cluster level using the reserve Helm parameter.

By specifying a list of allowed endpoints:

• An egress policy is applied automatically

• The policy is enforced for all GitHub Actions runs on the cluster

• No changes are required in your workflow files

Cluster Status

The Cluster Status feature in StepSecurity provides real-time visibility into the health and security posture of your clusters. This allows you to ensure that runtime security policies are enforced across your production environments.

Self-Hosted VM Runners

For organizations using Self-Hosted Runners, StepSecurity allows monitoring of VM-based execution environments.

Harden-Runner can monitor outbound runtime detections to help you stay informed about security risks in your GitHub Actions workflows. You can review all past runtime detections on the Detections page under the Harden-Runner menu.

The Detections page covers five critical areas:

1. Secrets in Build Logs

2. Secrets in Artifacts

3. Outbound Calls Blocked

4. Anomalous Outbound Network Calls

5. Source Code Overwritten

6. HTTPS Outbound Network Calls

7. Action Uses Imposter Commit

8. Suspicious Process Events

Each detection is linked to the relevant GitHub Actions workflow and run and includes direct links to the run and the insights URL that indicates where the detection happened.

1. Secrets in Build Logs: This section shows secrets (API keys, tokens, etc.) that were accidentally logged.

1. Secrets in Artifacts: Detects secrets found in generated artifacts

1. Outbound Calls Blocked: Shows network requests that were blocked to prevent security risks.

1. Anomalous Outbound Network Calls: Lists unusual or unexpected external network requests.

1. Source Code Overwritten: Tracks files modified during workflows to detect unauthorized changes.

1. HTTPS Outbound Network Calls: Lists network requests made over HTTPS to prevent security risks.

1. Action Uses Imposter Commit: List actions that use imposter commits

1. Suspicious Process Events: Lists process events that are flagged as suspicious.

Real-Time Security Alerts

StepSecurity delivers real-time alerts for runtime detections, ensuring you stay informed about potential security threats as they happen.

To minimize alert fatigue, notifications are sent only once per event, covering all repositories in your GitHub organization. This approach maintains visibility into security events without overwhelming your team.

Follow the instructions in to configure your alerts.

When StepSecurity GitHub Check is enabled for a repository, Harden Runner monitors all outbound traffic from each job at the DNS and network layers associated with a PR. This helps ensure that CI/CD runners do not communicate with unauthorized or unexpected destinations.

• ✅ If the check passes, it means everything looks clean—no suspicious or unusual network activity was detected.

• ❌If it fails, Harden-Runner found something out of the ordinary: unexpected network calls that could point to a misconfiguration or even a compromised action

As a developer, you have control: you can either cancel a check run or approve a failed StepSecurity check if the behavior is known and expected.

Follow this interactive demo to see it in action:

The policy store holds a collection of customized policies for your workflows, allowing you to easily manage and update policies in a single location.

Steps To Create and Use a Policy

Step 1: Navigate to the Policy Store

• Open StepSecurity, then navigate to the Harden Runner section and click on Policy Store

Step 2: Click "Create policy"

Step 3: Create a New Policy

• Enter a policy name.

• Configure the policy settings (e.g., allowed endpoints, telemetry settings).

• Click Add Policy to save.

Step 4: Apply the Policy in Your Workflow

• Remove any existing manual policy configurations.

• Add the policy name under the Harden Runner step.

• Ensure id-token: write permission is explicitly set in your workflow file. This permission is required to authenticate with the StepSecurity backend API and fetch the policy.

Here’s an example:

name: CI

on:
  pull_request:

permissions:
  contents: read
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Harden Runner
      uses: step-security/harden-runner@446798f8213ac2e75931c1b0769676d927801858 # v2.10.0
      with:
        policy: Test-policy

Step 5: Verify the Integration

• Run a test workflow to ensure the policy is applied correctly.

StepSecurity maintains a set of trusted GitHub Actions to reduce risk from supply chain attacks due to compromise of third-party actions and enhance security and consistency across workflows.

As a developer, you can view the full list of . Typically, if a low-scoring action in your workflow is being replaced with a more secure, StepSecurity-maintained alternative, your StepSecurity administrator will configure automated pull requests (PRs) to be created in your repositories.

When these PRs appear, you can easily review and merge them

Follow this interactive demo to see it in action:

This guide walks you through the steps to set up and use Harden-Runner in your CI/CD workflows.

Step 1: Add Harden-Runner to Your Workflow

To integrate Harden-Runner, follow these steps:

• Open your GitHub Actions workflow file (e.g., .github/workflows/<workflow-name>.yml).

• Add the following code as the first step in each job:

steps:
  - uses: step-security/harden-runner@v2 # v2.10.3
    with:
      egress-policy: audit

Step 2: Access Security Insights

Run your workflow. Once completed:

• Review the workflow logs and the job markdown summary.

• Look for a link to security insights and recommendations.

Click on the provided link (e.g., example link) to access the Process Monitor View, which displays:

• Network events: Outbound network calls correlated with each step.

• File events: File writes tracked during the job.

This guide is designed to help Admins successfully onboard with StepSecurity and secure their organization’s GitHub Actions workflows. You’ll learn how to install the required apps, enforce security policies, enable automated remediations, manage exceptions, and request maintained GitHub Actions

Install the StepSecurity Apps

StepSecurity provides two GitHub Apps: Basic and Advanced. Both must be installed to unlock the full set of enterprise-grade features.

StepSecurity Basic App

• Required to access Enterprise Tier features.

• If already installed, you can skip this step.

After installation, open the app and go to the Get Started section to set up and secure your CI/CD pipelines.

Setup Policy-Driven Pull Requests

Enable Policy-Driven PRs to automate security remediation across your repositories. This feature allows StepSecurity to:

• Create GitHub Issues for policy violations

• Automatically open Pull Requests to fix misconfigurations

Setting Up Harden Runner

StepSecurity's Harden-Runner adds runtime protections and telemetry to your GitHub Actions workflows. There are two supported setup paths based on the type of runner you're using:

• GitHub-Hosted Runners: Add Harden-Runner to your workflow files using either the or

• Self-Hosted Runners: Admins should follow the deployment guide provided in the app to install Harden-Runner for:

  • Kubernetes-based environments using Actions Runner Controller (ARC)

  • Traditional VM- or bare-metal-based runners

Enable GitHub Checks

To minimize developer noise, GitHub Checks should be enabled only on repositories that have a stable baseline.

To enable GitHub Check for your repositories, follow the instructions provided in this

Setup Workflow Run Policies

Workflow Run Policies allow you to enforce security controls by blocking GitHub Actions workflow runs that violate organization-defined policies.

Configure Suppression Rules

If harmless outbound calls (e.g., to www.google.com) are being flagged repeatedly, you can create Suppression Rules to silence false positives and reduce developer friction.

Suppression Rules allow you to:

• Ignore specific outbound network calls from trusted domains

• Reduce alert noise while maintaining visibility into new threats

Request a New StepSecurity Maintained Action

If your organization has enabled the , any new GitHub Action must first be reviewed and approved by an Admin before developers can use it.

When a developer attempts to use an Action that is not currently maintained by StepSecurity, you can request StepSecurity to create a maintained version of that Action.

The Control Evaluation setting in StepSecurity allows you to manage which repositories are included in security evaluations.

By selecting specific repositories, you can ensure that only those will be reflected in your overview dashboard.

To enable or modify control evaluation settings:

• Navigate to the StepSecurity Dashboard.

• Open the sidebar and go to Settings > Control Evaluation.

• Specify the Actions you want to exempt from pinning control.

• Use the checkboxes to select or deselect repositories for evaluation.

• Click Save to apply your changes.

Self-hosted runners allow you to execute workflows on your own infrastructure rather than using cloud-hosted environments. This provides greater control, security, and customization options for your CI/CD pipelines.

Setting Up a Self-Hosted Runner

To configure a self-hosted runner in StepSecurity, please for setup assistance.

The Settings page allows you to configure and customize your StepSecurity environment. Here, you can manage notifications, set up self-hosted runner settings, obtain your API key, enable HTTPS monitoring, configure GitHub Checks for your organization, choose security controls for repositories, and set up templates for GitHub Issues and Alerts.

Available Settings

• Notifications

• Self-Hosted Runner

• API Key

• GitHub Checks

• Control Evaluation

Runbooks at StepSecurity provide step-by-step instructions to diagnose, respond to, and resolve specific operational issues or security incidents. They ensure consistency, reduce response time, and minimize errors by offering predefined procedures for handling common scenarios.

At StepSecurity, we believe in the power of collaboration to strengthen security across software development and deployment pipelines. Our partnerships enable us to provide enhanced security solutions, integrate seamlessly with industry-leading tools, and support developers in building more secure applications.

📢 Want to Partner with StepSecurity?

If you’re interested in working with us to enhance software security, reach out to our team at [email protected].

Step 1: Navigate to Secure Repo

Step 2: Enter Your GitHub Repository

• Click on the "Enter Your GitHub Repository" field.

• Type or paste the URL of your GitHub repository.

Step 3: Analyze the Repository

• Click the "Analyze Repository" button.

• Secure Repo will scan your repository and suggest security improvements.

Step 4: Preview the Changes

• Click "Preview Changes" to review the security enhancements.

Step 5: Review commit message

• Review the commit message generated by Secure Repo.

• Click "Preview Changes" again to proceed.

Step 6: Review Read-Only Preview

• Click on the "read-only preview" to review the proposed changes before creating a pull request

Step 7: Inspect the Code Changes

• Ensure the proposed changes align with your repository’s security need

Step 8: Create a Pull Request

1. Click "Create Pull Request".

2. Confirm the pull request details and click "Create Pull Request" again.

Step 9: Final Confirmation

• Secure Repo will generate a confirmation message.

• Click the provided link to view your pull request on GitHub.

Step 10: Merge the Pull Request

• Once you've reviewed the changes, click the "Merge Pull Request" button to apply the fixes to your repository.

Step 11: Verify Security Fixes

• After merging, confirm that the security fixes have been successfully applied by viewing the updated repository.

• You can also re-analyze the repository in StepSecurity to verify the changes.

The notification settings in StepSecurity allow you to receive alerts about critical security events via email, Slack, or Microsoft Teams. These notifications help you stay informed about potential security risks in your workflows.

Configuring Notifications

You can customize notification settings by specifying:

• Notification Channels: Enter your email address or provide a Slack/Teams webhook URL to receive alerts. Follow these instructions to create a Slack webhook and Teams webhook

• Notification Events: Select the security events for which you want to be notified, such as:

  • Outbound traffic is blocked

  • Anomalous outbound call is discovered

  • Anomalous HTTPS outbound call is discovered

  • Source code file is overwritten

  • Secrets detected in the build log

  • Secrets detected in build artifacts

• File Exclusions: If there are specific files you do not want to trigger notifications (e.g., README.md, package-lock.json), you can list them in the Exempt Files text box. Wildcards (e.g., *.md) are supported.

Saving Your Preferences

• Once you’ve configured the notification settings, click Save to apply your changes.

The Resources section of the Admin Console provides a centralized view of all connected infrastructure within your StepSecurity setup.

Here, you can view and manage GitHub Cloud Organizations and GitHub Servers that are integrated with your StepSecurity environment.

Each connected organization is listed with quick access to its dashboard, allowing you to manage and monitor security posture and automation settings at an organizational level.

As a developer, your StepSecurity administrator can configure automated pull requests (PRs) to appear in your repository. When these PRs show up, you’ll be able to review and merge them easily.

To better understand how it works, explore the interactive demo provided below:

The Audit Logs page records every action taken via the dashboard, provided it’s classified as an action. This visibility ensures accountability and is especially valuable for compliance and regulatory requirements

Baseline monitoring is the practice of establishing what normal external network calls your CI/CD workflows typically make, and then monitoring for deviations that might indicate a security breach.

At its core, it helps answer the question: “Is this job making expected and safe outbound network calls?”

Baseline Status Categories

Each monitored resource, such as a job or repository, is evaluated for the predictability of its network activity. This evaluation helps uncover anomalies that could signal security issues.

Each resource can be in one of the following baseline states:

• Creating – The system is still collecting data to determine the resource’s baseline behavior.

• Stable – The resource’s network activity is predictable and consistent. A resource is considered stable once it has completed 100 runs without baseline changes.

• Unstable – The resource’s network activity is erratic and prone to triggering frequent alerts. If the baseline has changed within the last 50 runs, the resource is classified as unstable.

Baseline Coverage at StepSecurity

StepSecurity applies baseline monitoring to four distinct resource types within your CI/CD environment:

Jobs

The Jobs tab provides detailed insights into individual workflow jobs and their external network destinations. You can:

• View each job’s Baseline Status (Stable, Unstable, Creating)

• See the Sample Size that indicates how many runs were used to calculate the baseline. A minimum of 100 runs is required

• Track Baseline Changes to know when and why the baseline last changed

• Access the underlying Workflow File, and jump directly to Workflow Runs or Log Samples for investigation

Network Insights per Job

For each destination contacted by a job, you can view:

• The domain/IP

• Port used (e.g., 443)

• Whether the destination is allowed

• First seen / Last contacted timestamps

• Total number of calls (if available)

• Links to workflow runs making those calls

Repositories

The Repositories tab aggregates baseline data across all jobs and workflows within a specific repository. It offers the same insights as the Jobs tab, but from a repository-wide perspective. This helps identify broader behavioral patterns and anomalies.

ARC Clusters

For environments that use ARC-managed self-hosted runners, the ARC Clusters view lets you monitor network behavior trends. You can see:

• Which destinations self-hosted runners are contacting

• Workflow runs that interacted with those destinations

GitHub Organization

This view aggregates baseline data across all jobs and repositories in your GitHub organization. It enables organization-wide monitoring to detect systemic threats or changes.

You can:

• View all external destinations contacted by any job across the organization

• See job counts for each destination

• Drill into specific workflow runs using the Sample Workflow Runs option

• Detect organization-wide issues, such as unexpected domain access or behavioral shifts

Assess the Security of Your GitHub Actions

Before you can improve the security of the Actions you use, you need to know how they score.

Start this interactive demo to assess the security score of your GitHub Actions:

Handling Low-Scoring Actions

If an Action has a low score, you can either:

• Replace it with a maintained alternative (if one exists), or

• Submit a request for a maintained version if none is currently available.

Start this interactive demo to see how to replace an Action with a low score:

Enforce Safer Defaults Across Your Organization

Replace Third-Party Actions with Maintained Alternatives

You can use to replace all the third party actions in your Organization with StepSecurity maintained actions

Follow this interactive walkthrough to see how it works:

Enforce Usage Policies with Workflow Run Policies

Allowed Actions Policy

Use the Allowed Actions Workflow Run Policy to define and enforce a list of approved GitHub Actions that can run in your organization.

Follow this interactive walkthrough to see how it works:

Compromised Actions Policy

Use the Compromised Actions Workflow Run Policy to prevent known compromised Actions from executing within your workflows. This ensures that if an Action is found to be vulnerable or malicious, it is blocked immediately across your organization.

Follow this interactive walkthrough to see how it works:

To access and interact with StepSecurity’s API, you need to obtain an API key.

This key allows you to securely authenticate requests and explore API endpoints using the provided Swagger documentation.

Authorizing API Access in StepSecurity

Step 1: Navigate to the API Key Section

• Open Step Security

• Go to Organization Settings in the sidebar

• Click on API Key

Step 2: Copy the API Key

Step 3: Click Authorize on the API documentation section.

Step 4: Paste Your API Key

• A pop-up window will appear.

• Paste the copied API key into the Value field.

• Click Authorize.

Step 5: Test API Endpoints

• Select an API endpoint from the documentation.

• Click Try it out.

• Fill in any required parameters.

• Click Execute to send the request.

Determining the minimum required permissions for the GITHUB_TOKEN is a key step in securing your GitHub Actions workflows.

This guide walks you through how to use StepSecurity’s tooling to analyze workflow activity and identify the least-privilege permissions your jobs need, helping you reduce risk and follow security best practices with confidence.

The Secure Workflow feature in StepSecurity helps improve the security of GitHub Actions workflows by applying industry best practices. With a single click, users can harden their workflow configurations, restrict unnecessary permissions, and enhance security without manually modifying YAML files.

Key Features

• Restrict permissions for GITHUB_TOKEN to follow the principle of least privilege.

• Add StepSecurity's Harden-Runner security agent for monitoring and controlling the GitHub-hosted runner.

• Pin all GitHub Actions to full-length commit SHAs to prevent supply chain attacks.

How to Secure Your GitHub Actions Workflow

Step 1: Access the StepSecurity Dashboard

• Visit or navigate to “Secure Workflow” under the Orchestrate Security section in your StepSecurity dashboard.

Step 2: Paste Your Workflow File

• Copy your GitHub Actions workflow file and paste it into the editor on the StepSecurity tool interface.

Step 3: Click on the “Secure Workflow” Button

• Click the “Secure Workflow” button.

• The tool will automatically enhance the security of your workflow by applying recommended settings:

  • Restrict permissions for [[GITHUB_TOKEN]].

  • Add for the GitHub-hosted runner.

  • Pin actions to full-length commit SHAs.

Step 4: Review and Apply the Suggested Changes

• The tool will show a diff view of your original workflow versus the secure version.

• Key enhancements include:

  • Adjusted permissions to follow the principle of least privilege.

  • Integration of the StepSecurity Harden Runner with an audit egress policy.

  • Pinning all GitHub Actions to specific commit SHAs for better security

Step 5: Save and Commit the Changes

• After reviewing the updates, copy the secure workflow provided by the platform.

• Apply the updated workflow manually to your repository by pasting it into the appropriate file in your project.

The Pull Requests feature provides a centralized view of all pull requests (PRs) created using Secure Repo. This feature allows users to track the status of security-related PRs, ensuring that security improvements are reviewed, merged, and applied across repositories.

Key Features

• Complete PR List: Displays all pull requests generated by Secure Repo.

• Real-Time Status: View whether a PR is open, merged, or closed.

• Direct GitHub Access: Clickable links to PRs for easy review.

• Sorting & Filtering: Organize PRs by repository or state.

• Author Attribution: See which user initiated each PR.

The Admin Console is your control center for managing organizations, members, permissions, integrations, and security settings in StepSecurity.

Sections

The Action Secrets section in StepSecurity allows you to monitor, manage, and track GitHub Actions secrets across an entire organization or within specific repositories.

This helps ensure secure storage and proper usage of sensitive information, such as API keys, tokens, and credentials used within workflows.

Key Features

To access these features, open your StepSecurity dashboard and navigate to the Action Secrets section.

Organization-Wide Secret Management

• Provides a centralized view of all secrets used across repositories.

• Tracks the last rotation date of secrets, helping enforce regular updates for security.

Repository-Level Secrets

• Displays secrets specific to individual repositories.

• Lists repositories along with the secret names and last rotation date.

When a configured policy is not followed, the associated GitHub Actions workflow run will be blocked automatically. This helps enforce organization-wide security and compliance standards.

In such a case, you will see the following message within the workflow run:

Viewing Blocked Runs in the Dashboard

To investigate blocked runs, go to the “Policy Evaluations” dashboard under Run Policies in the StepSecurity platform.

This dashboard provides:

• A list of recent policy evaluation events across your organization.

• Information about the repository, workflow file, and timestamp of each event.

• The status of the run (e.g., Blocked).

• A direct link to the workflow run for deeper inspection.

Understanding Why a Run Was Blocked

Click the arrow next to any listed evaluation to expand detailed information about:

• The specific policy or policies that were violated (e.g., Do not allow GitHub-Hosted Runners).

• The reason the run was blocked, based on the conditions defined in the policy (e.g., the job was configured to run on ubuntu-latest, which violates the organization’s policy against using GitHub-hosted runners)

This page helps you track the statuses of requested maintained actions.

Follow this interactive demo to see how to request a StepSecurity maintained action:

StepSecurity is built with the needs of modern enterprises in mind. We offer robust security, compliance, and integration features to ensure seamless adoption across large organizations.

Security & Compliance

• Compliance Certifications: StepSecurity is SOC 2 Type II and ISO/IEC 27001 compliant. These certifications demonstrate our commitment to industry-standard security and operational practices. We also conduct annual Vulnerability Assessment and Penetration Testing (VAPT) to proactively identify and address potential risks.

• Access to Reports: Compliance and VAPT reports are available upon request for enterprise customers and security teams conducting due diligence.

Single Sign-On (SSO)

We support to simplify secure user access and identity management. StepSecurity integrates seamlessly with leading identity providers, including:

This ensures centralized authentication and access controls in line with your existing organizational policies.

Seamless Workflow Integration

StepSecurity is designed to integrate into your existing security and engineering workflows without requiring teams to change how they work. Our platform supports:

• : See security status and enforcement results directly in your GitHub pull requests.

• : Get real-time alerts and policy updates where your teams already collaborate.

• : Export logs, reports, or artifacts directly to your S3 buckets for long-term storage or downstream analysis.

AWS Marketplace Availability

StepSecurity is available on , offering enterprises a streamlined way to procure and manage our solution.

By listing on AWS Marketplace, StepSecurity makes it easier for enterprises to adopt our solution through familiar procurement channels. This approach reduces contract complexity and accelerates onboarding while aligning with your internal billing systems.

This allows you to automate security remediation across your repositories by either creating GitHub Issues to track vulnerabilities or automatically generating Pull Requests to fix them.

With this setting, you can configure how StepSecurity responds when security misconfigurations or vulnerabilities are detected in your workflows or repositories.

Remediation Options

Choose how StepSecurity should remediate the vulnerabilities:

• Pull Requests: Automatically generates PRs that fix security issues (e.g., hardening actions, updating tags).

GitHub Issues: Automatically creates GitHub Issues to track and discuss detected security vulnerabilities.

Controls

These controls enable automatic detection and remediation of specific risks:

• Harden GitHub-Hosted Runner: Ensures is installed on GitHub-hosted runners to:

  • Prevent exfiltration of credentials

  • Monitor the build process

  • Detect compromised dependencies

• Pin Actions to Full-Length Commit SHA: GitHub Action tags and Docker tags are mutable, which poses a security risk. GitHub’s Security Hardening Guide recommends pinning actions to full-length commit SHAs for better security.

  • You can exempt specific actions using the Exempted Actions input (e.g., actions/checkout@v3 or actions/*).

• Restrict GitHub Token Permissions: GitHub Actions workflows have read/write permissions by default, which can pose a security risk. It is recommended to restrict permissions to the minimum required.

• Replace third party actions with StepSecurity maintained actions: Use secure, audited GitHub actions maintained by StepSecurity to reduce supply chain risks.

• Enable GitHub Advanced Security Alerts: Provides additional security alerts alongside GitHub Issues, helping to identify and address vulnerabilities more effectively.

Repository Selection

Specify which repositories should use this configuration by selecting them from the list.

You can search for repositories and apply the configuration individually by checking the corresponding box under Configuration Applied.

Manage your StepSecurity configurations as code with our Terraform provider. Automate the setup of notification settings, policy-driven pull requests, user access controls and more across your GitHub organizations.

Quick Start Guide

Navigate to the Admin Console, then click on Integrations and select Terraform Provider. There, you’ll see the setup instructions — or simply follow the steps outlined below:

Step 1: Install Terraform

• Download and install Terraform from developer.hashicorp.com/terraform/install

Step 2: Set Environment Variables

• Export the required environment variables to authenticate the Terraform provider:

export STEP_SECURITY_API_KEY=***************
export STEP_SECURITY_CUSTOMER=<ORGANIZATION NAME>

• STEP_SECURITY_API_KEY: Your StepSecurity API key

• STEP_SECURITY_CUSTOMER: Your organization name

Step 3: Create Terraform Configuration

Create a main.tf file with the following content to define the StepSecurity provider:

terraform {
  required_providers {
    stepsecurity = {
      source = "step-security/stepsecurity"
    }
  }
}

provider "stepsecurity" {
  # Configuration will be read from environment variables
  # STEP_SECURITY_API_KEY, STEP_SECURITY_CUSTOMER
}

Step 4: Add Resources

You can now define Terraform resources to manage your StepSecurity configurations. Here’s an example of creating a GitHub user with organizational access:

# Create a GitHub user with organization access
resource "stepsecurity_user" "example_user" {
  user_name = "github-username"
  auth_type = "Github"
  policies = [
    {
      type         = "github"
      role         = "auditor"
      scope        = "organization"
      organization = "your-org-name"
    }
  ]
}

This configuration grants the specified GitHub user read-only access to the organization’s StepSecurity-managed GitHub workflows and policies.

Step 5: Run Terraform Commands

Use the following commands to deploy your configuration:

terraform init    # Initialize the working directory
terraform plan    # Preview the changes
terraform apply   # Apply the configuration

Further Reading

• Terraform Registry Documentation →

  Explore the complete resource reference, available data sources, configuration options, and provider versions.

• GitHub Examples Repository →

  Browse real-world examples, reusable templates, and best practices to accelerate your setup.

StepSecurity's Webhook Integration enables you to receive real-time notifications about security events detected in your organization

This allows teams to respond quickly, integrate with incident response workflows, and enhance observability across CI/CD pipelines.

Prerequisites

Before setting up the Webhook integration:

• You must be an Admin in your StepSecurity organization.

• You should have a webhook endpoint ready to receive POST requests.

• The endpoint must support HTTPS and accept JSON payloads.

Setup

Step 1: Navigate to your StepSecurity dashboard

Step 2: Click "Admin console"

Step 3: Click "Integrations"

Step 4: Click "Enable Webhook Integration

Step 5: Configure Webhook Integration

• Enter your Webhook URL in the corresponding input field.

• Select the HTTP Method (e.g., POST or GET) from the dropdown.

• Add headers such as Authorization, Content-Type, etc.

  • For example, set Content-Type to application/json.

  • Click “+ Add Header” to add multiple headers if needed.

• Choose your message format from the dropdown:

  • Raw – sends raw event data

  • Envelope – wraps the event data in an envelope structure

• Select the kind of content to send:

  • Toggle on Send Insights and/or Send Detections as required.

• Click “Test Connection” to validate the webhook setup.

Step 6: Select the Repos you want to send webhook events for

Step 7: Click “Save changes” to apply your configuration

Reusable workflows in GitHub Actions let you create shared workflows that can be used across multiple repositories. This reduces duplication, keeps workflows consistent, and makes maintenance easier.

Instead of copying workflow files, you can reference a reusable workflow from another repository or within the same repository.

Navigating Reusable Workflows

Accessing Reusable Workflows

• Navigate to the Actions section and select Reusable Workflows.

• You will see a list of all reusable workflows in your organization, including:

  • The repositories they belong to.

  • The repositories that are using them.

  • The Control Score for each workflow.

Viewing Repositories Using a Reusable Workflow

• Click on the number under the Repositories Using Reusable Workflow column.

• This will take you to a page that displays:

  • The repository using the workflow

  • The workflow file name

  • The commit SHA

  • The associated tag

Viewing the Control Score

• Click on the Control Score to see the detailed breakdown of the workflow’s score for each security control

• This will display a list of compliance checks and highlight areas where the workflow fails.

• You can review each failed control use secure workflow or secure repo to improve workflow compliance

This document outlines the steps required to set up Microsoft Entra (formerly Azure AD) SSO integration with StepSecurity.

Setup Instructions

Step 1: Create a New Enterprise Application

• Navigate to your Microsoft Entra Admin Portal.

• Create a new Enterprise Application.

• Name the application StepSecurity.

Step 2: Configure Single Sign-On

• After creating the application, go to the Single Sign-On section.

• Select SAML as the SSO method.

Step 3: Provide SAML Configuration

• In the SAML Basic Configuration, enter the following values:

• Leave all other properties with their default values unless specified otherwise.

Step 4: Download and Share Metadata

• After completing the configuration, download the Federation Metadata XML file.

• Share the metadata file with StepSecurity securely.

Using Suppression Rules

You can use suppression rules to prevent alerts for specific endpoints.

Follow this interactive demo to get started:

This feature integrates Harden-Runner insights into the GitHub Checks UI, providing developers with immediate feedback on outbound network activity.

With this integration, developers no longer need to rely on email or Slack notifications or visit the StepSecurity dashboard to monitor anomalous network calls.

How It Works

1. Pull Request Creation:

When a pull request is created, the StepSecurity Harden Runner Check will display the network monitoring status for all associated workflow runs.

1. Completion of Workflow Runs:

Once all workflow runs linked to the pull request are completed, the status check will indicate either Pass or Fail:

✅ Pass: No anomalous outbound calls detected.

❌ Fail: At least one anomalous outbound call detected.

1. Clicking the Details link next to the check provides:

• A list of monitored workflow runs.

• Links to insights pages for each run.

• If the check has failed, a list of anomalous outbound calls detected.

Approving a Failed StepSecurity GitHub Check

This guide explains how to approve a failed StepSecurity GitHub check when an alert is triggered due to unexpected network calls from CI/CD runners.

Step 1: Navigate to the Pull Request

• Open the Pull Request (PR) that contains the failed StepSecurity check.

Step 2: Click on the Failed Check

• Locate the StepSecurity Harden-Runner check under the failed checks section.

• Click on the failed check to view more details.

Step 3: Review the Failure Details and Approve

• The check failure page will display details about unexpected network calls detected from the Harden-Runner.

• Identify the endpoint and the workflow that triggered the alert.

• If you want to approve the check run, click the approval link provided in the failure details.

Step 4: Approve the Check Run

• On the approval page, review the detected outbound network calls.

• Click “Approve” to confirm that you are aware of the anomalous call.

Step 5: Verify Approval Status

• Return to the check run status tab in GitHub.

• You will now see that the check has been approved by your GitHub username.

Step 6: Confirm the StepSecurity Check Passed

• After approval, the StepSecurity check should now be successful.

• The PR is now ready for merging.

View past GitHub Checks

This guide walks you through how to view past GitHub Actions workflow checks using StepSecurity Harden-Runner

Step 1: Navigate to the GitHub Checks Section

• Open StepSecurity and go to the Harden Runner section.

• Click on GitHub Checks to view a list of all past workflow runs in your organization.

Step 2: View a Specific Check

• Locate the workflow check you want to inspect.

• Click View Check next to it.

Step 3: Review Check Details

• On the Check details page, look for any security alerts or anomalous network activity.

• If necessary, approve the Check or take additional security actions.

Step 4: Apply Filters to Find Specific Checks

You can refine the list of checks by applying filters:

1. Filter by Conclusion (Success or Failure)

• Click the Conclusion dropdown.

• Select:

  • Success to view successful runs.

  • Failure to see failed checks.

  • All to view everything.

1. Filter by Repository

• Click the Select Repository dropdown.

• Choose a specific repository to view only its checks.

1. Filter by Status

• Click the Status dropdown

• Select:

  • Approved to view approved checks

  • Pending to view pending checks

  • All to view everything

StepSecurity maintains a set of trusted GitHub Actions to reduce risk from supply chain attacks due to compromise of third-party actions and enhance security and consistency across workflows.

We onboard StepSecurity Maintained Actions based on requests from our enterprise customers who typically ask us to onboard actions that:

• Have been abandoned by original maintainers

• Have single maintainers

• Receive low security scores (based on )

• Present high security risks due to credential access requirements

Our Secure Maintenance Process

1. Rigorous Onboarding: Every action undergoes a thorough manual secure code review before being onboarded as a StepSecurity Maintained Action

2. Strict Access Control: All action repositories are created in the StepSecurity organization with write access strictly limited to our engineering team

3. Robust Branch Protection:

   • Requires cryptographically signed commits

   • Mandates approval from a reviewer other than the PR creator

   • Enforces security tool status checks before merging, such as:

     • CodeQL

     • Dependency Review

     • OpenSSF Scorecard

     • GuardDog

4. Tag Protection: By default, no tags can be created or changed. We use just-in-time access to create tags during the release process

5. Secure Release Process:

   • For Node actions: The dist folder is built from scratch and validated within a GitHub Actions workflow

   • For Docker actions: New images are built and pushed to StepSecurity's GitHub container registry

6. Release Safeguards:

   • Uses environment-based approvals to require explicit verification before release

   • Utilizes ephemeral GitHub Actions tokens instead of persistent bot accounts

7. Industry Best Practices:

   • Follows Open Source Security Foundation Scorecard recommendations

   • Pins dependencies in GitHub Actions workflows to specific versions

   • Implements minimal GITHUB_TOKEN permissions

   • Utilizes CodeQL and Dependabot

8. Proactive Vulnerability Management: Continuously monitors for security vulnerabilities in dependencies with a defined SLA for patches

   • High-risk vulnerabilities (CVSS 7.0 and higher): 30 days

   • Moderate-risk vulnerabilities (CVSS 4.0 to 6.9): 90 days

   • Low-risk vulnerabilities (CVSS under 4.0): 180 days

9. Upstream Coordination: Monitors for upstream changes and incorporates them using the same rigorous review and release process

10. Comprehensive Testing:

    • Implements integration tests for all actions

    • Tests run automatically before updating dependencies or merging from upstream

    • Ensures reliability and consistent behavior across updates

11. Runtime Security Monitoring:

    • Runs actions with StepSecurity Harden Runner to observe and analyze network traffic

    • Monitors runtime behavior for anomalies or unexpected activities

Real-World Security Benefits

Case Study Comparisons:

• tj-actions/changed-files: A compromise occurred when a with repository access was exploited to update tags. StepSecurity actions eliminate this risk by avoiding persistent credentials and requiring environment-based approvals for releases.

• reviewdog actions: Security was compromised due to where contributors who submitted to reviewdog/action-* repositories were automatically invited to the reviewdog/actions-maintainer team, which had write access to these repositories. StepSecurity restricts access exclusively to our dedicated maintenance team.

This page helps you assess the security score of any GitHub Action used in your workflows.

How to Check an Actions Security Score

• Navigate to the Actions section and select GitHub Actions Advisor

• Enter the name of an action (e.g., google-github-actions/auth) to view its security score.

• You can also browse a list of Actions maintained by StepSecurity

• This will open the GitHub Actions Advisor, which provides a breakdown of the GitHub Actions security score

• The following details are displayed for each Action:

• Scroll down in the GitHub Actions Advisor to see all outbound network calls made by the action.

The Orchestrate Security section in StepSecurity allows you to analyze your GitHub Actions workflows against security best practices and automatically fix security gaps through automation

You can use Secure Workflow to fix security issues in a single workflow and Secure Repo to apply fixes across all workflows in a repository.

Once these fixes are applied and merged, they will enforce the following security enhancements:

• Restrict Permissions for GITHUB_TOKEN

• Add stepsecurity/harden-runner

• Pin Actions to a Full-length Commit SHA

• Pin Image Tags to Digests in Dockerfiles

• Update Dependabot Configuration

• Add CodeQL Workflow (SAST Tool)

• Add Dependency Review Workflow

• Add OpenSSF Scorecard Workflow

• Update Pre-commit Configuration

Restrict Permissions for GITHUB_TOKEN

The GITHUB_TOKEN is an automatically generated secret that grants authenticated access to the GitHub API.

To minimize security risks, StepSecurity enforces the principle of least privilege, restricting token access to only the necessary scopes. This reduces the risk of privilege escalation and unauthorized access.

Add stepsecurity/harden-runner

The Harden-Runner GitHub Action installs a security agent on the Github-hosted runner to prevent exfiltration of credentials, monitor the build process, and detect compromised dependencies.

This ensures that workflows are protected against supply chain attacks and unauthorized data leaks.

Pin Actions to a Full-length Commit SHA

Pinning GitHub Actions to a full-length commit SHA ensures that workflows remain immutable and protected from upstream modifications.

This prevents the risk of a compromised action repository introducing security vulnerabilities. Users should verify that the SHA comes from the official action repository rather than a fork.

StepSecurity also supports pinning to immutable Actions, adding an extra layer of protection to your workflows.

Pin Image Tags to Digests in Dockerfiles

To prevent unauthorized updates and potential supply chain attacks, container images referenced in workflows are locked to a specific commit SHA.

This ensures that images remain consistent and are not silently updated with unverified changes.

Update Dependabot Configuration

StepSecurity automates the discovery of languages and technologies (e.g., Golang, GitHub Actions, etc.) used in repositories, enabling Dependabot to proactively upgrade dependencies with the latest security patches and improvements.

This automation helps reduce the risk of vulnerabilities caused by outdated third-party libraries.

Add CodeQL Workflow (SAST Tool)

Static Application Security Testing (SAST) scans source code during development to detect security vulnerabilities early in the software development lifecycle.

By proactively identifying potential weaknesses, you can remediate issues before deployment.

Add Dependency Review Workflow

The Dependency Review Workflow scans package version changes in pull requests to detect vulnerabilities introduced by new dependencies.

This provides visibility into potential security risks before merging a PR, helping you maintain a secure software supply chain.

Add OpenSSF Scorecard Workflow

OpenSSF Scorecard evaluates repository security based on multiple heuristics and assigns a security score from 0 to 10.

This helps users understand areas for improvement and strengthen their security posture. Additionally, repositories can display a Scorecard badge to showcase security best practices.

Update Pre-commit Configuration

Pre-commit hooks enforce security by scanning code before it is committed.

This helps detect hardcoded secrets, enforce code quality, and prevent security vulnerabilities at an early stage

The Members section in the StepSecurity Admin Console helps you manage user access and roles within your organization.

From this view, you can:

• Invite new users via the "Invite Members" button

• Search and filter the member list

• View each user's name, join date, and associated organization

• Use the actions menu (⋮) to manage individual member settings

This centralized list provides a clear overview of who has access, making it easy to maintain secure and organized team membership.

How to Invite Members to an Organization

Step 1: Click "Invite Members"

• Navigate to the Members section of your Admin Console and click the "Invite Members" button in the top-right corner.

Step 2: Select Authentication Type

• Choose the authentication method for the new member:

  • GitHub

  • SSO

  • SSO Group

  • Email Suffix

• Enter the required information based on the selected authentication method.

• Click Continue

Step 3: Select Access Type

• Choose the type of access to grant the invited member:

  • Account: Full access to the account.

  • Organization: Access to specific organizations only.

• Then click Continue.

Step 4: Assign a Role

• Select the role you want to assign (e.g., admin or auditor).

• Click Invite to finalize.

• Once invited, the new member will be added to your organization.

Enterprise users can export Harden-Runner security data to their own Amazon S3 bucket using the S3 Integration feature. This allows you to ingest StepSecurity insights and detections into your existing SIEM or log aggregation systems. It also provides the flexibility to build custom integrations and analytics on top of Harden-Runner data.

Prerequisites

Before setting up the S3 Integration, ensure you have the following prerequisites in place:

• Dedicated S3 Bucket: Create or designate an Amazon S3 bucket in your AWS account to receive the exported data.

• IAM Role for StepSecurity: An AWS IAM Role that the StepSecurity platform can assume to write objects to your S3 bucket. You will configure a trust policy on this role to allow StepSecurity’s AWS account to assume it (using an External ID for security).

Enabling the S3 Integration

Follow the steps below to configure the S3 Integration via the StepSecurity Admin Console:

Step 1: Open Integrations in Admin Console

• Log in to the StepSecurity Admin Console for your organization.

• Navigate to the Integrations section

• On this page, you will see an External ID value displayed – copy this value as it will be needed when creating the AWS IAM role.

Step 2: Deploy the CloudFormation Stack:

• Instead of manually creating the AWS resources, you can use the CloudFormation template shared here to set them up quickly. Feel free to update the CloudFormation template as required before deploying it.

• In the CloudFormation console, provide the required input parameters:

  • S3 Bucket Name: The name of the S3 bucket that will store StepSecurity data (this should be the dedicated bucket you prepared).

  • IAM Role Name: A name for the new IAM role to create (for example, “StepSecurityS3IntegrationRole”). This role will be assumed by StepSecurity to write to your bucket.

  • External ID: Paste the External ID value copied from the StepSecurity integration settings page.

• The CloudFormation template will provision the S3 bucket, a custom IAM managed policy granting necessary on that bucket, and an IAM role with a trust policy that allows StepSecurity’s AWS account to assume the role only when the correct External ID is provided. Once the stack deployment is complete, note the Role ARN output and ensure the S3 bucket has been created.

Step 3: Configure Integration Settings

• Return to the StepSecurity S3 Integration settings page in the Admin Console.

• Enter the Bucket Name of the S3 bucket and the Role ARN of the IAM role that you just created via CloudFormation. These fields tell StepSecurity where to send the data and which role to assume.

Step 4: Select Data Types to Export

• Choose which types of Harden-Runner data you want to export to S3

• You can enable Insights and/or Detections

• Each of these can be toggled on or off independently. For each enabled data type, you must specify a custom S3 object key prefix format for the data files:

• For example, you might use a prefix format like insights/{{.Year}}/{{.Month}}/{{.Day}}/ for Insights. In this case, Harden-Runner insight files will be organized into year/month/day folders within your bucket (e.g., insights/2025/04/09/…). Similarly, you could set detections/{{.Year}}/{{.Month}}/ for Detections. This templating allows you to partition and organize the logs by date, or other variables, to suit your retention and querying needs.

• After providing path values, click on the "Test Connection" button to verify that the StepSecurity platform can create objects inside the provided S3 bucket—a temp folder with a temp.json will be created

Step 4: Select Organization / Repositories Scope

• Decide whether the S3 integration should apply to all repositories in your organization or only specific repositories. You can choose the scope in the integration settings UI:

  • All repositories: The Harden-Runner data from every repository in your GitHub organization (that is monitored by StepSecurity) will be exported to S3.

  • Selected repositories: You can pick one or more repositories for which to enable the export. Only those repositories’ data will be sent to S3. This option is useful if you want to pilot the integration on a subset of projects or limit data export to certain critical repositories.

Step 5: Save and Enable

• After filling in the Bucket Name and Role ARN, selecting the data types, and choosing the repository scope, click the Save button

• The S3 integration will be activated. StepSecurity will now begin exporting the chosen Harden-Runner data to your S3 bucket. The data will continuously be delivered in near real-time as new workflow runs occur, allowing you to ingest it into your SIEM or other tools.

Verification and Next Steps

Once enabled, it’s a good practice to verify that everything is working:

• Check AWS S3: In your AWS S3 console, navigate to the configured bucket. After some GitHub Actions runs have completed, you should see objects appearing under the specified prefixes (e.g., an insights/ folder or detections/ folder with timestamped files). This confirms that StepSecurity can assume the role and write to your bucket.

• SIEM / Log Ingestion: Now that the data is flowing into S3, you can integrate it with your log management or SIEM platform. Many SIEM tools (like Splunk, Elastic, Datadog, etc.) can ingest logs directly from S3 buckets. Configure your SIEM to pull the objects from the bucket (using the folder structure you defined) to start analyzing Harden-Runner insights and detections alongside your other security data.

• Custom Processing: Alternatively, you can build custom processing on this data. For example, you might use AWS Lambda functions triggered by new S3 objects to automate responses to certain detections, or use AWS Athena/Glue to query the insights data with SQL for ad-hoc analysis.

By setting up the S3 Integration, you gain greater flexibility in how you store, analyze, and respond to CI/CD security information from StepSecurity. This integration ensures that Harden-Runner’s rich telemetry can be seamlessly incorporated into your organization’s broader security operations and monitoring workflows.

Workflow Run Policies allow you to enforce security controls by blocking GitHub Actions workflow runs that violate organization-defined policies. This is particularly useful for preventing misconfigurations and supply chain attacks in your CI/CD pipelines.

How It Works

When a workflow run violates a policy, the run is automatically blocked. You can define policies such as:

• Automatically block compromised GitHub Actions, preventing them from executing in your workflows

• Whether secrets can be used on non-default branches

• Which GitHub Actions are permitted, including internal/private actions

• Which runner labels are allowed or disallowed

Below are the supported policy types and example runs where the policy enforcement blocked workflow execution:

When a workflow run is blocked, you will see this message in the workflow run:

The run was canceled by @stepsecurity-app[bot].

Compliant workflow runs continue without any impact—everything runs as expected.

Use this interactive demo to learn how to set up an Actions policy in your organization:

Scenario

You received a detection alert for an anomalous outbound network call either via or a failed .

This runbook will help you identify what code or process caused the outbound call.

Getting Started: Locate the Job and Endpoint

• Open the summary page for the detection.

• You can find the details in the "All Detections" section of the Summary page. This section shows:

  • The job in which the anomalous outbound call occurred.

  • The anomalous endpoint (domain or IP address) flagged by StepSecurity.

• Click on "View Job Details"

• This will take you to the Network Events tab, where you can review all the outbound network calls made by that specific job. Use the “Show findings only” toggle to quickly filter and display just the detections, or use the search bar to look up specific events

Step 1: Review Build Logs with Timestamps

• Each outbound call has an associated timestamp.

• Open the build log for the affected run

• Enable timestamps in the UI

• Scroll to the time around the outbound call and observe what was happening in the workflow at that point

Step 2: Search for the Domain or IP in Logs

• Check if the domain name or IP address from the alert appears in the build log.

• Sometimes, build tools or scripts log outbound destinations directly—this can give a direct clue about what triggered the call.

Step 3: Review Outbound API Call Details

• If available, StepSecurity also shows outbound API call details, including the HTTP method (e.g., GET, POST) and the path.

• This provides additional context about what operation was attempted (e.g., a POST /upload vs. a GET /version).

• Compare this against the code or build step at that time to see if it matches expected behavior.

Step 4: Inspect the Process Tree in Insights

• Go to the Network Events page in StepSecurity.

• Click on the PID of the process that made the outbound call.

• Review the Process Events panel to see the exact command executed and click "View Parent Process (PPID)" to trace back to the parent process

• Inspect the parent process (e.g., /usr/bin/bash) to see which script or tool launched the outbound call

Step 5: Investigate Code, Commits, and GitHub Actions

• Check the commit associated with the build to see if the domain or IP is directly referenced in the changes.

• If the outbound call correlates to a workflow step that runs a GitHub Action, identify which action it was.

  • If it’s a third-party action, inspect the action’s code in its repository to confirm whether the outbound call is expected or suspicious.

  • If it’s your own action, check recent changes or dependencies that might have introduced the behavior.

• If not found in the commit or the correlated action:

  • Search within the repository codebase.

  • Expand the search to your organization’s repositories.

  • As a last step, check if the domain is mentioned in public repositories (to detect potential supply chain or dependency issues).

Outcome

By following these steps, you should be able to trace the anomalous outbound network call back to:

• A specific job and workflow step (or GitHub Action),

• A process or script executed during the build,

• Or a piece of code (commit, repo, dependency) that introduced the outbound behavior.

To get insights into the GitHub Actions used in your repositories, navigate to the Actions section in the StepSecurity dashboard. Here, you can find:

• The name of each Action.

• The Action Security Score.

• The Repositories using that particular Action.

Exploring GitHub Actions Insights

Viewing Action Details

• Click on a specific action, such as actions/checkout.

• This will open the GitHub Actions Advisor, which provides a breakdown of the GitHub Actions security score.

• Scroll down in the GitHub Actions Advisor to see all outbound network calls made by the action.

Checking Repository Usage

• The dashboard also allows you to view the number of repositories using each action.

• Click on the repository count to access a detailed list of:

  • The repositories using the action.

  • The associated workflows.

  • The SHA and tag for each repository.

  • The age of the last used tag/SHA(If the tag hasn’t been updated in a while, it is recommended to upgrade it. You can automate this process using Dependabot)

• You can also explore reusable workflows and see where they are being used. Hover over a workflow to find out which other workflows depend on it.

Managing Low-Scoring Actions

• Actions with low security scores should be replaced or updated.

• StepSecurity provides maintained alternatives for some actions.

• If an action has a maintained version, you will see a Maintained action available label.

• Clicking on the Maintained action available label will take you to the StepSecurity-maintained action, where you can see the difference between the StepSecurity-maintained action and the low-scoring action.

Requesting a Maintained Action

• Click on an action with a low score.

• If it does not have a maintained version, you can request one.

• Click on Request maintained action .

• Enter your email and submit the request.

Suppression rules allow you to ignore specific outbound network calls from known domains that are not a security concern.

For example, if your organization regularly makes outbound calls to www.google.com, but these calls are being flagged as anomalous, you can create a suppression rule to prevent unnecessary alerts for this domain.

Scope of Suppression Rules

You can create suppression rules at different levels, depending on how broadly you want to apply them:

• Job Level – Applies to a specific job.

• Workflow Level – Applies to all jobs within a workflow.

• Repository Level – Applies to an entire repository.

• Organization Level – Applies across all repositories within the organization.

How to Create a Suppression Rule

There are two ways to create a suppression rule, from the:

• Suppression Rules page

• All Detections page

Method 1: From the Suppression Rules Page

Step 1: Navigate to Suppression Rules under the Harden Runner Section

Step 2: Click "Create rule"

Step 3: Enter the following details:

• Rule Name – Provide a meaningful name for the rule.

• Rule Type – Select the type of rule

• Description – Add details about why this rule is being created.

• Destination – Specify the domain or IP Address to suppress (use * for wildcard matching).

• Process – Specify the exact process name

• Scope – Choose the level of the rule: Job, Workflow, Repository, or Organization.

Step 4: Click "Save"

Your Suppression Rule is now created and active

Method 2: Creating a Suppression Rule from the All Detections Page

Step 1: Navigate to Detections and go to the Anomalous Outbound Network Calls Tab

Step 2: Click on the three dots next to the detection you want to suppress and select "Suppress detection"

Step 3: You will be redirected to the Suppression Rules page with the detection details pre-filled, add the name and description.

Step 4: Click "Save"

Your Suppression Rule is now in effect

This document outlines the steps required to set up Okta SSO with StepSecurity.

StepSecurity uses AWS Cognito as the service provider for the SSO experience. Please note that StepSecurity-based SSO allows login only when initiated by the service provider.

Setup Instructions

Step 1: Log in to Okta

• Log in to the Okta Admin Console

• Navigate to Applications > Applications from the left sidebar.

Step 2: Create App Integration

• Click on Create App Integration on the Applications page.

Step 3: Choose SAML 2.0

• Select SAML 2.0 as the Sign-in method, then click Next.

Step 4: Configure General Settings

• On the General Settings page:

  • Enter the App name as StepSecurity.

  • Optionally, add the StepSecurity logo:

    StepSecurity Logo Link

• Click Next to continue.

Step 5: Configure SAML Settings

• Provide the following values:

  • Single sign-on URL:

    https://login.app.stepsecurity.io/saml2/idpresponse

  • SP Entity ID:

    urn:amazon:cognito:sp:us-west-2_PGbAJDNzx

• (Optional) For Idp initiated login we can add the Default RelayState:

identity_provider=<IDP_NAME_IN_COGNITO>&client_id=<COGNITO_CLIENT_ID>&redirect_uri=https%3A%2F%2F.stepsecurity.io%2Fauth%2Fcognito%2Fcallback&response_type=code&scope=email+openid+phone+profile

Step 6: Add Attribute Statement

• Under Attribute Statements, add the following field:

  • email → user.email

Step 7: Add Group Attribute Statements

• Scroll down to ‘Group Attribute Statements’ and add following field.

  • Name as ‘Groups’ and use Filter as ‘Matches regex’ with value as ‘.*’

Step 8: Save Settings

• Scroll down keeping the default values, then click Next.

Step 9: Provide Feedback

• Optionally, provide feedback. Then click Finish.

Step 10: Share Metadata URL

• After finishing, you will see a screen displaying the Metadata URL.

• Copy the Metadata URL and share it securely with the StepSecurity team.

Step 11: Assign Users

• Under the Assignments tab, add users who should have access to this application.

Step 12: Confirm SSO Setup

Once StepSecurity confirms the SSO setup is complete:

• Users can go to the StepSecurity login page.

• Enter their email address under the Sign in with your corporate ID section.

• They will then be redirected to authenticate via Okta SSO.

Step 13 (Optional): Access StepSecurity Console via Okta App

• Contact us to get your RelayState value

• In the Okta Admin Console, go to:

  StepSecurity app → Sign On → Settings → Edit

  and paste the provided value into the Default Relay State field under the SAML 2.0 section.

This document outlines the steps required to set up Google SSO with StepSecurity.

StepSecurity uses AWS Cognito as the service provider for the SSO experience.

Setup Instructions

Step 1: Access Google Admin Console

• Log in to your Google Workspace as an Administrator.

• From the left sidebar, navigate to:

  Apps → Web and mobile apps

Step 2: Add a New Custom SAML App

• Click Add App ➔ Add custom SAML app.

Step 3: Configure App Details

• Name the app: StepSecurity

• (Optional) Add a description and upload the StepSecurity logo: StepSecurity Logo

Step 4: Download Google SAML Metadata

• Download the metadata file provided during this step.

• Securely share the metadata file with StepSecurity.

Step 5: Enter Service Provider Details

On the "Service Provider Details" page:

• ACS URL: https://login.app.stepsecurity.io/saml2/idpresponse

• Entity ID: urn:amazon:cognito:sp:us-west-2_PGbAJDNzx

• [Optional] For Idp Initiated login, we can enter Start URL as following:

RelayState=identity_provider%3D{{IDP_NAME_IN_COGNITO}}%26client_id%3Dq1v7a8skmmdmr9a3kv29013g5%26redirect_uri%3Dhttps%253A%252F%252F{{DOMAIN}}.stepsecurity.io%252Fauth%252Fcognito%252Fcallback%26response_type%3Dcode%26scope%3Demail%2Bopenid%2Bphone%2Bprofile

Step 6: Map Identity Attributes

• In the "Attribute Mapping" section:

  • Map Primary Email ➔ email.

• Under Group membership add your user groups that will be assigned to this app and map it to 'Groups' attribute

• After completing the mapping, click Finish to complete app creation.

Step 7: Enable the SAML App

• In the created SAML app page:

  • First set the app to OFF for everyone.

  • Then switch it ON for everyone.

  • Click Save to apply changes.

Step 8: Verification and Finalization

• StepSecurity will notify you once SSO is successfully set up.

• After setup:

  • Users can log in by entering their email under the "Sign in with your corporate ID" section on the StepSecurity login page.

Step 9 (Optional): Access StepSecurity console directly from Google App:

• Contact us to get your Start URL.

• In Google Admin:

  • Go to Apps → Web and mobile apps → StepSecurity app → Service provider details,

    then enter the URL under Start URL.

After you install the in your GitHub Account and access your dashboard, you should see the Overview dashboard.

On this page, you can see all the controls enabled by StepSecurity:

All Controls

StepSecurity provides these controls as specific checks on your GitHub organization workflows, ensuring compliance with industry-standard security practices.

Network and runtime security monitoring should be enabled for GitHub-hosted runners

This check ensures that the GitHub Action is included in your workflow for GitHub-hosted runners to prevent unauthorized access, exfiltration, and tampering.

Why This Matters

Without security monitoring, attackers can exploit CI/CD workflows to leak sensitive code or credentials. harden-runnerhelps detect and prevent these threats by monitoring network activity and restricting unexpected behaviors.

How to Fix It

Fix this issue with an automated pull request that adds the step-security/harden-runner GitHub Action to the job using or

Network and runtime security should be enabled for self-hosted runners

This check ensures that the necessary monitoring measures are in place to protect self-hosted runners against unauthorized access and tampering

Why This Matters

Without security monitoring, attackers can exploit self-hosted runners to exfiltrate code or steal CI/CD credentials. Harden-Runner helps mitigate these risks by monitoring network activity and detecting suspicious file modifications.

How to Fix It

• Deploy Harden-Runner on self-hosted runners by following the instructions in the

Prevent execution of untrusted code from context variables (Script Injection Vulnerability)

This check ensures context variables in workflows are not used in a way that allows untrusted input to be executed as code, preventing script injection vulnerabilities.

Why This Matters

If workflow context variables (e.g., ${{ github.event.issue.title }}) are not properly handled, attackers can inject malicious scripts into workflows. This can lead to arbitrary command execution, data exfiltration, or unauthorized access to repository secrets.

How to Fix It

Avoid inline scripts

Wherever possible, use tried and tested GitHub Actions instead of inline scripts. Please note that a GitHub Action itself can be vulnerable to script injection attacks, so you must review the Action before using it.

Intermediate Environment Variable

If you must use inline scripts, consider using intermediate environment variables to access user controller attributes. Here is an example:

Prevent execution of untrusted code from forks (Pwn Request Vulnerability)

This check ensures that workflows triggered by potentially unsafe events, such as pull_request_target, do not execute untrusted code from forked repositories without proper safeguards.

Why This Matters

Using risky triggers like pull_request_target without explicitly defining a reference (ref) when checking out code can expose secrets and lead to repository compromises. Attackers can manipulate pull requests to run unauthorized code with elevated permissions.

How to Fix It

If this check fails, take one of the following actions:

• Use a safer trigger: Prefer pull_request over pull_request_target where possible.

• Restrict code checkout: If you must use pull_request_target, ensure that the code is only checked out from a trusted branch by specifying an explicit ref:

• Limit workflow permissions to minimize access to secrets and other sensitive data.

Actions should be pinned to a full-length commit SHA

This check ensures each GitHub Action used in the job is referenced using a full-length commit SHA instead of a branch name or version tag.

Why This Matters

Referencing GitHub Actions by branch name (e.g., main) or version tags (e.g., v1.0.0) introduces security risks. The action’s code could change unexpectedly, potentially introducing vulnerabilities. Pinning actions to a full-length commit SHA ensures that only the expected, reviewed code is executed, reducing the risk of supply chain attacks.

How to Fix it

• Pin Actions to a full-length commit SHA.

• Fix this issue with an automated pull request that adds the step-security/harden-runner GitHub Action to the job using or

Compromised npm packages found in PR

This check ensures that pull requests (PRs) do not introduce known compromised npm packages into the codebase.

Why This Matters

Introducing compromised npm packages into a repository can result in severe security issues, including:

• Unauthorized code execution during CI/CD runs,

• Exfiltration of secrets via malicious package behavior,

• Complete takeover of repository environments, especially if secrets or deployment keys are exposed during the workflow.

How to Fix it

• Update the compromised package(s) to a safe version, preferably the latest secure release.

• Replace or remove the package if it is no longer actively maintained or cannot be safely updated.

• Rotate your secrets if a known-compromised package was already used in prior workflow runs.

GITHUB_TOKEN should have minimum permissions

This check ensures that GitHub workflows use the least required token permissions at the job or workflow level, reducing the risk of excessive access.

Why This Matters

By default, GitHub tokens may have broad permissions, increasing the attack surface. If a workflow grants unnecessary privileges, a compromised workflow run could lead to unauthorized actions, such as modifying repository settings or leaking sensitive data.

How to Fix it

• Set minimum GitHub token permissions at the job or workflow level.

• Fix this issue with an automated pull request that adds the step-security/harden-runner GitHub Action to the job using or

Third-party GitHub Actions with high scores should be used

This check ensures each GitHub Action used in the job has a security score of 6 or above to minimize security risks.

Why This Matters

Using third-party GitHub Actions with low-security scores increases the risk of vulnerabilities, including supply chain attacks. Actions with higher security scores are more likely to follow best practices, reducing the chance of exploitation.

How to Fix it

• Use instead of third-party Actions with a low score.

• If there are no StepSecurity Maintained Actions, then you can

OIDC should be used when deploying to the cloud

This check ensures deployment GitHub Actions that support OpenID Connect (OIDC) are configured to use OIDC authentication instead of long-term secrets.

Why This Matters

Using long-term secrets in workflows increases security risks, as secrets can be leaked, misused, or rotated improperly. OIDC provides a more secure and automated way to authenticate deployments, eliminating the need to store and manage credentials manually.

How to Fix it

• Enable OIDC authentication for your deployment Actions instead of using static secrets.

• Update workflows to use federated credentials, which allow short-lived tokens to be issued dynamically.

• Remove long-term secrets from your repository and migrate to OIDC-based authentication for enhanced security.

Publishing secrets should be set as environment secrets

This check ensures publishing secrets are stored as environment secrets rather than repository or organization secrets, ensuring they are only accessible under controlled conditions.

Why This Matters

Storing publishing secrets as environment secrets restricts their access to workflows running in protected branches or requiring manual approval. This prevents unauthorized use of sensitive credentials, reducing the risk of accidental exposure or misuse.

How to Fix It

• Move publishing credentials to environment secrets instead of using repository or organization secrets.

• Configure deployment protection rules to enforce manual approvals or restrict deployments to protected branches.

Secrets should be rotated periodically

This check ensures all Organization and Repository secrets have been rotated within the last 180 days to minimize security risks.

Why This Matters

Long-lived secrets increase the risk of exposure, as compromised credentials can be misused for extended periods. Regularly rotating secrets reduces the likelihood of unauthorized access and mitigates the impact of leaked credentials.

How to Fix It

If this check fails, take one of the following actions:

• Rotate secrets at least every 180 days to maintain security.

• Use OpenID Connect (OIDC) for authentication instead of long-term secrets to eliminate the need for manual rotation.

• Automate secret management by integrating secret rotation policies into your security workflows.

Secrets should not be logged in the build log

This check ensures no secrets are present in the build log, preventing accidental exposure of sensitive credentials.

Why This Matters

If secrets are logged in plaintext during builds, they can be exposed to unauthorized users, leading to security breaches. Attackers may exploit leaked credentials to gain access to repositories, infrastructure, or sensitive data.

How to Fix It

If this check fails, take one of the following actions:

• Mask sensitive values by using GitHub’s secrets masking feature to prevent them from appearing in logs.

• Avoid echoing secrets in scripts—use environment variables securely instead of printing them.

• Review build logs regularly for unintended secret exposure and take corrective action.

• Use OpenID Connect (OIDC) for authentication where possible to reduce reliance on long-term secrets.

StepSecurity Artifact Monitor is a zero-friction solution for continuously monitoring your software artifacts. It detects unauthorized releases in real time and ensures every version originates from your official CI/CD pipelines.

Dashboard Overview

Top-Level Metrics

• Total Artifacts: Displays the number of artifacts currently being monitored.

• Non-Compliant: Shows how many artifacts have at least one version not published through an authorized CI/CD pipeline.

• Compliant: Shows how many artifacts are fully compliant, with all versions verified as originating from trusted pipelines.

Artifact List Breakdown

The Artifact Monitor dashboard displays each monitored artifact as a row with the following details:

• Artifact Name: A clickable label (e.g., @harden-runner-canary/basic-npm-package) that links to the artifact’s detailed compliance view.

• CI/CD Workflow File: Indicates the CI configuration file (e.g., publish.yml) associated with the release.

• Artifact Type: Currently supported types include npm packages, with support for additional registries coming soon.

• Last Published: Timestamp showing when the most recent version was released.

• Last Monitored: Indicates when Artifact Monitor last scanned the artifact for compliance.

• Compliance Summary:

  • A visual ring chart shows how many versions are compliant (green) versus non-compliant (red).

  • The center number represents the total number of published versions detected.

  • If an artifact has one or more non-compliant versions, a warning icon appears next to its name

Detailed View (View Details)

Clicking View details opens a compliance log for all versions of the selected artifact. The version table includes:

• Version: The version string of the artifact.

• Release Date: Timestamp of when the version was published.

• Confidence Level: Risk score based on provenance data and detection algorithms.

• Compliance: Status based on whether the release matched an approved CI/CD pipeline.

• Logs: Direct link to CI logs or workflow runs.

How It Works

• Real-Time Tracking: Instantly detects new software versions as soon as they are published to your artifact registry.

• CI/CD Verification: Traces each release back to an authorized CI/CD pipeline.

  • Authorized: Releases published via an approved CI/CD workflow are marked as safe.

  • Unauthorized: If no valid CI/CD job is found, the system sends an alert to your security team.

• Immediate Alerts: Notifications are sent instantly, enabling your security team to respond before a potential attack spreads.

Key Features & Benefits

• Continuous Monitoring: Constantly watches artifact registries like npm, with support for ECR, DockerHub, and more coming soon.

• Automated CI/CD Verification: Ensures every artifact version is tied to a trusted release process.

• Instant Security Alerts: Detects unauthorized or rogue releases in real time—critical for preventing supply chain attacks.

• Zero False Positives: Leverages provenance data when available and uses proprietary detection technology when it’s not.

• No Developer Overhead: Integrates with existing pipelines out of the box. No code changes or developer involvement required.

Creating a New Artifact

Step 1: Navigate to "Artifact Monitor" on your dashboard

Step 2: Click "Add Artifact"

Step 3: Fill in the details of the Artifact:

• The Artifact name

• Specify the Artifact type

• Specify the path to your GitHub Actions workflow file that handles artifact publishing

Step 4: Click "Add Artifact"

• Artifact Monitor will begin scanning the artifact, detecting its published versions and checking each one for a valid CI/CD provenance.

The Secure Repo feature in StepSecurity allows you to apply security best practices across all GitHub Actions workflows in your repository. It automates security improvements by scanning workflows, suggesting fixes, and generating a pull request for seamless integration.

Key Features

• Automated Security Enhancements: Analyzes and applies security best practices to all workflow files.

• One-Click PR Creation: Generates a pull request with security fixes for easy review and merging.

• GitHub Best Practices Compliance: Ensures workflow permissions, dependencies, and secrets follow industry standards.

• Minimal Manual Intervention: StepSecurity automatically enforces security measures with minimal user effort.

• Orchestrate Custom Workflows: Define and enforce standardized GitHub Actions workflows across repositories by specifying mandatory template workflows that must be included in every repository. Learn how to use this feature .

How to Secure Your Repository Using Secure Repo

Step 1: Access the StepSecurity Dashboard

• Visit or navigate to “Secure Repo” under the Orchestrate Security section in your StepSecurity dashboard.

Step 2: Enter Your GitHub Repository

• Click on the "Enter Your GitHub Repository" field.

• Type or paste the URL of your GitHub repository.

Step 3: Analyze the Repository

• Click the "Analyze Repository" button.

• Secure Repo will scan your repository and suggest security improvements.

Step 4: Preview the Changes

• Click "Preview Changes" to review the security enhancements.

Step 5: Review commit message

• Review the commit message generated by Secure Repo.

• Click "Preview Changes" again to proceed.

Step 6: Review Read-Only Preview

• Click on the "read-only preview" to review the proposed changes before creating a pull request

Step 7: Inspect the Code Changes

• Ensure the proposed changes align with your repository’s security need

Step 8: Create a Pull Request

1. Click "Create Pull Request".

2. Confirm the pull request details and click "Create Pull Request" again.

Step 9: Final Confirmation

• Secure Repo will generate a confirmation message.

• Click the provided link to view your pull request on GitHub.

Step 10: Merge the Pull Request

• Once you've reviewed the changes, click the "Merge Pull Request" button to apply the fixes to your repository.

Step 11: Verify Security Fixes

• After merging, confirm that the security fixes have been successfully applied by viewing the updated repository.

• You can also re-analyze the repository in StepSecurity to verify the changes.

How To Setup Custom Workflow Templates

Workflow templates allow you to define standardized workflows that can be used across all repositories in your organization. Setting up workflow templates is simple—just follow these steps:

Step 1: Access the StepSecurity Dashboard

• Click on your user profile picture in the StepSecurity dashboard.

• Select "User Settings" from the dropdown menu.

Step 2: Configure Workflow Templates

• Navigate to the Workflow Templates section under User Settings.

• Enter the repository link containing the GitHub workflow templates.

• Click "Update Templates Repository" to save your changes.

Step 3: Secure and Analyze a Repository

• Go to Secure Repo under the Orchestrate Security section.

• Enter the link to a repository in your organization.

• Click "Analyze Repository" to review security configurations.

Step 4: Apply Workflow Templates to Repositories

• Review the suggested changes in the repository.

• The system will automatically apply the specified workflow templates.

Corporate laptops and production servers have strong security monitoring for compliance and risk reduction. However, CI/CD runners, which handle sensitive data like cloud secrets and production builds, often lack such protections, making them targets for supply chain attacks like SolarWinds and Codecov.

Traditional security tools struggle with CI/CD runners due to their short-lived nature and lack of workflow context.

Harden-Runner fills this gap by providing tailored security monitoring, ensuring CI/CD runners receive the same protection as other critical systems.

Security Incidents Detected

• Harden-Runner Detected the tj-actions/changed-files compromise (CVE-2025-30066)

• Harden-Runner Detected a CI/CD Supply Chain Attack in Google’s Open-Source Project Flank

• Harden-Runner Detected a CI/CD Supply Chain Attack in Microsoft’s Open-Source Project Azure Karpenter Provider in Real-Time

• Harden-Runner Detected Anomalous Traffic to api.ipify.org Across Multiple Customers

• Harden-Runner Flagged an Anomalous Outbound Call, Leading to a Docker Documentation Update

Threats in a CI/CD Environment

Compromised workflows, dependencies, and build tools pose two major threats:

1. Exfiltration of CI/CD credentials and source code

2. Tampering of source code, dependencies, or artifacts during the build process to inject backdoors

To mitigate these risks, Harden-Runner provides key security measures. The table below outlines its core functionalities and the threats they help prevent:

Enabling Runtime Security with Harden-Runner

Securing your CI/CD pipelines requires configuring your runners with StepSecurity’s Harden-Runner, which provides comprehensive monitoring and protection across different runner environments.

Harden-Runner supports multiple CI/CD runner types:

GitHub-Hosted Runners

Step 1: Add the step-security/harden-runner GitHub Action to your GitHub Actions workflow file as the first step in each job. You can automate adding Harden-Runner Action to your workflow file by using Secure Workflow.

steps:
  - uses: step-security/harden-runner@v2 # v2.10.3
    with:
      egress-policy: audit

Step 2: You will see a link to security insights and recommendations in the workflow logs and the job markdown summary.

Step 3: Click on the link (example link). You will see a process monitor view of network and file events correlated with each step of the job.

Step 4: In the Recommended Policy tab, you'll find a recommended block policy based on outbound calls aggregated from the current and past runs of the job. You can update your workflow file with this policy or use the Policy Store to apply the policy without modifying the workflow file. From now on, any outbound calls not on the allowed list will be blocked.

Self-Hosted VM Runners

To enable runtime security for self-hosted runners on Cloud VMs (e.g. EC2 instances), you can add the Harden-Runner agent to your runner image.

Instead of adding the Harden-Runner GitHub Action in each job, you'll need to install the Harden-Runner agent on your runner image (e.g., AMI). This is typically done using a packer or as a post-install step when using the https://github.com/philips-labs/terraform-aws-github-runner project to set up runners.

The Harden-Runner agent monitors all jobs run on the VM; both ephemeral and persistent runners are supported; you do NOT need to add the Harden-Runner GitHub Action to each job for audit mode. You must add the Harden-Runner GitHub Action to jobs where you want to enable block mode.

You can access security insights and runtime detections under the Harden-Runner section in your dashboard.

Self-Hosted bare-metal Runners

Self-hosted bare-metal runners are set up by installing the harden-runner agent as a service. This setup closely resembles the self-hosted cloud VM scenario but runs directly on physical hardware instead of virtualized environments.

Actions Runner Controller (ARC) Runners

Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates and scales self-hosted runners for GitHub Actions.

Rather than incorporating the Harden Runner GitHub Action into each individual workflow, you'll need to install the ARC-Harden-Runner daemonset on your Kubernetes cluster.

Upon installation, the ARC Harden-Runner daemonset monitors all jobs run on the cluster; you do NOT need to add the Harden-Runner GitHub Action to each job for audit mode. You need to add the Harden-Runner GitHub Action to jobs where you want to enable block mode.

You can access security insights and runtime detections under the Runtime Security tab in your dashboard.

How to access Harden-Runner security insights

For each GitHub Actions workflow run, Harden-Runner monitors the run-time network, file, and process events and makes runtime insights available via the StepSecurity Web App.

There are four ways to find the insights link:

• BuildLog

• Workflow Runs

• Markdown Job Summary

• GitHub Checks

BuildLog

Step 1: Navigate to build log of your workflow file in Github Actions.

Step 2: Look for the Harden-Runner step in the log and click on the Insights link which appears in the logs as View security insights and recommended policy at: followed by a clickable URL (this is an example link).

Step 3: Once you click on the Insights link, you will be redirected to the Summary tab in the StepSecurity Web App. The Summary Page provides an overview of:

• Outbound destinations contacted during the job execution.

• HTTPS requests and the number of actions taken.

• Detections (if any security risks were found).

Workflow runs

StepSecurity provides a dashboard where you can view the latest GitHub Actions workflow runs monitored by Harden-Runner. This guide will help you navigate the dashboard and access insights for specific workflow runs.

Step 1: Navigate to https://app.stepsecurity.io/github/<GITHUB_ORG_NAME>/actions/dashboard

Step 2: In the left-hand menu, under Harden-Runner, click Workflow Runs

Step 3: After opening the Workflow Runs page, locate the workflow you want to inspect and click on it.

Step 4: Once inside the workflow details page, navigate to the Summary tab.

Here, you can review:

• Outbound destinations contacted during the workflow.

• Security detections (if any were found).

• Actions performed by the workflow.