Falco – Plugins Developer Guide

Docs: How to develop a plugin

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

This section explains how to develop a plugin from scratch with the official Go SDK.

We'll create a plugin for the docker events from a local docker daemon. It is a basic example of an event stream with a basic format and without specific authentication.

To know more about the available feature of the Go SDK and how to see use, you can refer to this page.

Awaited result

At the end, your plugin will allow you to get that kind of alerts:

2022-02-08T10:58:56.370816183+01:00 container create e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)
2022-02-08T10:58:56.371818906+01:00 container attach e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)
2022-02-08T10:58:56.482094215+01:00 network connect 5864a44bccca4e0963dfe9c3087919bf8f8e5c3aa7db33dd6d9ae7138c5ee3f3 (container=e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6, name=bridge, type=bridge)
2022-02-08T10:58:56.804166856+01:00 container start e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)
2022-02-08T10:58:56.831912702+01:00 container die e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (exitCode=0, image=alpine, name=confident_kirch)
2022-02-08T10:58:57.072125878+01:00 network disconnect 5864a44bccca4e0963dfe9c3087919bf8f8e5c3aa7db33dd6d9ae7138c5ee3f3 (container=e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6, name=bridge, type=bridge)
2022-02-08T10:58:57.132390363+01:00 container destroy e327f1fa52a90d79421e416aed60e6de6872231f31101a1cc63401e90cef4bd6 (image=alpine, name=confident_kirch)

The Docker SDK

For reducing the complexity to communicate with the docker daemon, we'll use the official docker sdk.

Requirements

The only requirements for this examples are:

a docker daemon running in your local system
falco >=0.35 installed in your local system
go >= 1.19

Code Organization

To simplify contributions and keep a consistency between plugins, we propose a specific organization for the repositories of plugins:

.
├── LICENSE
├── Makefile
├── README.md
├──
├── go.mod
├── go.sum
├── pkg
│   └── docker.go
├── plugin
│   └── main.go
└── rules
 └── docker_rules.yaml

The directories:

pkg: Contains all modules for our plugin, we use a pkg folder because they might be imported and used by other plugins.
plugin: Contains the main.go of our plugin.
rules: Contains one or more .yaml files with default rules for the plugin.

The files:

LICENSE: The license file, most of the plugins are under Apache License 2.0.
README: The README, see in the repository for an example.
Makefile: Allows to easily build and install the plugin, see in the repository for an example.
falco.yaml: (optional) An example file with the minimal configuration to use the plugin.
rules/docker_rules.yaml: An example rule file, its name must respect <plugin_name>_rules.yaml.
go.mod, go.sum: Classic go module files.

The plugin codebase

plugin/main.go

This is the entrypoint of our plugin.

This is where we declare the details of our plugin:

package main

import (
 docker "github.com/Issif/docker-plugin/pkg"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/extractor"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"
)

const (
 PluginID uint32 = 5
 PluginName = "docker"
 PluginDescription = "Docker Events"
 PluginContact = "github.com/falcosecurity/plugins/"
 PluginVersion = "0.2.0"
 PluginEventSource = "docker"
)

func init() {
 plugins.SetFactory(func() plugins.Plugin {
 p := &docker.Plugin{}
 p.SetInfo(
 PluginID,
 PluginName,
 PluginDescription,
 PluginContact,
 PluginVersion,
 PluginEventSource,
 )
 extractor.Register(p)
 source.Register(p)
 return p
 })
}

func main() {}

Few requirements:

PluginID (Sourcing Capability Only) The ID field is mandatory and must be unique in the registry across all the plugins with event source capability
PluginName: The name field is mandatory and must be unique across all the plugins in the registry. The plugin name must 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)
PluginEventSource: The source (Sourcing Capability Only) and sources (Extraction Capability Only) must match this regular expression: ^[a-z]+[a-z0-9_]*$

The imports

Despite basic Go modules, we'll have to import the different plugin-sdk-go modules (>= 0.5.0) and other modules we need for our plugin:

import (
 docker "github.com/Issif/docker-plugin/pkg"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/extractor"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"
)

We'll import these different components of plugin-sdk-go in almost every plugin we'll write. They're really convenient and provide a much easier way to deal with the Falco plugin framework.

The const

const (
 ID uint32 = 5
 Name = "docker"
 Description = "Docker Events"
 Contact = "github.com/Issif/docker-plugin"
 Version = "0.2.0"
 EventSource = "docker"
)

The const are used to declare all mandatory information of our plugin through the docker.SetInfo() method:

ID: Must be unique among all plugins, it's used by the framework in captures to know which plugin is the source of events. It's also important for avoiding collisions if you want to share your plugin in the registry, see the main repository for more details.
Name: The name of our plugin, will be used in plugins section of falco.yaml. The plugin name must 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).
Description: The description of our plugin.
Contact: A contact link, often a link to the repository.
Version: All plugins must be versioned for compatibility with Falco, the versioning must follow the semantic versioning.
EventSource: This represents the value we'll set in Falco rules for mapping, in our case, all rules we'll set will have source: docker. The source must match this regular expression: ^[a-z]+[a-z0-9_]*$.

The functions

`main()`

The main() function is mandatory for any go program, but because we'll build the plugin as a library for the Falco plugin framework which is written in C, we can let it empty.

// main is mandatory but empty, because the plugin will be used as C library by Falco plugin framework
func main() {}

`init()`

The init() function is used for registering our plugin to the Falco plugin framework, as a source and an extractor. We also use it to set the info of the plugin:

