Falco Actions

Run Falco in GitHub Actions to detect suspicious behavior in your CI/CD workflows.

These GitHub Actions can be used to monitor your GitHub runner and detect Software Supply Chain attacks thanks to ad-hoc Falco rules specific to this use case.

The repository is home of three GitHub Actions, namely start, stop and analyze. We currently support two modes of operation:

• live mode
• analyze mode

Let's delve into their details.

Note: we recommend users to always pin the dependencies of these GitHub Actions to ensure the use of an immutable release

Live mode

Live mode is meant to protect a single job at runtime. To use this mode, only the start and stop actions are required.

The start action will be responsible of starting Falco in a Docker container using its modern_ebpf probe. In turn, the stop action will stop the container, and a summary of triggered Falco rules will be printed in the job summary.

Note: The actions: read permission is used to contact a Github endpoint to perform a best-effort correlation of Falco events to the job's step. In this way, users can better understand where the problem occurred and try to remediate faster.

Example

jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
    - name: Start Falco
      uses: falcosecurity/falco-actions/start@<commit-sha>
      with:
        mode: live
        falco-version: '0.39.0'
        verbose: true
        
    # ...
    # Your steps here
    # ...

    - name: Stop Falco
      uses: falcosecurity/falco-actions/stop@<commit-sha>
      with:
        mode: live
        verbose: true

Start action

Start action accept the following inputs:

Config file - syscall filtering

Captures can become very big and complex to manage. To address this, applying syscall filters helps keep captures manageable while retaining all the necessary information to assess activity in our workflows.

By default, the action will drop the following syscalls specified in the syscall_ignore.config file.

{
    "ignore_syscalls": [
        "switch",
        "rt_sigprocmask",
        "clock_gettime",
        "rt_sigaction",
        "waitid",
        "getpid",
        "clock_getres",
        "mprotect",
        "gettimeofday",
        "close",
        "time",
        "getdents64",
        "clock_nanosleep"
    ]
}

By passing a custom file to the action, it's possible to override the syscall filtered by default and apply custom filters.

Note: currently only syscall filters are supported on the capture level. More specific filters can be applied using Falco conditions in the analyze action.

Stop action

Stop action accept the following inputs:

Analyze mode

Analyze mode is meant to offer a more detailed report.

To achieve this, a scap file is generated via a Sysdig OS container, which is started and stopped using the start and stop actions, respectively. The capture file is then uploaded as an artifact and passed to a subsequent analyze job, that uses the analyze action. The latter may use additional secrets we want to keep separate from the job we are protecting and integrate with external services to provide more relevant security information, such as OpenAI, VirusTotal, and more. The final report will (configurably) contain:

• Falco rules triggered during steps' execution.
• Contacted IPs
• Contacted DNS domains
• SHA256 hash of spawned executables
• Spawned container images
• Written files
• A summary of the report generated with OpenAI
• Reputation of Contacted IPs
• Reputation of SHA256 hashes

Example

jobs:
  foo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
    - name: Start Falco
      uses: falcosecurity/falco-actions/start@<commit-sha>
      with:
        mode: analyze
        
    # ...
    # Your steps here
    # ...

    - name: Stop Falco
      uses: falcosecurity/falco-actions/stop@<commit-sha>
      with:
        mode: analyze
  
  analyze-foo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
    - name: Analyze
      uses: falcosecurity/falco-actions/analyze@<commit-sha>
      with:
        falco-version: '0.39.0'

Analyze Action

Analyze action currently accepts the following config inputs:

Config file - filtering and exceptions

Filters and exceptions can be applied to the report to create tailored insights, reduce false positives, and highlight critical information. Since Falco runs under the hood, you can easily leverage Falco conditions to add exceptions and filters.

We currently accept filters on:

• outbound_connections
• written_files
• processes

By default, this action applies exceptions specified in the filters.config file. You can override default filters by providing a custom file to the action.

Example

{
  "outbound_connections": [
    {
      "description": "Filter for connection from pythonist ",
      "condition": "proc.name in (pythonist, dragent)"
    }
  ],
  "written_files": [
    {
      "description": "Filter for file writes to github runner",
      "condition": "fd.name startswith '/home/runner/runners/' and proc.exepath endswith '/bin/Runner.Worker' and proc.pexepath endswith '/bin/Runner.Listener'"
    }
  ],
  "processes": [
    {
      "description": "Whitelisting noisy process names.",
      "condition": "proc.name in (sysdig, systemd-logind, systemd-network, systemd-resolve, systemd-udevd, linux-bench, journalctl, systemd-journal, systemd-cgroups)"
    }
  ]
}

Report Customization

The report produced by analyze action can be customized using the following inputs:

External Dependencies

Analyze mode currently supports two main external dependencies:

• OpenAI - Using OpenAI you can generate an understanble summary report and customise it on your needs.
• VirusTotal - Using VirusTotal you can get the reputation of IPs and Hashes found during the run

Analyze action currently accepts the following inputs for external dependencies:

Example

    steps:
    - name: Analyze
      uses: falcosecurity/falco-actions/analyze@<commit-sha>
      with:
        falco-version: '0.39.0'
        openai-user-prompt: "Pls add remediation steps"
        openai-model: "gpt-3.5-turbo"
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        VT_API_KEY: ${{ secrets.VT_API_KEY }}

Join the Community

To get involved with The Falco Project, please visit the community repository to find out more.

How to reach out?

• Join the #falco channel on the Kubernetes Slack
• Join the Falco mailing list

Reporting security vulnerabilities

Please report security vulnerabilities following the community process documented here.

License Terms

This project is licensed to you under the Apache 2.0 open source license.