Getting Started

Creating a new Falco plugin project

Prerequisites

To build and test your .NET Falco plugins you'll need a Linux host (machine, vm or container) with:

• Falco (see how to Install)
• NET 6+ SDK (and runtime) to build and host the plugin itself

Create a new project

1. install the falcoplugin template
2. create a new project dotnet new falcoplugin (see The falcoplugin template)

Create a new Project manually

1. Clone this repo

2. Create a new NET 6 Library project

3. Add DNNE NuGet package

4. Add Project references to if you cloned the repo:

   • Falco.Plugin.Sdk
   • Falco.Plugin.Sdk.Generators

   OR

   add the NuGet packages:

   • Falco.Plugin.Sdk.Generators
   • Falco.Plugin.Sdk

Update the .csproj

Add DNNE configuration:

<PropertyGroup>
  <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  <EnableDynamicLoading>true</EnableDynamicLoading> 
  <DnneAddGeneratedBinaryToProject>true</DnneAddGeneratedBinaryToProject>
  <DnneNativeBinaryName>plugin_native</DnneNativeBinaryName>
</PropertyGroup>

Make sure Falco.Sdk.Plugin.Generators is referenced as a Source generator

<ProjectReference 
  Include="..\Falco.Plugin.Sdk.Generators\Falco.Plugin.Sdk.Generators.csproj" 
  OutputItemType="Analyzer" 
  ReferenceOutputAssembly="false" />

The full csproj will look something like this:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
	<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
	<EnableDynamicLoading>true</EnableDynamicLoading>
	<DnneAddGeneratedBinaryToProject>true</DnneAddGeneratedBinaryToProject>
	<DnneNativeBinaryName>plugin_native</DnneNativeBinaryName>
    <PublishSingleFile>true</PublishSingleFile>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="DNNE" Version="1.0.32" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\Falco.Plugin.Sdk.Generators\Falco.Plugin.Sdk.Generators.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
    <ProjectReference Include="..\Falco.Plugin.Sdk\Falco.Plugin.Sdk.csproj" />
  </ItemGroup>
</Project>

The falcoplugin template

The Falco.Plugin.Sdk.Template contains a project template to scaffold an empty plugin project. You can check with dotnet new falcoplugin --help or reference template.json / dotnetcli.host.json to see the available parameters and relative aliases

Capabilities

There are two parameters --event-sourcing-capability and --field-extraction-capability than can be used to toggle conditional code for the respective capabilities.

Visual Studio

If you create the project through Visual Studio, after selecting the "Falco Plugin: Empty" template, you will be prompted for a set of parameters to customize the scaffold:

Implement the plugin

see the Dummy Plugin example for a detailed walktrough.