func init() {
 plugins.SetFactory(func() plugins.Plugin {
 p := &docker.Plugin{}
 p.SetInfo(
 ID,
 Name,
 Description,
 Contact,
 Version,
 EventSource,
 )
 extractor.Register(p)
 source.Register(p)
 return p
 })
}

The init() contains also some specific functions and methods:

plugins.SetFactory() is a method to register our plugin to the framework
SetInfo() is a method to set the details of our plugin before it's registered to the Falco plugin framework
source.Register() allows to declare our plugin as a source to the framework, ie, a plugin to collect events from a source
extractor.Register() allows to declare our plugin as an extractor to the framework, ie, a plugin to extract fields from an event

pkg/docker.go

The module used by our main.go, it can also be imported by other plugins, especially when it's an extractor.

package docker

import (
 "context"
 "encoding/json"
 "fmt"
 "io"
 "io/ioutil"

 "github.com/alecthomas/jsonschema"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"

 dockerTypes "github.com/docker/docker/api/types"
 dockerEvents "github.com/docker/docker/api/types/events"
 docker "github.com/moby/docker/client"
)

var (
 ID uint32
 Name string
 Description string
 Contact string
 Version string
 EventSource string
)

type PluginConfig struct {
 FlushInterval uint64 `json:"flushInterval" jsonschema:"description=Flush Interval in ms (Default: 30)"`
}

// Plugin represents our plugin
type Plugin struct {
 plugins.BasePlugin
 Config PluginConfig
 lastDockerEventMessage dockerEvents.Message
 lastDockerEventNum uint64
}

// setDefault is used to set default values before mapping with InitSchema()
func (p *PluginConfig) setDefault() {
 p.FlushInterval = 30
}

// SetInfo is used to set the Info of the plugin
func (p *Plugin) SetInfo(id uint32, name, description, contact, version, eventSource string) {
 ID = id
 Name = name
 Contact = contact
 Version = version
 EventSource = eventSource
}

// Info displays information of the plugin to Falco plugin framework
func (p *Plugin) Info() *plugins.Info {
 return &plugins.Info{
 ID: ID,
 Name: Name,
 Description: Description,
 Contact: Contact,
 Version: Version,
 EventSource: EventSource,
 }
}

// InitSchema map the configuration values with Plugin structure through JSONSchema tags
func (p *Plugin) InitSchema() *sdk.SchemaInfo {
 reflector := jsonschema.Reflector{
 RequiredFromJSONSchemaTags: true, // all properties are optional by default
 AllowAdditionalProperties: true, // unrecognized properties don't cause a parsing failures
 }
 if schema, err := reflector.Reflect(&PluginConfig{}).MarshalJSON(); err == nil {
 return &sdk.SchemaInfo{
 Schema: string(schema),
 }
 }
 return nil
}

// Init is called by the Falco plugin framework as first entry,
// we use it for setting default configuration values and mapping
// values from `init_config` (json format for this plugin)
func (p *Plugin) Init(config string) error {
 p.Config.setDefault()
 return json.Unmarshal([]byte(config), &p.Config)
}

// Fields exposes to Falco plugin framework all availables fields for this plugin
func (p *Plugin) Fields() []sdk.FieldEntry {
 return []sdk.FieldEntry{
 {Type: "string", Name: "docker.status", Desc: "Status of the event"},
 {Type: "string", Name: "docker.id", Desc: "ID of the event"},
 {Type: "string", Name: "docker.from", Desc: "From of the event (deprecated)"},
 {Type: "string", Name: "docker.type", Desc: "Type of the event"},
 {Type: "string", Name: "docker.action", Desc: "Action of the event"},
 {Type: "string", Name: "docker.stack.namespace", Desc: "Stack Namespace"},
 {Type: "string", Name: "docker.node.id", Desc: "Swarm Node ID"},
 {Type: "string", Name: "docker.swarm.task", Desc: "Swarm Task"},
 {Type: "string", Name: "docker.swarm.taskid", Desc: "Swarm Task ID"},
 {Type: "string", Name: "docker.swarm.taskname", Desc: "Swarm Task Name"},
 {Type: "string", Name: "docker.swarm.servicename", Desc: "Swarm Service Name"},
 {Type: "string", Name: "docker.node.statenew", Desc: "Node New State"},
 {Type: "string", Name: "docker.node.stateold", Desc: "Node Old State"},
 {Type: "string", Name: "docker.attributes.container", Desc: "Attribute Container"},
 {Type: "string", Name: "docker.attributes.image", Desc: "Attribute Image"},
 {Type: "string", Name: "docker.attributes.name", Desc: "Attribute Name"},
 {Type: "string", Name: "docker.attributes.type", Desc: "Attribute Type"},
 {Type: "string", Name: "docker.attributes.exitcode", Desc: "Attribute Exit Code"},
 {Type: "string", Name: "docker.attributes.signal", Desc: "Attribute Signal"},
 {Type: "string", Name: "docker.scope", Desc: "Scope"},
 }
}

