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.

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 StepSecurity Community Tier! Here’s everything you need to know to get started:

How to Get Started

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

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

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

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.

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

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

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

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

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

• Avoid using context variables in script execution unless properly sanitized.

• Use safe quoting practices when referencing context variables in shell commands.

Example:

run: echo "${{ github.event.issue.title }}"

instead of:

run: echo ${{ github.event.issue.title }}

• Validate and sanitize user-controlled inputs before using them in workflows.

• Restrict workflow permissions to limit exposure in case of an injection attack.

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:

- name: Checkout trusted code
  uses: actions/checkout@v3
  with:
    ref: 'main' # Specify a safe reference instead of defaulting to PR changes

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

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.

Leaked secrets due to compromise of reviewdog GitHub Actions

This check ensures that workflows do not use the vulnerable reviewdog/actions-setup GitHub Action, which could lead to unauthorized access to secrets and repository compromise.

Why This Matters

The review dog/actions-setup GitHub Action has a known vulnerability that could be exploited to compromise repository secrets. If an attacker gains control over this action, they could leak credentials, tamper with workflow execution, or escalate privileges within the CI/CD pipeline.

How to Fix It

To resolve this issue, replace all instances of tj-actions/changed-files@vx with a secure alternative:

• Use step-security/reviewdog-action-setup@fab6de28ae8bc2a032c9e655d990afa450edb995 # v1.3.2 or step-security/reviewdog-action-setup@v1.

Leaked secrets due to compromise of tj-actions/changed-files GitHub Actions

This check ensures that workflows do not use the vulnerable tj-actions/changed-files GitHub Action, which could lead to unauthorized access to secrets and repository compromise.

Why This Matters

The tj-actions/changed-files GitHub Action has a known vulnerability that could be exploited to compromise repository secrets. If an attacker gains control over this action, they could leak credentials, tamper with workflow execution, or escalate privileges within the CI/CD pipeline.

How to Fix It

To resolve this issue, replace all instances of tj-actions/changed-files@vx with a secure alternative:

• Use step-security/changed-files@3dbe17c78367e7d60f00d78ae6781a35be47b4a1 # v45.0.1 or step-security/changed-files@v45

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

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.

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.

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.

You can view all unique network destinations from all workflow runs in your organization on the Harden-Runner menu.

• The All Destinations tab under the Harden-Runner menu provides a detailed list of all network destinations contacted by your Actions runners.

• For each listed endpoint, clicking View under the Sample Workflow Runs option allows you to examine individual GitHub Actions workflow runs that interacted with it.

Additionally, you can view unique outbound network destinations for your ARC clusters from all workflow runs within your clusters:

• Switch to the Arc Clusters tab

• For each listed endpoint, clicking the View button under the Sample Workflow Runs option enables you to examine individual GitHub Actions workflow runs that interacted with the endpoint.

The Workflow Run Details page provides an in-depth view of each CI/CD job execution, including network activity, file modifications, and security detections. It highlights key security metrics, outbound destinations, and policy recommendations, helping you monitor and secure your workflows effectively.

Runtime Summary States

• Empty/No Tag: No detections were found; Harden-Runner is functioning as expected.

• Harden-Runner Not Enabled: Harden-Runner is not active in your workflow.

• Overwritten File: A file in the workflow has been overwritten.

• Jobs Without Harden-Runner: At least one job in the workflow lacks Harden-Runner coverage.

• Blocked Call: An endpoint has been blocked.

• New Endpoint: A network call deviated from the baseline, indicating potential anomalies.

Features Available in Harden-Runner

View outbound network traffic at the job level

Harden-Runner monitors all outbound traffic from each job at the DNS and network layers

• After the workflow completes, each outbound call is correlated with each step of the job, and shown in the insights page

• For self-hosted runners, no changes are needed to workflow files to monitor egress traffic

• A filtering (block) egress policy is suggested in the insights page based on the current and past job runs

To access this feature switch to the Network Events tab on your Insights page

For the Enterprise Tier, the PID is available, and you can click on it to view the process arguments

Detect anomalous outbound network traffic

You can detect suspicious/ anomalous traffic using this feature even in egress-policy:audit mode.

To access this feature switch to the Recommendations tab on your Insights page

• Anomaly detection feature creates a machine learning model of outbound network calls by analyzing the historical data of the same workflow in previous runs

• Once the baseline is established, any anomalous outbound destinations are flagged on the insights page, triggering real-time alerts

• You can view the list of all anomalous outbound network traffic in the All Detections page on the dashboard

Filter outbound network traffic to allowed endpoints

