GitHub-hosted runner

On GitHub-hosted runners, add cicd-sensor/cicd-sensor-action to the workflow to start monitoring.

With the default settings, the cicd-sensor action starts the agent before your workload, records job runtime activity, and uploads the HTML report and runtime-trace attestation predicate as artifacts after the job. Optional inputs can enable centralized configuration through cicd-sensor Manager, cloud delivery for Summary Log / Detection Log / Runtime Event Log, and debug bundle uploads that include Runtime Event Log output.

Usage

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - uses: cicd-sensor/cicd-sensor-action@2b76335ff1c2dd298e983961f7a200d3fe9076c2 # v0.0.36

This action targets Linux GitHub-hosted VM runners. You can use x64 and arm64 runner labels.

Examples:

ubuntu-latest
ubuntu-24.04
ubuntu-22.04
ubuntu-24.04-arm
ubuntu-22.04-arm

The supported kernel ranges differ by architecture: 5.15 or later on amd64, 6.1 or later on arm64. The arm64 lower bound comes from upstream Linux because BPF trampoline / fentry attach was added on arm64 only in 6.0+.

ubuntu-slim is not supported. It runs as a container on a shared VM and does not provide the host eBPF environment that cicd-sensor needs.

Third-party hosted runners

Third-party GitHub Actions hosts (for example, Blacksmith and BuildJet) often run their own kernel builds, so eBPF capabilities can differ from GitHub’s runner images even when the OS and kernel version look similar.

cicd-sensor also requires kernel BTF to load its eBPF CO-RE programs. A supported Linux kernel version alone is not sufficient; the running kernel must expose BTF at /sys/kernel/btf/vmlinux. Check a runner with:

ls /sys/kernel/btf/vmlinux

If the file is missing, the kernel may not have been built with CONFIG_DEBUG_INFO_BTF=y, and cicd-sensor may fail to start with a “no BTF found” error.

cicd-sensor attaches its programs with fentry, which requires the target kernel functions to be fentry-attachable (present in /sys/kernel/tracing/available_filter_functions). When a required function is not exposed, the agent fails to start at BPF load time.

Blacksmith

Blacksmith Ubuntu 24.04 x86_64 runners (kernel 6.5.13, as of 2026-06) are supported from v0.0.38 onward. These runners expose kernel BTF at /sys/kernel/btf/vmlinux, so cicd-sensor can load its eBPF CO-RE programs.

Blacksmith ARM64 runners are not currently supported because their runner kernel ships without kernel BTF, so /sys/kernel/btf/vmlinux is missing. Use a Blacksmith x86_64 runner for jobs that run cicd-sensor, or disable cicd-sensor on Blacksmith ARM64 jobs.

Earlier versions failed to start on Blacksmith x86_64 because they attached fentry/security_socket_connect, which is not fentry-attachable on Blacksmith’s kernel. v0.0.38 observes AF_UNIX connects through fentry/unix_stream_connect and fentry/unix_dgram_connect instead, both of which are available there.

For Blacksmith x86_64, action v0.0.33 and later default to a compatible agent, so no extra configuration is needed. On older action releases, set cicd-sensor-version: v0.0.38 explicitly.

Standalone mode

When no manager is configured, the agent starts inside the GitHub Actions job and uploads the HTML report as a job artifact.

flowchart LR
    JOB["GitHub Actions Job"]
    ACTION["cicd-sensor Action"]
    AGENT["cicd-sensor Agent"]
    REPORT["cicd-sensor-report<br/>HTML artifact"]

    JOB --> ACTION --> AGENT --> REPORT

    classDef cicdSensor fill:#ecfdf5,stroke:#0f766e,color:#134e4a,stroke-width:1.5px;
    class ACTION,AGENT cicdSensor

The attestation artifact is generated by default. Signing is not done by the action itself; use a downstream step or job, such as actions/attest, when you want to sign it.

Config and Rules

In standalone mode, project-local config and custom rules live under .cicd-sensor/.

repo/
  .cicd-sensor/
    config.yaml
    rules/
      a.yaml
      b.yaml

Even when project-local rules are not present, Baseline Rules still apply by default. Use project-local files only for repository-specific tuning or additional detections.

config.yaml

config.yaml controls project-local defaults for the GitHub-hosted standalone mode.

default_max_alerts_per_rule: 20
disable_baseline_rules: false
monitor_mode: true

Field	Meaning
`default_max_alerts_per_rule`	Default Detection Log limit for rules that do not set `max_alerts`. Allowed values are 1-100.
`disable_baseline_rules`	Disable cicd-sensor baseline rules for standalone project-local mode. Defaults to `false`.
`monitor_mode`	Treat `terminate` rules as `detect` rules. Recommended for first rollout. Defaults to `false`.

See RuleSet max_alerts for per-rule limits.

rules/

Place one or more YAML files under .cicd-sensor/rules/. For example:

rule_sets:
  - ruleset_id: acme/github-hosted
    rules:
      - rule_id: curl_exec
        rule_name: "curl executed"
        event_type: process_exec
        condition: process.exec_path.endsWith("/curl")
        action: detect

This emits a Detection Log entry when curl is executed during the job. See RuleSet, Event types, CEL conditions, Correlation, and Rule modifiers for the full rule syntax.

The action can be placed as the first step so it can monitor the whole job. It is fine to place it before actions/checkout.

Rules can be validated before running the workflow.

cicd-sensorctl rule validate .cicd-sensor/rules

Manager delivery

Use cicd-sensor Manager when you want to send Summary Logs, Detection Logs, and Runtime Event Logs from GitHub-hosted runners to cloud-side outputs. In this mode, the cicd-sensor Agent can still generate the HTML report and attestation artifact as job artifacts.

Important: when manager-url is set, repository-local .cicd-sensor/config.yaml and .cicd-sensor/rules/ are not used. Config and rules are fetched from the manager. Repository-local rules and manager rules are not combined. Baseline policy is also owned by the manager, not by repository-local config.

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - uses: cicd-sensor/cicd-sensor-action@2b76335ff1c2dd298e983961f7a200d3fe9076c2 # v0.0.36
        with:
          manager-url: https://cicd-sensor-manager.example.com
          manager-token: ${{ secrets.CICD_SENSOR_MANAGER_TOKEN }}

flowchart LR
    ACTION["GitHub Actions job<br/>with cicd-sensor-action"]
    AGENT["cicd-sensor Agent"]
    MANAGER["cicd-sensor-manager"]
    ARTIFACTS["Job artifacts<br/>HTML report / Attestation"]
    OUTPUTS["Cloud outputs / SIEM"]

    ACTION --> AGENT
    MANAGER -.->|"Config / Rules"| AGENT
    AGENT --> ARTIFACTS
    AGENT -->|"Logs"| MANAGER
    MANAGER --> OUTPUTS

    classDef cicdSensor fill:#ecfdf5,stroke:#0f766e,color:#134e4a,stroke-width:1.5px;
    class ACTION,AGENT,MANAGER cicdSensor

Store the manager token as a GitHub Actions secret. Do not write secrets or tokens into repository config files.

Action reference

For detailed inputs and outputs, see cicd-sensor/cicd-sensor-action.

Keyboard shortcuts

cicd-sensor Docs