// Extract allows Falco plugin framework to get values for all available fields
func (p *Plugin) Extract(req sdk.ExtractRequest, evt sdk.EventReader) error {
 msg := p.lastDockerEventMessage

 // For avoiding to Unmarshal the same message for each field to extract
 // we store it with its EventNum. When it's a new event with a new message, we
 // update the Plugin struct.
 if evt.EventNum() != p.lastDockerEventNum {
 rawData, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 fmt.Println(err.Error())
 return err
 }

 err = json.Unmarshal(rawData, &msg)
 if err != nil {
 return err
 }

 p.lastDockerEventMessage = msg
 p.lastDockerEventNum = evt.EventNum()
 }

 switch req.Field() {
 case "docker.status":
 req.SetValue(msg.Status)
 case "docker.id":
 req.SetValue(msg.ID)
 case "docker.from":
 req.SetValue(msg.From)
 case "docker.type":
 req.SetValue(msg.Type)
 case "docker.action":
 req.SetValue(msg.Action)
 case "docker.scope":
 req.SetValue(msg.Scope)
 case "docker.actor.id":
 req.SetValue(msg.Actor.ID)
 case "docker.stack.namespace":
 req.SetValue(msg.Actor.Attributes["com.docker.stack.namespace"])
 case "docker.swarm.task":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task"])
 case "docker.swarm.taskid":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.id"])
 case "docker.swarm.taskname":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.name"])
 case "docker.swarm.servicename":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.service.name"])
 case "docker.node.id":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.node.id"])
 case "docker.node.statenew":
 req.SetValue(msg.Actor.Attributes["state.new"])
 case "docker.node.stateold":
 req.SetValue(msg.Actor.Attributes["state.old"])
 case "docker.attributes.container":
 req.SetValue(msg.Actor.Attributes["container"])
 case "docker.attributes.image":
 req.SetValue(msg.Actor.Attributes["image"])
 case "docker.attributes.name":
 req.SetValue(msg.Actor.Attributes["name"])
 case "docker.attributes.type":
 req.SetValue(msg.Actor.Attributes["type"])
 default:
 return fmt.Errorf("no known field: %s", req.Field())
 }

 return nil
}