You can see recommended egress block policy in the Recommendations tab for each job. This is based on observed traffic across multiple runs of the job.

Once you set these allowed endpoints in the workflow file, or in the Policy Store(Need to understand this more) and switch to using egress-policy:block

• Harden-Runner blocks egress traffic at the DNS (Layer 7) and network layers (Layers 3 and 4)

• It blocks DNS exfiltration, where attacker tries to send data out using DNS resolution

• Wildcard domains are supported, e.g. you can add *.data.mcr.microsoft.com:443 to the allowed list, and egress traffic will be allowed to eastus.data.mcr.microsoft.com:443 and westus.data.mcr.microsoft.com:443

Disable telemetry in block mode

Harden Runner sends telemetry related to egress traffic to the StepSecurity API, e.g.

• Domain names resolved,

• IP addresses called, and

• Processes that made these calls

When you use egress-policy: block mode, and if you do not want this telemetry to be sent anymore, you can set disable-telemetry: true.

When this is done, telemetry will no longer be sent to StepSecurity API.

Example

Here is an example of how to use disable-telemetry: true

name: Harden Runner
uses: step-security/harden-runner@v2
with:
  egress-policy: block
  disable-telemetry: true
  allowed-endpoints: >
    api.github.com:443
    github.com:443

Detect tampering of source code during build

Harden-Runner monitors file writes and detects if any source code files are overwritten during a build.

Why is this important?

• Source code overwrites are unexpected in a release build.

• All source code files are monitored, including infrastructure-as-code (IaC) files such as Kubernetes manifests and Terraform configurations.

• Notifications can be enabled to receive alerts when source code modifications occur.

• No additional changes are needed for self-hosted runners to enable file monitoring.

How to Detect Source Code Overwrites

Step 1: Access the Workflow Runs

Navigate to Latest Workflow Runs under the Harden-Runner menu in your StepSecurity dashboard. If any files were overwritten, you’ll see an alert similar to this:

Step 2: View File Write Events

• Click on the workflow insights

• Go to the File Write Events tab

• You’ll see a list of overwritten files, including their paths and timestamps.

Enterprise-tier users get additional details such as:

• The process that wrote to the file.

• The arguments passed during the write operation.

Step 3: Investigate the Overwrite

• Identify the file and its path.

• Review the detection timestamp for when the overwrite occurred.

• If unexpected, trigger a security review or rollback to a safe commit.

Run your job without sudo access

GitHub-hosted runner uses passwordless sudo for running jobs.

• This means compromised build tools or dependencies can install attack tools

• When you set disable-sudo-and-containers to true, the job steps run without sudo access to the GitHub-hosted Ubuntu VM. You can only use this option if you do not use docker in your job. If a job attempts to use the sudo command, the CI will fail.

Here is an example of how to use this option:

- uses: step-security/harden-runner@v2
  with:
   disable-sudo-and-containers: true
   egress-policy: audit

View outbound GitHub API calls at the job level

This feature provides visibility into outbound GitHub API calls made during a job execution. It logs details such as HTTP methods and request paths, helping detect any unauthorized data exfiltration attempts through GitHub.com .

How it Works

Clicking on any Destination in the Network Events tab reveals detailed information about the process that initiated the event, along with its process arguments.

This allows you to:

• Identify which processes are making outbound requests.

• Inspect HTTP methods and API endpoints used.

• Monitor network activity for potential security concerns.

For example, in the screenshot below, clicking on ghcr.io under the Destination column reveals detailed API call logs, including HTTP methods such as GET, POST, HEAD, PATCH, and PUT. This visibility helps track and analyze API interactions effectively.

Determine minimum GITHUB_TOKEN permissions

Harden-Runner monitors outbound HTTPS requests using eBPF and uses the PATHs and VERBs of these HTTPS calls to recommend the minimum GITHUB_TOKEN permissions for each job in your workflow.

• GITHUB_TOKEN is an automatically generated secret used to authenticate to GitHub APIs from GitHub Actions workflows.

• Harden-Runner can monitor the VERBs (e.g., GET, POST) and PATHs (e.g., /repos/owner/repo/issues) for calls made to the GitHub APIs from the runner.

• Each GitHub Actions API call requires a corresponding GITHUB_TOKEN permission. For instance, a GET request to the /repos/org/repo/info/refs?service=git-upload-pack endpoint requires the contents: read permission.

• The recommendation for the minimum GITHUB_TOKEN permissions are show in the Recommendations tab.

View the name and path of every file written during the build process

View the name and path of every file that was written during the build process.

• Harden-Runner tracks every file written to the GitHub Actions working directory during the build process.

