Note: The plugin system is a new feature introduced since Falco 0.31.0. You can find more detail in the original proposal document.
This repository contains the Plugin Registry and the plugins officially maintained by the Falcosecurity organization. Plugins can be used to extend Falco and of applications using Falcosecurity libs. Please refer to the official documentation to better understand the plugin system's concepts and architecture.
The Registry contains metadata and information about every plugin known and recognized by the Falcosecurity organization. It lists plugins hosted either in this repository or in other repositories. These plugins are developed for Falco and made available to the community. Check out the sections below to know how to register your plugins and see plugins currently contained in the registry.
Registering your plugin inside the registry helps ensure that some technical constraints are respected, such as that a given ID is used by exactly one plugin with event source capability and allows plugin authors to coordinate about event source formats. Moreover, this is a great way to share your plugin project with the community and engage with it, thus gaining new users and increasing its visibility. We encourage you to register your plugin in this registry before publishing it. You can add your plugins in this registry regardless of where its source code is hosted (there's a url field for this specifically).
The registration process involves adding an entry about your plugin inside the registry.yaml file by creating a Pull Request in this repository. Please be mindful of a few constraints that are automatically checked and required for your plugin to be accepted:
- The
namefield is mandatory and must be unique across all the plugins in the registry - (Sourcing Capability Only) The
idfield is mandatory and must be unique in the registry across all the plugins with event source capability- See docs/plugin-ids.md for more information about plugin IDs
- The plugin
namemust match this regular expression:^[a-z]+[a-z0-9-_\-]*$(however, its not recommended to use_in the name, unless you are trying to match the name of a source or for particular reasons) - The
source(Sourcing Capability Only) andsources(Extraction Capability Only) must match this regular expression:^[a-z]+[a-z0-9_]*$ - The
urlfield should point to the plugin source code - The
rules_urlfield should point to the default ruleset, if any
For reference, here's an example of an entry for a plugin with both event sourcing and field extraction capabilities:
- name: k8saudit
description: ...
authors: ...
contact: ...
maintainers:
- name: The Falco Authors
email: cncf-falco-dev@lists.cncf.io
keywords:
- audit
- audit-log
- audit-events
- kubernetes
url: https://github.com/falcosecurity/plugins/tree/main/plugins/k8saudit
rules_url: https://github.com/falcosecurity/plugins/tree/main/plugins/k8saudit/rules
url: ...
license: ...
capabilities:
sourcing:
supported: true
id: 2
source: k8s_audit
extraction:
supported: trueYou can find the full registry specification here: (coming soon...)
The tables below list all the plugins currently registered. The tables are automatically generated from the registry.yaml file.
| Name | Capabilities | Description |
|---|---|---|
| plugin-id-zero-value | Event Sourcing ID: 0 `` |
This ID is reserved for particular purposes and cannot be registered. A plugin author should not use this ID unless specified by the documentation. Authors: N/A License: N/A |
| k8saudit | Event Sourcing ID: 1 k8s_audit Field Extraction k8s_audit |
Read Kubernetes Audit Events and monitor Kubernetes Clusters Authors: The Falco Authors License: Apache-2.0 |
| cloudtrail | Event Sourcing ID: 2 aws_cloudtrail Field Extraction aws_cloudtrail |
Reads Cloudtrail JSON logs from files/S3 and injects as events Authors: The Falco Authors License: Apache-2.0 |
| json | Field Extraction All Sources |
Extract values from any JSON payload Authors: The Falco Authors License: Apache-2.0 |
| dummy | Event Sourcing ID: 3 dummy Field Extraction dummy |
Reference plugin used to document interface Authors: The Falco Authors License: Apache-2.0 |
| dummy_c | Event Sourcing ID: 4 dummy_c Field Extraction dummy_c |
Like dummy, but written in C++ Authors: The Falco Authors License: Apache-2.0 |
| docker | Event Sourcing ID: 5 docker Field Extraction docker |
Docker Events Authors: Thomas Labarussias License: Apache-2.0 |
| seccompagent | Event Sourcing ID: 6 seccompagent Field Extraction seccompagent |
Seccomp Agent Events Authors: Alban Crequy License: Apache-2.0 |
| okta | Event Sourcing ID: 7 okta Field Extraction okta |
Okta Log Events Authors: The Falco Authors License: Apache-2.0 |
| github | Event Sourcing ID: 8 github Field Extraction github |
Github Webhook Events Authors: The Falco Authors License: Apache-2.0 |
| k8saudit-eks | Event Sourcing ID: 9 k8s_audit Field Extraction k8s_audit |
Read Kubernetes Audit Events from AWS EKS Clusters Authors: The Falco Authors License: Apache-2.0 |
| nomad | Event Sourcing ID: 10 nomad Field Extraction nomad |
Read Hashicorp Nomad Events Stream Authors: Alberto Llamas License: Apache-2.0 |
| dnscollector | Event Sourcing ID: 11 dnscollector Field Extraction dnscollector |
DNS Collector Events Authors: Daniel Moloney License: Apache-2.0 |
| gcpaudit | Event Sourcing ID: 12 gcp_auditlog Field Extraction gcp_auditlog |
Read GCP Audit Logs Authors: The Falco Authors License: Apache-2.0 |
| syslogsrv | Event Sourcing ID: 13 syslogsrv Field Extraction syslogsrv |
Syslog Server Events Authors: Maksim Nabokikh License: Apache-2.0 |
| salesforce | Event Sourcing ID: 14 salesforce Field Extraction salesforce |
Falco plugin providing basic runtime threat detection and auditing logging for Salesforce Authors: Andy License: Apache-2.0 |
| box | Event Sourcing ID: 15 box Field Extraction box |
Falco plugin providing basic runtime threat detection and auditing logging for Box Authors: Andy License: Apache-2.0 |
| test | Event Sourcing ID: 999 test |
This ID is reserved for source plugin development. Any plugin author can use this ID, but authors can expect events from other developers with this ID. After development is complete, the author should request an actual ID Authors: N/A License: N/A |
| k8smeta | Field Extraction syscall |
Enriche Falco syscall flow with Kubernetes Metadata Authors: The Falco Authors License: Apache-2.0 |
| k8saudit-gke | Event Sourcing ID: 16 k8s_audit Field Extraction k8s_audit |
Read Kubernetes Audit Events from GKE Clusters Authors: The Falco Authors License: Apache-2.0 |
| journald | Event Sourcing ID: 17 journal Field Extraction journal |
Read Journald events into Falco Authors: Grzegorz Nosek License: Apache-2.0 |
| kafka | Event Sourcing ID: 18 kafka |
Read events from Kafka topics into Falco Authors: Hunter Madison License: Apache-2.0 |
| gitlab | Event Sourcing ID: 19 gitlab Field Extraction gitlab |
Falco plugin providing basic runtime threat detection and auditing logging for GitLab Authors: Andy License: Apache-2.0 |
| keycloak | Event Sourcing ID: 20 keycloak Field Extraction keycloak |
Falco plugin for sourcing and extracting Keycloak user/admin events Authors: Mattia Forcellese License: Apache-2.0 |
Another purpose of this repository is to host and maintain the plugins owned by the Falcosecurity organization. Each plugin is a standalone project and has its own directory, and they are all inside the plugins folder.
The main branch contains the most up-to-date state of development, and each plugin is regularly released. Please check our Release Process to know how plugins are released and how artifacts are distributed. Dev builds are published each time a Pull Request gets merged into main, whereas stable builds are released and published only when a new release gets tagged. You can find the published artifacts at https://download.falco.org/?prefix=plugins.
If you wish to contribute your plugin to the Falcosecurity organization, you just need to open a Pull Request to add it inside the plugins folder and to add it inside the registry. In order to be hosted in this repository, plugins must be licensed under the Apache 2.0 License.
If you want to help and wish to contribute, please review our contribution guidelines. Code contributions are always encouraged and welcome!
This project is licensed to you under the Apache 2.0 Open Source License.