// Open is called by Falco plugin framework for opening a stream of events, we call that an instance
func (Plugin *Plugin) Open(params string) (source.Instance, error) {
 dclient, err := docker.NewClientWithOpts()
 if err != nil {
 return nil, err
 }

 eventC := make(chan source.PushEvent)
 ctx, cancel := context.WithCancel(context.Background())
 // launch an async worker that listens for Docker events and pushes them
 // to the event channel
 go func() {
 defer close(eventC)
 msgC, errC := dclient.Events(ctx, dockerTypes.EventsOptions{})
 var msg dockerEvents.Message
 var err error
 for {
 select {
 case msg = <-msgC:
 bytes, err := json.Marshal(msg)
 if err != nil {
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 eventC <- source.PushEvent{Data: bytes}
 case err = <-errC:
 if err == io.EOF {
 // map EOF to sdk.ErrEOF, which is recognized by the Go SDK
 err = sdk.ErrEOF
 }
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 }
 }()
 return source.NewPushInstance(eventC, source.WithInstanceClose(cancel))
}

// String represents the raw value of on event
// (not currently used by Falco plugin framework, only there for future usage)
func (Plugin *Plugin) String(in io.ReadSeeker) (string, error) {
 evtBytes, err := ioutil.ReadAll(in)
 if err != nil {
 return "", err
 }
 evtStr := string(evtBytes)
 return fmt.Sprintf("%v", evtStr), nil
}

The imports

Despite basic Go modules, we'll have to import the different modules from plugin-sdk-go and from Docker SDK to docker events:

import (
 "context"
 "encoding/json"
 "fmt"
 "io"
 "io/ioutil"

 "github.com/alecthomas/jsonschema"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins"
 "github.com/falcosecurity/plugin-sdk-go/pkg/sdk/plugins/source"

 dockerTypes "github.com/docker/docker/api/types"
 dockerEvents "github.com/docker/docker/api/types/events"
 docker "github.com/moby/docker/client"
)

The global variables

Global variables are declared and filled with the SetInfo() method called by the init() of the main.go. These variables are then used to declare the details of the plugin to Falco:

var (
 ID uint32
 Name string
 Description string
 Contact string
 Version string
 EventSource string
)

The structures

The structure to declare the plugin is mandatory and must respect the interface declared in the SDK:

type PluginConfig struct {
 FlushInterval uint64 `json:"flushInterval" jsonschema:"description=Flush Interval in ms (Default: 30)"`
}

// Plugin represents our plugin
type Plugin struct {
 plugins.BasePlugin
 Config PluginConfig
 lastDockerEventMessage dockerEvents.Message
 lastDockerEventNum uint64
}

Plugin represents our plugin that will be loaded by the framework. It contains some fields:

plugins.BasePlugin: Allows to respect the Plugin interface of the SDK.
Config: Contains the configuration of our plugin, represented by the PluginConfig structure.
lastDockerEventMessage: Contains the result of the last unmarshalled event.
lastDockerEventNum: Contains the number of the unmarshalled event, by comparing it, we avoid to unmarshal the same event several times.

PluginConfig represents the configuration of our plugin, we'll use the module alecthomas/jsonschema to map the content of init_config from the plugin section of falco.yaml and check its validity:

plugins:
 - name: docker
 library_path: /etc/falco/audit/libdocker.so
 init_config: '{"flushinterval": 10}'
 open_params: ''

The functions and methods

`SetInfo()`

It's used to set the global variables which represent the details of our plugin, this method is called by the init() of the main.go:

// SetInfo is used to set the Info of the plugin
func (p *Plugin) SetInfo(id uint32, name, description, contact, version, eventSource string) {
 ID = id
 Name = name
 Contact = contact
 Version = version
 EventSource = eventSource
}

`Info()`

This method is mandatory and all plugins must respect that. It allows the Falco plugin framework to have all intel about the plugin itself, we use the global variables and the SetInfo() method to set the values:

// Info displays information of the plugin to Falco plugin framework
func (p *Plugin) Info() *plugins.Info {
 return &plugins.Info{
 ID: ID,
 Name: Name,
 Description: Description,
 Contact: Contact,
 Version: Version,
 EventSource: EventSource,
 }
}

`Init()`

This method (different from the function init()) will be the first one called by the Falco plugin framework, we use setDefault() to set the default values of the config. In our case, these default values are overridden by the values from init_config:.

// Init is called by the Falco plugin framework as first entry,
// we use it for setting default configuration values and mapping
// values from `init_config` (json format for this plugin)
func (p *Plugin) Init(config string) error {
 p.Config.setDefault()
 return json.Unmarshal([]byte(config), &p.Config)
}

`InitSchema()`

InitSchema() and the jsonschema tags from the fields of PluginConfig struct are used to check the validity of the content of init_config from falco.yaml.

// InitSchema map the configuration values with Plugin structure through JSONSchema tags
func (p *Plugin) InitSchema() *sdk.SchemaInfo {
 reflector := jsonschema.Reflector{
 RequiredFromJSONSchemaTags: true, // all properties are optional by default
 AllowAdditionalProperties: true, // unrecognized properties don't cause a parsing failures
 }
 if schema, err := reflector.Reflect(&PluginConfig{}).MarshalJSON(); err == nil {
 return &sdk.SchemaInfo{
 Schema: string(schema),
 }
 }
 return nil
}

It uses a json schema reflector, see jsonschema for more details about how it works.

`Fields()`

This method declares to the Falco plugin framework all fields that will be available for the rules, with their names and their types.

// Fields exposes to Falco plugin framework all availables fields for this plugin
func (dockerPlugin *DockerPlugin) Fields() []sdk.FieldEntry {
 return []sdk.FieldEntry{
 {Type: "string", Name: "docker.status", Desc: "Status"},
 {Type: "string", Name: "docker.id", Desc: "ID"},
 {Type: "string", Name: "docker.from", Desc: "From"},
 {Type: "string", Name: "docker.type", Desc: "Type"},
 {Type: "string", Name: "docker.action", Desc: "Action"},
 {Type: "string", Name: "docker.stack.namespace", Desc: "Stack Namespace"},
 {Type: "string", Name: "docker.node.id", Desc: "Swarm Node ID"},
 {Type: "string", Name: "docker.swarm.task", Desc: "Swarm Task"},
 {Type: "string", Name: "docker.swarm.taskid", Desc: "Swarm Task ID"},
 {Type: "string", Name: "docker.swarm.taskname", Desc: "Swarm Task Name"},
 {Type: "string", Name: "docker.swarm.servicename", Desc: "Swarm Service Name"},
 {Type: "string", Name: "docker.node.statenew", Desc: "Node New State"},
 {Type: "string", Name: "docker.node.stateold", Desc: "Node Old State"},
 {Type: "string", Name: "docker.attributes.container", Desc: "Attribute Container"},
 {Type: "string", Name: "docker.attributes.image", Desc: "Attribute Image"},
 {Type: "string", Name: "docker.attributes.name", Desc: "Attribute Name"},
 {Type: "string", Name: "docker.attributes.type", Desc: "Attribute Type"},
 {Type: "string", Name: "docker.attributes.exitcode", Desc: "Attribute Exit Code"},
 {Type: "string", Name: "docker.attributes.signal", Desc: "Attribute Signal"},
 {Type: "string", Name: "docker.scope", Desc: "Scope"},
 }
}

`String()`

Even if this method is mandatory, it's not used by Falco for now but must be set up for future usage. It simply retrieves the events, it can be in JSON or any format as long it contains the whole content of the source event.

// String represents the raw value of on event
// (not currently used by Falco plugin framework, only there for future usage)
func (dockerPlugin *DockerPlugin) String(in io.ReadSeeker) (string, error) {
 evtBytes, err := ioutil.ReadAll(in)
 if err != nil {
 return "", err
 }
 evtStr := string(evtBytes)

 return fmt.Sprintf("%v", evtStr), nil
}

`Extract()`

This method is called by the Falco plugin framework for getting the values of fields:

// Extract allows Falco plugin framework to get values for all available fields
func (p *Plugin) Extract(req sdk.ExtractRequest, evt sdk.EventReader) error {
 msg := p.lastDockerEventMessage

 // For avoiding to Unmarshal the same message for each field to extract
 // we store it with its EventNum. When it's a new event with a new message, we
 // update the Plugin struct.
 if evt.EventNum() != p.lastDockerEventNum {
 rawData, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 fmt.Println(err.Error())
 return err
 }

 err = json.Unmarshal(rawData, &msg)
 if err != nil {
 return err
 }

 p.lastDockerEventMessage = msg
 p.lastDockerEventNum = evt.EventNum()
 }

 switch req.Field() {
 case "docker.status":
 req.SetValue(msg.Status)
 case "docker.id":
 req.SetValue(msg.ID)
 case "docker.from":
 req.SetValue(msg.From)
 case "docker.type":
 req.SetValue(msg.Type)
 case "docker.action":
 req.SetValue(msg.Action)
 case "docker.scope":
 req.SetValue(msg.Scope)
 case "docker.actor.id":
 req.SetValue(msg.Actor.ID)
 case "docker.stack.namespace":
 req.SetValue(msg.Actor.Attributes["com.docker.stack.namespace"])
 case "docker.swarm.task":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task"])
 case "docker.swarm.taskid":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.id"])
 case "docker.swarm.taskname":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.task.name"])
 case "docker.swarm.servicename":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.service.name"])
 case "docker.node.id":
 req.SetValue(msg.Actor.Attributes["com.docker.swarm.node.id"])
 case "docker.node.statenew":
 req.SetValue(msg.Actor.Attributes["state.new"])
 case "docker.node.stateold":
 req.SetValue(msg.Actor.Attributes["state.old"])
 case "docker.attributes.container":
 req.SetValue(msg.Actor.Attributes["container"])
 case "docker.attributes.image":
 req.SetValue(msg.Actor.Attributes["image"])
 case "docker.attributes.name":
 req.SetValue(msg.Actor.Attributes["name"])
 case "docker.attributes.type":
 req.SetValue(msg.Actor.Attributes["type"])
 default:
 return fmt.Errorf("no known field: %s", req.Field())
 }

 return nil
}

Try to not overlap the fields created by other plugins, for eg, in this example we can use docker. prefix because Falco libs use container. fields which are more generic, so we've not a conflict.

For this plugin, we use the modules provided by the Docker SDK, all retrieved events will be unmarshaled into the events.Message struct which simplifies the mapping and the extraction of fields.

To avoid to unmarshall for each field extraction the same message and impact the performances, we store the number (=~ event ID) and the result of the last unmarshalled message. When the number change, it means it's not the same event and we can unmarshall its message and store it with its number.

 msg := p.lastDockerEventMessage

 // For avoiding to Unmarshal the same message for each field to extract
 // we store it with its EventNum. When it's a new event with a new message, we
 // update the Plugin struct.
 if evt.EventNum() != p.lastDockerEventNum {
 rawData, err := ioutil.ReadAll(evt.Reader())
 if err != nil {
 fmt.Println(err.Error())
 return err
 }

 err = json.Unmarshal(rawData, &msg)
 if err != nil {
 return err
 }

 p.lastDockerEventMessage = msg
 p.lastDockerEventNum = evt.EventNum()
 }

`Open()`

This methods is used by the Falco plugin framework for opening a new stream of events, what is called an instance (source.Instance). The current implementation creates only one instance per plugin but it's possible in future that same plugin allows to open several streams, and so several instances at once.

To simplify the creation of this source.Instance, the Go SDK provides two easy functions, see the docs:

source.NewPullInstance: for when the event source can be implemented sequentially and the time required to generate a sequence of event is deterministic, eg: periodic calls to an external API
source.NewPushInstance: for when the event source can be suspensive and there is no time guarantee regarding when an event gets produced, eg: we wait a webhook from an external service

For collecting events from docker, we'll use source.NewPushInstance as the docker SDK creates a channel and sends the events into when they happened.

// Open is called by Falco plugin framework for opening a stream of events, we call that an instance
func (Plugin *Plugin) Open(params string) (source.Instance, error) {
 dclient, err := docker.NewClientWithOpts()
 if err != nil {
 return nil, err
 }

 eventC := make(chan source.PushEvent)
 ctx, cancel := context.WithCancel(context.Background())
 // launch an async worker that listens for Docker events and pushes them
 // to the event channel
 go func() {
 defer close(eventC)
 msgC, errC := dclient.Events(ctx, dockerTypes.EventsOptions{})
 var msg dockerEvents.Message
 var err error
 for {
 select {
 case msg = <-msgC:
 bytes, err := json.Marshal(msg)
 if err != nil {
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 eventC <- source.PushEvent{Data: bytes}
 case err = <-errC:
 if err == io.EOF {
 // map EOF to sdk.ErrEOF, which is recognized by the Go SDK
 err = sdk.ErrEOF
 }
 eventC <- source.PushEvent{Err: err}
 // errors are blocking, so we can stop here
 return
 }
 }
 }()
 return source.NewPushInstance(eventC, source.WithInstanceClose(cancel))
}

We'll not describe with details the docker relative part, see the documentation of the Docker SDK for more info. You just have to know it creates a channel to receive the events from the engine and we use same context than the whole plugin.

Here's the most important things to notice:

eventC := make(chan source.PushEvent): we create a channel, it will be used by the instance to listen incoming events, we'll push into it the events from the docker client
ctx, cancel := context.WithCancel(context.Background()): we create a context, and more important, a Done channel for this context
eventC <- source.PushEvent{Data: bytes}: this is how to push an event to the instance
return source.NewPushInstance(eventC, source.WithInstanceClose(cancel)): the Open() method must return a source.Instance, and source.NewPushInstance() requires a channel where the events will pushed and may have optional settings, in our case, we pass also the Done channel of the context with the source.WithInstanceClose() function

Passing to the instance the same Done channel than the docker client uses, allows to correctly stop the plugin when we ask Falco to stop (CTRL+C or systemctl stop falco).

Build the plugin

The plugin is built as a c-shared library, it means a .so:

go build -buildmode=c-shared -o libdocker.so

If you use make from the repository:

make build

Installation

The plugins are commonly installed in /usr/share/falco/plugins, just move the libdocker.so you built or run make install.

Makefile

To simplify the build and the installation of the plugin, we can use a Makefile like this one:

SHELL=/bin/bash -o pipefail
GO ?= go

NAME := docker
OUTPUT := lib$(NAME).so
DESTDIR := /usr/share/falco/plugins

ifeq ($(DEBUG), 1)
 GODEBUGFLAGS= GODEBUG=cgocheck=2
else
 GODEBUGFLAGS= GODEBUG=cgocheck=0
endif

all: build

clean:
 @rm -f lib$(NAME).so

build: clean
 @$(GODEBUGFLAGS) $(GO) build -buildmode=c-shared -buildvcs=false -o $(OUTPUT) ./plugin

install: build
 mv $(OUTPUT) $(DESTDIR)/

This makefile will work for any plugin, just change the NAME variable.

Configuration

Now we have our plugin, we must declare it to Falco in falco.yaml:

plugins:
 - name: docker
 library_path: /usr/share/falco/plugins/libdocker.so
 init_config: '{"flushinterval": 1}'

load_plugins: [docker]

stdout_output:
 enabled: true

For more details about this configuration, see how to load and configure a plugin.

Rules

We create a simple rule, for checking that the fields and source work as expected:

- rule: Container status changed
 desc: Container status changed
 condition: docker.status in (create,start,die)
 output: status=%docker.status from=%docker.from type=%docker.type action=%docker.action name=%docker.attributes.name
 priority: DEBUG
 source: docker
 tags: [docker]

Test and Results

Let's run Falco with our configuration and rules files:

falco -c falco.yaml -r rules/docker_rules.yaml

17:17:24.008405000: Debug status=create from=alpine type=container action=create name=bold_keller
17:17:24.008953000: Debug status=start from=alpine type=container action=start name=bold_keller
17:17:24.009076000: Debug status=die from=alpine type=container action=die name=bold_keller

Events detected: 3
Rule counts by severity:
 DEBUG: 3
Triggered rules by rule name:
 Container status changed: 3
Syscall event drop monitoring:
 - event drop detected: 0 occurrences
 - num times actions taken: 0

It works!

Docs: Plugins SDKs

Mon, 01 Jan 0001 00:00:00 +0000

Plugins SDKs

To facilitate the development of plugins, The Falco Project provides SDKs for multiple programming languages: Go, C++, and Rust. These SDKs provide flexibility for developers to choose the programming language they are most comfortable with while ensuring a consistent and streamlined experience when building Falco plugins.

C++ SDK

The C++ SDK provides abstract base classes for plugin development. Plugin authors can derive from these base classes and implement abstract methods to:

Supply plugin metadata and capabilities.
Provide events.
Extract fields from events.

Go SDK

We offer a Go SDK that simplifies plugin development by providing support code and abstractions. This SDK includes:

Go structs and enums corresponding to the C structs and enums used by the plugin API.
Utility packages to handle memory management and type conversions.
Abstract interfaces that provide a streamlined and user-friendly way to implement plugins.

For a detailed explanation of the architecture and usage of the Go SDK, refer to the Go SDK walkthrough section.

Rust SDK

We recently introduced a Rust SDK, enabling developers to write plugins in Rust. The Rust SDK offers a safe, idiomatic interface for interacting with the Falco plugin API while leveraging Rust’s strong type system and memory safety guarantees.

Docs: How to distribute a plugin

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

In this article, we'll focus on the steps to build the OCI artifacts containing the plugin and its rules and how to distribute them on Github Packages.

To get more familiar with the OCI artifacts, you can read our blog posts about falcoctl and GitOps for rules

In the next sections we'll describe how to:

set up a Github Actions workflow to:
- create a release with GoReleaser when a tag is pushed
- build the OCI artifacts of the plugin and its rules
create the index.yaml used by falcoctl

Requirements

This tutorial is based on a Github repo, with the possibility to run workflows in Github Actions and store OCI artifacts in Github Packages. If you use a different system or even just private repositories, you'll need to adapt the examples to your context.

To make it work, you must have the code organization proposed in how to develop a plugin page.

GoReleaser

GoReleaser is a famous tool to build and create releases for projects on Github or else. We'll use it to build and archive the binaries at each release.

At the root of your repo, create a .goreleaser.yaml file with the following content:

builds:
 - env:
 - GODEBUG=cgocheck=0
 main: ./plugin
 binary: lib{PLUGIN_NAME}.so
 goos:
 - linux
 goarch:
 - amd64
 flags: -buildmode=c-shared
checksum:
 name_template: "checksums.txt"

With PLUGIN_NAME as the name of your plugin.

Makefile

Makefiles are a convenient way to script actions. We'll use it to pass all the required flags to create the final .so library files used by the Falco plugin framework:

SHELL=/bin/bash -o pipefail
GO ?= go

NAME := {PLUGIN_NAME}
OUTPUT := lib$(NAME).so

ifeq ($(DEBUG), 1)
 GODEBUGFLAGS= GODEBUG=cgocheck=2
else
 GODEBUGFLAGS= GODEBUG=cgocheck=0
endif

all: build

clean:
 @rm -f lib$(NAME).so

build: clean
 @$(GODEBUGFLAGS) $(GO) build -buildmode=c-shared -buildvcs=false -o $(OUTPUT) ./plugin

With PLUGIN_NAME as the name of your plugin.

You can test it by running make build and see the lib{PLUGIN_NAME}.so appearing at the root of your folder.

Github Actions Workflow

The first step is to create the .github/workflows folder and the release.yaml file describing our workflow.

Headers

Each workflow starts with, at least, a name and a on:

name: Release Plugins

on:
 push:
 tags:
 - '[0-9]+\.[0-9]+\.[0-9]+'

env:
 OCI_REGISTRY: ghcr.io
 PLUGIN_NAME: {PLUGIN_NAME}

permissions:
 contents: write
 packages: write

The workflow will be triggered each time a tag following semantic versioning (major.minor.patch) is created.

Once again PLUGIN_NAME is the name of your plugin, it will be set as env var to be reused all over the file. It's the only thing to adapt to your context. We also set the registry (Github Packages) URL with OCI_REGISTRY.

The permissions are required to allow Github Actions to read the content of your repo, create the release and push the artifacts into Github Packages.

The jobs

Once we have set the "headers" of the workflow file, it's time to set the actions that will be run. We'll split them into 2:

Publish the OCI artifacts
Create the release

Publish the OCI artifacts

To publish the artifacts, we'll use falcoctl, the official CLI to manage Falco artifacts.

The steps to publishing the artifacts will be, in this order:

Get the falcoctl sources
Prepare the Go env
Build falcoctl (guarantees the latest version)
Get the plugin sources
Build the plugin (.so file)
Get the repo name in lower case
Push the artifacts with all their tags:
- push the plugin
- push the rules with a dependency to the plugin

jobs:
 publish-oci-artifacts:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout Falcoctl Repo
 uses: actions/checkout@v3
 with:
 repository: falcosecurity/falcoctl
 ref: main
 path: tools/falcoctl
 - name: Setup Golang
 uses: actions/setup-go@v4
 with:
 go-version: '^1.20'
 cache-dependency-path: tools/falcoctl/go.sum
 - name: Build falcoctl
 run: make
 working-directory: tools/falcoctl
 - name: Checkout
 uses: actions/checkout@v3
 with:
 path: plugin
 - name: Build the plugin
 run: make build
 working-directory: plugin
 - id: StringRepoName
 uses: ASzc/change-string-case-action@v5
 with:
 string: ${{ github.repository }}
 - name: Upload OCI artifacts to GitHub packages
 run: |
 MAJOR=$(echo ${{ github.ref_name }} | cut -f1 -d".")
 MINOR=$(echo ${{ github.ref_name }} | cut -f1,2 -d".")
 DIR=$(pwd)

 cd plugin/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/plugin/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type plugin \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --platform linux/amd64 \
 --requires plugin_api_version:2.0.0 \
 --depends-on ${{ env.PLUGIN_NAME }}-rules:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }} \
 lib${{ env.PLUGIN_NAME }}.so

 cd rules/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/ruleset/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type rulesfile \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --depends-on ${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }}-rules \
 ${{ env.PLUGIN_NAME }}_rules.yaml
 env:
 FALCOCTL_REGISTRY_AUTH_BASIC: ${{ env.OCI_REGISTRY }},${{ github.repository_owner }},${{ secrets.GITHUB_TOKEN }}