• In the insights page in the File Write Events tab you can see a file explorer view of each file that was written to.

• Clicking on any file reveals a list of processes that wrote to it, providing complete transparency.

View process names and arguments

Gain deeper insights into your build environment by viewing process names, Process IDs (PIDs), and process arguments.

To access this feature switch to the Network Events tab on your Insights page

How it Works

• Harden-Runner tracks every process that is run during the build process.

• Clicking on any process ID (PID) in the network events shows the process that caused the event, along with the process arguments.

• You can walk up the process tree to analyze parent-child relationships, helping you detect suspicious activity and understand how processes interact.

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:

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

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

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

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

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

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

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.

Markdown Job Summary

Step 1: Navigate to the workflow run page

Step 2: Click "📄 View Full Report"

Step 3: Review the outbound connections allowed during the workflow execution.

GitHub Checks

Step 1: Navigate to the Pull Request

Step 2: View Check Details

• Look at the checks summary under your pull request.

• Identify any failed or successful checks.

• Click on the “Details” link next to the StepSecurity Harden-Runner check.

Step 3: Access Insights URL

• On the new page, select StepSecurity Harden-Runner from the list of workflow checks.

• Find the Insights URL under the Workflow Run Insights section.

• Click the Insights URL to proceed.

Step 4: Review Security Insights

• The Insights page will display outbound traffic details, network events, and security findings.

• Verify if any unauthorized outbound connections were detected.

• Review the All Outbound Destinations and All Detections sections for further analysis.

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

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.

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

• File events: File writes tracked during the job.

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 Orchestrate Security section in StepSecurity allows you to analyze your GitHub Actions workflows against security best practices and automatically fix security gaps through automation

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

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

How to Secure Your Repository Using Secure Repo

Step 1: Access the 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.

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

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

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

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 support@stepsecurity.io.

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.

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

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

• 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

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

5. Release Safeguards:

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

   • Utilizes ephemeral GitHub Actions tokens instead of persistent bot accounts

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

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

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

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

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

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

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

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

Exploring StepSecurity Maintained Actions

• Go to the Actions section and select StepSecurity Actions.

• A list of StepSecurity-maintained actions will be displayed.

• Click on any maintained action (e.g step-security/action-semantic-pull-request)

• You will be redirected to the GitHub Actions Advisor, where you can compare the security score of StepSecurity-maintained action with the original action.

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 Score

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

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

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.

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.

Scenario

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

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

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.

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

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

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)

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:

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

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

Sections

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

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.

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

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

Leave other fields as default and continue.

Step 6: Map Identity Attributes

• In the "Attribute Mapping" section:

  • Map Primary Email ➔ email.

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

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

Step 6: Add Attribute Statement

• Under Attribute Statements, add the following field:

  • email → user.email

Step 7: Save Settings

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

Step 8: Provide Feedback

• Optionally, provide feedback. Then click Finish.

Step 9: 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 10: Assign Users

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

Step 11: 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.

What is RunsOn?

• 10x cheaper than GitHub-hosted runners

• at least 30% faster than GitHub-hosted runners

• 5x faster, unlimited caching with S3-local bucket

• fully self-hosted in your own AWS account

• no concurrency limits

• native x64, arm64, GPU, and Windows support

• SSH access, advanced networking, and more

RunsOn is a partner of StepSecurity and provides ready-made base images that contain the StepSecurity agent for self-hosting use.

Getting Started with StepSecurity on RunsOn

1. Get a StepSecurity API Key

   • You need a StepSecurity Enterprise License.
2. Configure RunsOn –

   1. Get your StepSecurity API key (from Settings-> Self Hosted Runners-> Self Hosted VM -> RunsOn Integration)

   2. Enter it in the RunsOn CloudFormation template.
3. Use StepSecurity images in your workflows. Here is the list of all StepSecurity images:

   • ubuntu24-stepsecurity-x64

   • ubuntu24-stepsecurity-arm64

Example

FAQ

How much does StepSecurity cost?

Does Harden-Runner impact CI/CD performance?

No, Harden-Runner is optimized for low overhead. It monitors activity efficiently without slowing down builds.

Can I use the Harden-Runner community tier with RunsOn?

No, the Harden-Runner community tier only works with GitHub-hosted runners. Self-hosted runners with RunsOn will need a StepSecurity enterprise license.

Resources

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?

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.

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.

The GitHub Issues and Pull Requests setting 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:

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

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

You can also edit the PR template to customize the content of the pull requests.

Controls

These controls enable automatic detection and remediation of specific risks:

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

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

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