---
Title: "Extend Falco inputs by creating a Plugin: Register the plugin"
Date: 2022-03-02
Author: Thomas Labarussias
slug: extend-falco-inputs-with-a-plugin-register
---

> This post is is part of a series of articles about `How to develop Falco plugins`. It's addressed to anybody who would like to understand how plugins are written and want to contribute.
> See other articles:
> * [Extend Falco inputs by creating a Plugin: the basics]({{< ref "/blog/extend-falco-inputs-with-a-plugin-the-basics" >}})
> * [Extend Falco inputs by creating a Plugin: Distribute the plugin]({{< ref "/blog/extend-falco-inputs-with-a-plugin-distribute" >}})

- [Introduction](#introduction)
- [The registry](#the-registry)
- [Details of your plugin](#details-of-your-plugin)
  - [License](#license)
  - [ID](#id)
  - [Name](#name)
  - [Fields](#fields)
- [Propose your Plugin](#propose-your-plugin)
- [Share with the community](#share-with-the-community)
- [Conclusion](#conclusion)

# Introduction

In the previous [post]({{< ref "/blog/extend-falco-inputs-with-a-plugin-the-basics" >}}) article we covered all the basics to develop a plugin. In this article, we'll focus on the steps to register and allow the community to use it.

> The registration is mandatory for `source` plugins and optional (but still recommend) for `extractor` plugins. This blog will talk about the registration of `source` plugins.

# The registry

At the moment, what we call the `Plugin Registry` is a git repository that centralizes all available plugins through a [`yaml` file](https://github.com/falcosecurity/plugins/blob/master/registry.yaml).

The table in the [README](https://github.com/falcosecurity/plugins#registered-plugins) is auto generated by aforementioned registry:

| ID  | Name                                                                                      | Event Source     | Description                                                                                                                                                                                                                   | Info                                                                                |
| --- | ----------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 2   | [cloudtrail](https://github.com/~~falcosecurity~~/plugins/tree/master/plugins/cloudtrail) | `aws_cloudtrail` | Reads Cloudtrail JSON logs from files/S3 and injects as events                                                                                                                                                                | Authors: [The Falco Authors](https://falco.org/community) <br/> License: Apache-2.0 |
| 3   | [dummy](https://github.com/falcosecurity/plugins/tree/master/plugins/dummy)               | `dummy`          | Reference plugin used to document interface                                                                                                                                                                                   | Authors: [The Falco Authors](https://falco.org/community) <br/> License: Apache-2.0 |
| 4   | [dummy_c](https://github.com/falcosecurity/plugins/tree/master/plugins/dummy_c)           | `dummy_c`        | Like Dummy, but written in C++                                                                                                                                                                                                | Authors: [The Falco Authors](https://falco.org/community) <br/> License: Apache-2.0 |
| 999 | test                                                                                      | `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 <br/> 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, but also complete all fields for `plugins` section of [registry.yaml](https://github.com/falcosecurity/plugins/blob/master/registry.yaml), like:

```yaml
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/](https://choosealicense.com/) for help. Most of 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`, that can be shared across different plugins (eg, for k8s audit logs, we may have different 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, you must 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, you can submit your plugin to registration:
* fork https://github.com/falcosecurity/plugins
* update [falcosecurity/plugins/edit/master/registry.yaml](https://github.com/falcosecurity/plugins/edit/master/registry.yaml) for adding your plugin in the `plugins` section
* submit your PR to [falcosecurity/plugins](https://github.com/falcosecurity/plugins)

> Following our [`Contributing` Guide](https://github.com/falcosecurity/.github/blob/master/CONTRIBUTING.md) your commits must be signed-off.

You can find more information [here](https://github.com/falcosecurity/plugins#registering-a-new-plugin).

# Share with the community

By sharing your idea and code with the community, you will have direct feedbacks. Don't hesitate to share your work in the Slack kubernetes#falco before submitting your PR too!

# Conclusion

You should now be able to propose your plugin to the community and have feedbacks about it. The following posts will describe more advanced use-cases like events from Cloud Services. Stay tuned!

---

You can find us in the [Falco community](https://github.com/falcosecurity/community). Please feel free to reach out to us for any questions, suggestions, or even for a friendly chat!

If you would like to find out more about Falco:

* Get started in [Falco.org](http://falco.org/)
* [Plugin Documentation](https://falco.org/docs/plugins/)
* [Plugin Developer Guide](https://falco.org/docs/plugins/developers-guide/)
* [Plugin registry](https://github.com/falcosecurity/plugins) 
* Check out the [Falco project in GitHub](https://github.com/falcosecurity/falco)
* Get involved in the [Falco community](https://falco.org/community/)
* Meet the maintainers on the [Falco Slack](https://kubernetes.slack.com/messages/falco)
* Follow [@falco_org on Twitter](https://twitter.com/falco_org)