How to register a plugin

How to register a plugin in the Falco Plugin Registry

Plugin Registry

The registry is a GitHub repository that provides metadata and information about all plugins recognized by The Falco Project. It includes plugins hosted within this repository as well as those located in other repositories. These plugins are developed for Falco and shared with the community.

Registering your plugin

In this section, we’ll outline the key steps to get your plugin registered successfully.

To complete the registration process, you’ll need to:

Create a clear and well-structured README for your plugin.
Fill in all the required fields in the plugins section of the registry.yaml file, like in the below example.

plugins:
    source:
      - id: 2
        source: aws_cloudtrail
        name: cloudtrail
        description: Reads Cloudtrail JSON logs from files/S3 and injects as events
        authors: The Falco Authors
        contact: https://falco.org/community
        url: https://github.com/falcosecurity/plugins/tree/master/plugins/cloudtrail
        license: Apache-2.0

License

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

ID

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).

Name

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_]*$.

Fields

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

For example:

Name	Type	Description
`docker.status`	string	Status of the event
`docker.id`	string	ID of the event
`docker.from`	string	From of the event (deprecated)
`docker.type`	string	Type of the event
`docker.action`	string	Action of the event
`docker.stack.namespace`	string	Stack Namespace

Propose your Plugin

Once you're ready, follow these steps to submit your plugin for registration:

Fork the falcosecurity/plugins repository.
Update the registry.yaml file by adding your plugin to the plugins section.
Make sure to follow our Contributing Guide, e.g. all commits must be signed-off.
Submit a Pull Request (PR) to the falcosecurity/plugins repository.

For more details, check out the plugin registration documentation.

Was this page helpful?

Let us know! You feedback will help us to improve the content and to stay in touch with our users.

You are viewing documentation for Falco version: v0.41.3