Create the release

GoReleaser can automatically generate a Changelog at the same time we publish the new artifacts. This step isn't imperative to generate the OCI artifacts but it's a good practice among Go developers. To achieve that, make sure to have a correct .goreleaser.yml file as explained here.

 release:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - name: Setup Golang
 uses: actions/setup-go@v3
 with:
 go-version: '1.19'
 - name: Run GoReleaser
 uses: goreleaser/goreleaser-action@v4
 with:
 version: latest
 args: release --clean --timeout 120m
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 LDFLAGS: "-buildmode=c-shared"
 GOPATH: /home/runner/go

Final result

name: Release Plugins

on:
 push:
 tags:
 - '[0-9]+\.[0-9]+\.[0-9]+'

env:
 OCI_REGISTRY: ghcr.io
 PLUGIN_NAME: {PLUGIN_NAME}

permissions:
 contents: write
 packages: write

jobs:
 publish-oci-artifacts:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout Falcoctl Repo
 uses: actions/checkout@v3
 with:
 repository: falcosecurity/falcoctl
 ref: 0.5.0 # adapt to the latest version
 path: tools/falcoctl
 - name: Setup Golang
 uses: actions/setup-go@v4
 with:
 go-version: '^1.20'
 cache-dependency-path: tools/falcoctl/go.sum
 - name: Build falcoctl
 run: make
 working-directory: tools/falcoctl
 - name: Checkout
 uses: actions/checkout@v3
 with:
 path: plugin
 - name: Build the plugin
 run: make build
 working-directory: plugin
 - id: StringRepoName
 uses: ASzc/change-string-case-action@v5
 with:
 string: ${{ github.repository }}
 - name: Upload OCI artifacts to GitHub packages
 run: |
 MAJOR=$(echo ${{ github.ref_name }} | cut -f1 -d".")
 MINOR=$(echo ${{ github.ref_name }} | cut -f1,2 -d".")
 DIR=$(pwd)

 cd plugin/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/plugin/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type plugin \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --platform linux/amd64 \
 --requires plugin_api_version:2.0.0 \
 --depends-on ${{ env.PLUGIN_NAME }}-rules:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }} \
 lib${{ env.PLUGIN_NAME }}.so

 cd rules/
 $DIR/tools/falcoctl/falcoctl registry push \
 ${{ env.OCI_REGISTRY }}/${{ steps.StringRepoName.outputs.lowercase }}/ruleset/${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --config /dev/null \
 --type rulesfile \
 --version "${{ github.ref_name }}" \
 --tag latest --tag $MAJOR --tag $MINOR \
 --depends-on ${{ env.PLUGIN_NAME }}:${{ github.ref_name }} \
 --name ${{ env.PLUGIN_NAME }}-rules \
 ${{ env.PLUGIN_NAME }}_rules.yaml
 env:
 FALCOCTL_REGISTRY_AUTH_BASIC: ${{ env.OCI_REGISTRY }},${{ github.repository_owner }},${{ secrets.GITHUB_TOKEN }}

 release:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - name: Setup Golang
 uses: actions/setup-go@v3
 with:
 go-version: '1.19'
 - name: Run GoReleaser
 uses: goreleaser/goreleaser-action@v4
 with:
 version: latest
 args: release --clean --timeout 120m
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 LDFLAGS: "-buildmode=c-shared"
 GOPATH: /home/runner/go

Replace PLUGIN_NAME with the name of your plugin.

The index.yaml file for falcoctl

This file is used by falcoctl to know where to download your plugin and rules. Please read this blog post to understand better how it works.

We'll create our own file to allow like the following:

- name: {PLUGIN_NAME}
 type: plugin
 registry: ghcr.io
 repository: {OWNER_NAME}/{REPO_NAME}/plugin/{PLUGIN_NAME}
 description: {DESCRIPTION}
 home: https://github.com/{OWNER_NAME}/{PLUGIN_NAME}
 keywords:
 - {PLUGIN_NAME}
 license: Apache-2.0
 maintainers:
 - email: {OWNER_EMAIL}
 name: {OWNER_REAL_NAME}
 sources:
 - https://github.com/{OWNER_NAME}/{PLUGIN_NAME}
- name: {PLUGIN_NAME}-rules
 type: rulesfile
 registry: ghcr.io
 repository: {OWNER_NAME}/{REPO_NAME}/ruleset/docker
 description: Rules for the {PLUGIN_NAME} plugin
 home: https://github.com/{OWNER_NAME}/{REPO_NAME}/tree/main/rules
 keywords:
 - {PLUGIN_NAME}
 license: Apache-2.0
 maintainers:
 - email: {OWNER_EMAIL}
 name: {OWNER_REAL_NAME}
 sources:
 - https://github.com/{OWNER_NAME}/{REPO_NAME}/tree/main/rules/{PLUGIN_NAME}_rules.yaml

With:

PLUGIN_NAME: the name of you plugin
OWNER_NAME: your nickname on Github
REPO_NAME: the name of your repo for your plugin on Github
OWNER_EMAIL: an email for contact
OWNER_REAL_NAME: your real name or not
DESCRIPTION: description of your plugin

falcoctl uses the keywords field to perform a search among your plugins. Leverage this functionality by adding relevant terms to your plugin.

The repository structure should look like the following:

├── .github
│ └── workflows
│ └── release.yaml
├── .gitignore
├── go.mod
├── .goreleaser.yml
├── go.sum
├── index.yaml
├── LICENSE
├── Makefile
├── README.md
├── pkg
│ └── {PLUGIN_NAME}.go
├── plugin
│ └── main.go
└── rules
 └── {PLUGIN_NAME}_rules.yaml

There are 2 ways to expose the index.yaml file:

exposing the raw file: https://raw.githubusercontent.com/{OWNER_NAME}/{REPO_NAME}/main/index.yaml
exposing the file through Github Page: https://{OWNER_NAME}.github.io/{REPO_NAME}/index.yaml (make sure to enable the Pages)

Create our first version

Everything is now ready to publish a first version of our plugin.

In the main branch, run:

git tag 0.1.0 -m "0.1.0" && git push origin 0.1.0

Few seconds after, your workflow should be started and you will have your first published version with associated artifacts.

Installation of your plugin and rules

The process is now the same as the one described here, except we'll use your specific index.yaml to register a new index:

sudo falcoctl index add {PLUGIN_NAME} https://{OWNER_NAME}.github.io/{REPO_NAME}/index.yaml
sudo falcoctl artifact install {PLUGIN_NAME}
sudo falcoctl artifact install {PLUGIN_NAME}-rules

For the docker plugin, for example:

❯ sudo falcoctl index add docker http://issif.github.io/docker-plugin/index.yaml

❯ sudo falcoctl artifact search docker
INDEX ARTIFACT TYPE REGISTRY REPOSITORY
docker docker plugin ghcr.io issif/docker-plugin/plugin/docker
docker docker-rules rulesfile ghcr.io issif/docker-plugin/ruleset/docker

❯ sudo falcoctl artifact install docker-rules
 INFO Reading all configured index files from "/root/.config/falcoctl/indexes.yaml"
 INFO Resolving dependencies ...
 INFO Installing the following artifacts: [docker:0.3.3 ghcr.io/issif/docker-plugin/ruleset/docker:latest]
 INFO Preparing to pull "ghcr.io/issif/docker-plugin/plugin/docker:0.3.3"
 INFO Pulling 9145239be00e: ############################################# 100%
 INFO Pulling 2073e106ba07: ############################################# 100%
 INFO Pulling 01ecf22a3821: ############################################# 100%
 INFO Artifact successfully installed in "/usr/share/falco/plugins"
 INFO Preparing to pull "ghcr.io/issif/docker-plugin/ruleset/docker:latest"
 INFO Pulling 3482c7ca931f: ############################################# 100%
 INFO Pulling 433ad24cb056: ############################################# 100%
 INFO Pulling e449b880035d: ############################################# 100%
 INFO Artifact successfully installed in "/etc/falco"

Docs: How to register a plugin

Mon, 01 Jan 0001 00:00:00 +0000

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.