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:

Input	Description	Type	Required	Default
`mode`	Start action with a mode. Can be live or analyze	choice	false	live
`falco-version`	Falco version to use	string	false	latest
`config-file`	Start action with a config file (analyze mode only)	string	false	src/syscall_ignore.config
`custom-rule-file`	Custom rule file	string	false	(empty)
`verbose`	Enable verbose logs	boolean	false	false

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:

Input	Description	Type	Required	Default
`mode`	Start action with a mode. Can be live or analyze	choice	false	live
`verbose`	Enable verbose logs	boolean	false	false

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:

Input	Description	Type	Required	Default
`custom-rule-file`	Custom rule file	string	false	(empty)
`falco-version`	Falco version to use	string	false	latest
`filters-config`	Filter configuration file	string	false	src/filters.config

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:

Input	Description	Type	Required	Default
`extract-connections`	Extract connections	boolean	false	true
`extract-processes`	Extract processes	boolean	false	true
`extract-dns`	Extract DNS	boolean	false	true
`extract-containers`	Extract containers	boolean	false	true
`extract-written-files`	Extract written files	boolean	false	false
`extract-chisels`	Extract chisels	boolean	false	false
`extract-hashes`	Extract hashes	boolean	false	false

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:

Input	Description	Type	Required	Default
`openai-model`	OpenAI model to use for summary	string	false	gpt-3.5-turbo
`openai-user-prompt`	Message to send to OpenAI	string	false	(empty)

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Falco Actions

Live mode

Example

Start action

Config file - syscall filtering

Stop action

Analyze mode

Example

Analyze Action

Config file - filtering and exceptions

Example

Report Customization

External Dependencies

Example

Join the Community

Reporting security vulnerabilities

License Terms

Files

README.md

Latest commit

History

README.md

File metadata and controls

Falco Actions

Live mode

Example

Start action

Config file - syscall filtering

Stop action

Analyze mode

Example

Analyze Action

Config file - filtering and exceptions

Example

Report Customization

External Dependencies

Example

Join the Community

Reporting security vulnerabilities

License Terms