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.

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

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

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

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.

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

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

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].

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.

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:

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, 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:

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.

This guide walks you through the steps to set up and use 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:

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.,) 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.

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:

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 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 .

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 for setup assistance.

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:

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

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.

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 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 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:

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 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.

StepSecurity supports Single Sign-On (SSO) to help organizations manage user access in a secure and centralized way.

You can enable SSO using popular identity providers like Okta, Google Workspace, or Microsoft Entra ID. To set this up for your organization, please , and we’ll help you get started.

Once SSO is enabled, you can enforce it across your organization to ensure that all members sign in using your configured identity provider.

In addition to SSO, members can also sign in using their email and password or GitHub account, depending on your chosen configuration.

From this page, you can:

• Configure SSO settings

• Enforce SSO for all members

• Choose which login methods are allowed (SSO, GitHub, email/password)

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.

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

Using Suppression Rules

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

Follow this interactive demo to get started:

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)

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

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 SAML-based SSO to simplify secure user access and identity management. StepSecurity integrates seamlessly with leading identity providers, including:

• Okta

• Google Workspace

• Microsoft Entra ID (formerly Azure AD)

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:

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

• Slack / Microsoft Teams Webhooks: Get real-time alerts and policy updates where your teams already collaborate.

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

AWS Marketplace Availability

StepSecurity is available on AWS Marketplace, 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.

Scenario

You received a detection alert for an anomalous outbound network call either via Email/ Slack notification or a failed GitHub Check.

Click on the insights link in the notification or the GitHub Check details.

Reviewing the insights page

To determine the cause of the anomalous network call, follow these steps:

Step 1: Identify the source

• Review the job and step that triggered the anomalous network call.

• Locate the specific step in the Insights page and click on it to view the associated build log

Step 2: Inspect the Process ID (PID)

• Click on the PID of the process responsible for the anomalous network call to reveal the process arguments.

Step 3: Check for recent workflow modifications

• Review any new commits that may have altered the workflow file.

Triage

Based on the above information,

• If you believe the endpoint is not expected, reach out to your security team or to [email protected]

• If you believe the endpoint is expected, no action is required. The endpoint will get added to the baseline for this job and you will not be notified of it again

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.

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

• Endpoint to Ignore – Specify the domain or endpoint to suppress (use * for wildcard matching).

• 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 All 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 "Create Rule"

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

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 Policy Based PRs 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:

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

Sections

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.

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 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.

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

• Click Save to apply your changes.

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

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.

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 to fix security issues in a single workflow and 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

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

  • Email & Password

  • 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.

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.

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.

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 or to improve workflow compliance

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

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

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.

Example: A Slack webhook URL was logged in load_tests_int.yml.

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

Example: A JWT token was found in jwt-artifact1

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

Example: A workflow tried to access www.google.com, but it was blocked because it was not part of the baseline

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.

Example: go.mod was changed in int-release.yml

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.

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:

Step 5: Verify the Integration

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

GitHub Checks is a powerful feature that helps you monitor and improve the quality of your code by running automated checks on your repositories.

By enabling this feature, you can gain better insights into your code’s performance, security, and compliance directly within your GitHub workflow.

How to Enable the GitHub Checks Feature

Step 1: Open the SideBar and Access Settings

• Navigate to the StepSecurity Dashboard

• Open the sidebar and click on Settings

Step 2: Select GitHub Check and Enable the Feature

• Click on GitHub Checks from the settings menu

• Locate the repository you want to enable checks for

• Tick the checkbox to enable the checks feature

• Click Save to apply the changes

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.

Step 1: Navigate to

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.

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.

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:

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.

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:

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:

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:

• 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.

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.

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 contact us for setup assistance.

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.

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.

Harden-Runner provides network and runtime security for CI/CD pipelines, helping developers secure their GitHub Actions workflows against supply chain attacks.

This showcase highlights 40 leading open-source projects that have integrated Harden-Runner to monitor outbound network calls, detect anomalies, and enforce security controls in their workflows. These projects are part of a larger ecosystem of 6,000+ open-source repositories and enterprises, including industry giants like Microsoft, Google, Kubernetes, and more, that trust Harden-Runner for CI/CD security.

🔍 See Harden-Runner in action—these insights are publicly available for open-source projects using the community tier.

🔒 Want to secure your own GitHub Actions workflows?

Add Harden-Runner to your project today!

👇Click on a project logo below to explore the security insights Harden-Runner has generated for it.

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.

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.

Use this page to view and manage all workflow run policies created in your organization.

Creating a New Policy in Your Organization

There are four policy types you can create:

• Compromised Actions Policy - Block the use of compromised Actions

• Secret Exfiltration Policy - Prevents unauthorized access to Secrets

• Allowed Actions Policy - Block specific GitHub Actions

• Runner Label Policy - Prevent or monitor usage of specific runners

