Falco APIs

Summary

This is a proposal to better structure the Falco API.

The Falco API is a set of contracts describing how users can interacts with Falco.

By defining a set of interfaces the Falco Authors intend to decouple Falco from other software and data (eg., from the input sources) and, at the same time, make it more extensible.

Thus, this document intent is to propose a list of services that constitute the Falco API (targeting the first stable version of Falco, v1.0.0).

Motivation

We want to enable users to use third-party clients to interface with Falco outputs, inputs, rules, and configurations.

Such ability would enable the community to create a whole set of OSS tools, built on top of Falco.

Some examples, already in place, are:

Goals

To design and implement an API to make Falco more configurable
To design and implement an API to make Falco more consumable
To have an API so that users are able to interface with Falco
To design a set of simple contract interfaces
To have an API which is secure by default
To implement this API in C++ using gRPC as a first implementation

Non-Goals

To replace the existing inputs: the inputs will be only for new source events users may want to add, initially
To document the API: to be approached as separate task
To create/update the API client: to be approached as a separate task

Proposal

Use cases

Receive Falco events with a well-defined contract --> outputs
Receive Falco drops with a well-defined contract --> drops
Receive current Falco version and related meta information (commit hash, built type, etc.) --> version
Configure Falco via API (CRUD) -> configs
Inject and/or modify Falco rules via API (CRUD) --> rules
Send input events to Falco --> inputs

Unary services

Version
Rules
Configs

Streaming (server or client) services

Outputs
Drops

Bidirectional streaming services

Inputs

Architecture

We propose to have:

1 gRPC server
1 service grouping services

This translates in having the following set of proto files.

a .proto containing the request and response messages for each service - eg., version.proto, outputs.proto etc.

For example,

proto3

# version.proto
message request
{
  ...
}

// The `response` message contains the version of Falco.
// It provides the whole version as a string and also
// its parts as per semver 2.0 specification (https://semver.org).
message response
{
string version = 1;
  uint32 major = 2;
  uint32 minor = 3;
  uint32 patch = 4;
  string prerelease = 5;
  string build = 6;
}

one or more .proto containing the command models - ie., the already existing schema.proto containing source enum, etc.

proto3

# schema.proto
enum priority {
  ..
}
enum source {
option allow_alias = true;
  SYSCALL = 0;
  syscall = 0;
  Syscall = 0;
  K8S_AUDIT = 1;
  k8s_audit = 1;
  K8s_audit = 1;
  K8S_audit = 1;
}

a .proto for service definitions

For example,

proto3

service api {
  rpc version(request) returns (response);
  rpc outputs(request) returns (stream response);
  rpc drops(request) returns (stream response);
  ...
}