Project: Falco (Provisioning / Security & Compliance)
File: 20190826-grpc-outputs.md

<!-- toc --> * * * <!-- tocstop --> We intend to build a simple gRPC server and SDKs - eg., - to allow users receive and consume the alerts regarding the violated rules. The most valuable information that Falco can give to its users are the alerts. An alert is an "output" when it goes over a transport, and it is emitted by Falco every time a rule is matched. At the current moment, however, Falco can deliver alerts in a very basic way, for example by dumping them to standard output. For this reason, many Falco users asked, with issues - eg., - or in the if we can find a more consumable way to implement Falco outputs in an extensible way. The motivation behind this proposal is to design a new output implementation that can meet our user's needs. To decouple the outputs from the Falco code base To design and implement an additional output mode by mean of a gRPC streaming server To keep it as simple as possible To have a simple contract interface To only have the responsibility to route Falco output requests and responses To continue supporting the old output formats by implementing their same interface To be secure by default (mutual TLS authentication) To be asynchronous and non-blocking To provide a connection over unix socket (no authentication) To implement a Go client To implement a Rust client To implement a Python client To substitute existing outputs (stdout, syslog, etc.) To support different queuing systems than the default (round-robin) one To support queuing mechanisms for message retransmission Users can have a local gRPC relay server along with Falco that multiplexes connections and handles retires and backoff To change the output format To make the message context (text, fields, etc.) and format configurable Users can already override rules changing their output messages To act as an orchestrator for Falco instances Receive Falco events with a well-defined contract over wire Integrate Falco events with existing alerting/paging mechanisms Integrate Falco events with existing monitoring infrastructures/tools Falco outputs SDKs for different languages The following sequence diagram illustrates the flow happening for a single rule being matched and the consequent alert through the gRPC output client. Here is the proto3 contracts definitions for the client and the server SDK. ```proto3 syntax = "proto3"; import "google/protobuf/timestamp.proto"; import "schema.proto"; package falco.outputs; option go_package = "github.com/falcosecurity/client-go/pkg/api/outputs"; // This service defines the RPC methods // to `request` a stream of output `response`s. service service { // Subscribe to a stream of Falco outputs by sending a stream of requests. rpc sub(stream request) returns (stream response); // Get all the Falco outputs present in the system up to this call. rpc get(request) returns (stream response); } // The `request` message is the logical representation of the request model. // It is the input of the `output.service` service. message request { } // The `response` message is the representation of the output model. // It contains all the elements that Falco emits in an output along with the // definitions for priorities and source. message response { google.protobuf.Timestamp time = 1; falco.schema.priority priority = 2; falco.schema.source source = 3; string rule = 4; string output = 5; map<string, string> output_fields = 6; string hostname = 7; } ```