How to register a plugin

How to register a plugin


In this article, we'll focus on the steps to register and allow the community to use it.

The registry

At the moment, what we call the Plugin Registry is a git repository that centralizes all available plugins through a yaml file.

The table in the README is auto generated by aforementioned registry:

IDNameEvent SourceDescriptionInfo
2cloudtrailaws_cloudtrailReads Cloudtrail JSON logs from files/S3 and injects as eventsAuthors: The Falco Authors
License: Apache-2.0
3dummydummyReference plugin used to document interfaceAuthors: The Falco Authors
License: Apache-2.0
4dummy_cdummy_cLike Dummy, but written in C++Authors: The Falco Authors
License: Apache-2.0
999testtestThis 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 IDAuthors: N/A
License: N/A

Details of your plugin

In this section, we'll describe the key elements to get your plugin allowed to register.

The registration needs you to create a nice README for your plugin and complete all fields for the plugins section of registry.yaml, like:

      - id: 2
        source: aws_cloudtrail
        name: cloudtrail
        description: Reads Cloudtrail JSON logs from files/S3 and injects as events
        authors: The Falco Authors
        license: Apache-2.0


You're free to choose the open source license you want, you can check for help. Most of the current plugins are under Apache License 2.0.


Every source plugin requires its own unique plugin event ID to interoperate with Falco and the other plugins. This ID is used in the following ways:

  • It is stored inside in-memory event objects and used to identify the associated plugin that injected the event.
  • It is stored in capture files and used to recreate in-memory event objects when reading capture files.

It must be unique to ensure that events written by a given plugin will be properly associated with that plugin (and its event sources, see below).


Each plugin in the registry must have its own name and can be different from event source, which can be shared across multiple plugins (e.g., for k8s audit logs, there might be several plugins but only one type of event source).

The name should match this regular expression ^[a-z]+[a-z0-9_]*$.


The fields are used for conditions in rules. Describe the available fields of your plugin in the README.

For example:

docker.statusstringStatus of the event
docker.idstringID of the event
docker.fromstringFrom of the event (deprecated)
docker.typestringType of the event
docker.actionstringAction of the event
docker.stack.namespacestringStack Namespace

Propose your Plugin

Once you're ready, submit your plugin for registration:

Following our Contributing Guide your commits must be signed-off.

You can find more information here.