Compromised Actions Policy

The Compromised Actions Policy prevents the use of known malicious or compromised GitHub Actions in workflows. It scans for references to actions flagged as security risks and blocks their execution to protect your environment.

Why It Matters

Workflows often rely on third-party actions, which may be:

• Compromised via account takeovers

• Malicious by design

• Altered to include malware or backdoors

This policy reduces risk by:

• Maintaining a list of compromised actions

• Scanning workflows for those references

• Blocking runs using them

• Alerting developers with actionable feedback

What Developers See

If a compromised action is used:

• The workflow is automatically canceled and a PR comment explains the violation and suggests trusted alternatives

To try the Compromised Action policy, add this action to your workflow:

step-security/dummy-compromised-action@main

To create a compromised Actions policy, follow the steps below:

Step 1: Navigate to the Policies page

• Go to your StepSecurity dashboard, then to Run Policies → Policies in the sidebar.

Step 2: Click “Create Policy”

• Click the Create Policy button on the top right of the page.

Step 3: Fill in Policy Details

• Policy Name – e.g., Compromised Actions Policy

• Policy Type – Select "Compromised Actions Policy"

• Action – Choose between:

  • Enforce: Actively blocks compromised Actions

  • Dry Run: Sends notifications but does not block

Step 4: Select Repositories

• Choose whether to apply the policy to:

  • All current and future repositories (default), or

  • Select specific repositories manually

Step 6: Save the Policy

• After configuring all settings, click Save to create the policy.

Secret Exfiltration Policy

The Secret Exfiltration Policy protects against unauthorized secret access in GitHub Actions. It blocks modified workflows in non-default branches from using secrets unless explicitly approved.

Why It Matters

Workflows often need secrets to access protected resources. Attackers may exploit non-default branches to run malicious workflows and exfiltrate secrets. This policy helps stop that by:

• Allowing secret access only if the workflow matches the default branch

• Enforcing approval for legitimate changes

• Creating an auditable approval trail

How It Works

• Detects non-default branch workflows accessing secrets (${{ secrets.X }}, toJSON(secrets))

• Compares workflow content to the default branch using SHA256

• Requires a workflows-approved label from a different team member for approval

• Blocks runs without proper matching or approval

What Developers See

If a modified workflow accesses secrets:

• The run is canceled, and a PR comment explains the block and how to get approval (a teammate has to add the "workflows-approved" label to the PR)

• Once the "workflows-approved" label has been added by a teammate, the workflow can be re-run

To create a Secrets Exfiltration policy, follow the steps below:

Step 1: Select “Secret Exfiltration Policy”

Step 2: Choose Target Repositories

Step 3: Save the Policy

Allowed Actions Policy

Use this policy to enforce an allowlist of GitHub Actions. Any action not listed is blocked (Enforce) or flagged (Dry Run).

To create a Allowed Actions policy, follow the steps below:

Step 1: Select “Allowed Actions Policy”

Step 2: Add Actions to Allowlist

• Manually type and add actions (e.g., actions/checkout) OR

• Use All Actions (Used) to select from known usage

• Select one Action and click "Add to Allowed List"

• Decide whether to allow all versions (default) or select specific commit versions OR

• Use Repository Filter (Optional): Go to By Repository (Used) tab → Select a repo → Add used actions

Step 3: Click "Save"

Runner Label Policy

Use this policy to block untrusted GitHub-hosted runners or allow only specific self-hosted runners.

To create a Runner Label policy, follow the steps below:

Step 1: Fill in Policy Details

• Policy Name – e.g., Do not allow GitHub-Hosted Runners

• Policy Type – Select Runner Label Policy

• Action – Choose between:

  • Enforce: Actively blocks disallowed runner labels

  • Dry Run: Sends notifications but does not block

Step 2: Specify Disallowed Runner Labels

• Type in the runner labels you want to block (e.g., ubuntu-latest, macos-latest) and press Enter to add.

Step 3: Select Repositories

Choose whether to apply the policy to:

• All current and future repositories (default), or

• Select specific repositories manually

Step 4: Save the Policy

• After configuring all settings, click Save to create the policy.

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.

StepSecurity supports integrations with external platforms to enhance your security workflows, automate telemetry export, and streamline policy enforcement.

We currently support two third party integrations:

Detection Scenarios

Each detection event is emitted in real-time and includes detailed metadata about the workflow, job, detection, and offending artifacts. Below is a list of detection types currently supported by StepSecurity, along with example payloads for each.

Action-Uses-Commit-From-Non-Default-Branch

Action-Uses-Imposter-Commit

Domain-Blocked

HTTPS-Outbound-Network-Call

New-Outbound-Network-Call

Privileged-Container

Reverse-Shell

Runner-Worker-Memory-Read

Secret-In-Build-Log

Source-Code-Overwritten

After you install the StepSecurity Actions Security GitHub App 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: