Skip to content

Latest commit

 

History

History
126 lines (93 loc) · 3.44 KB

20191030-api.md

File metadata and controls

126 lines (93 loc) · 3.44 KB

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

  1. Version
  2. Rules
  3. Configs

Streaming (server or client) services

  1. Outputs
  2. Drops

Bidirectional streaming services

  1. 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,

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

    # 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,

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