From 47ab5bf39d04e82ae0c85000415e483ebaa102bb Mon Sep 17 00:00:00 2001 From: Leonardo Di Donato Date: Wed, 25 Sep 2019 09:23:21 +0000 Subject: [PATCH] update(proposals): address review comments and suggestions Co-authored-by: Lorenzo Fontana Signed-off-by: Leonardo Di Donato --- proposals/20190826-grpc-outputs.md | 118 ++++++++++++----------------- 1 file changed, 48 insertions(+), 70 deletions(-) diff --git a/proposals/20190826-grpc-outputs.md b/proposals/20190826-grpc-outputs.md index fbfd85fc..595e3af0 100644 --- a/proposals/20190826-grpc-outputs.md +++ b/proposals/20190826-grpc-outputs.md @@ -2,50 +2,50 @@ -- [Summary](#summary) -- [Motivation](#motivation) - * [Goals](#goals) - * [Non-Goals](#non-goals) -- [Proposal](#proposal) - * [Use cases](#use-cases) - * [Diagrams](#diagrams) - * [Design Details](#design-details) +- [gRPC Falco Output](#grpc-falco-output) + - [Summary](#summary) + - [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) + - [Proposal](#proposal) + - [Use cases](#use-cases) + - [Diagrams](#diagrams) + - [Design Details](#design-details) ## Summary -We intend to build a simple gRPC contract and SDKs - eg., [falco#785](https://github.com/falcosecurity/falco/issues/785) - to allow users receive and consume the alerts regarding the violated rules. +We intend to build a simple gRPC server and SDKs - eg., [falco#785](https://github.com/falcosecurity/falco/issues/785) - to allow users receive and consume the alerts regarding the violated rules. ## Motivation The most valuable information that Falco can give to its users are the alerts. -An alert is given by Falco each 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., [falco#528](https://github.com/falcosecurity/falco/issues/528) - or in the [slack channel]() if we can find a more consumable way to -implement Falco outputs in an extensible way. +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., [falco#528](https://github.com/falcosecurity/falco/issues/528) - or in the [slack channel](https://sysdig.slack.com) 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. ### Goals - To decouple the outputs from the Falco code base -- To design and implement an additional output containing a gRPC client +- 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 -- To be asynchronous and non-blocking - +- To be secure by default (**mutual TLS** authentication) +- To be **asynchronous** and **non-blocking** +- To implement a Go SDK ### Non-Goals - To substitute existing outputs (stdout, syslog, etc.) -- To support connecting to multiple gRPC servers - - Users can have a single server multiplexing requests to multiple servers +- To support different queing 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 @@ -53,7 +53,6 @@ The motivation behind this proposal is to design a new output implementation tha - Users can already override rules changing their output messages - To act as an orchestrator for Falco instances - ## Proposal ### Use cases @@ -61,6 +60,7 @@ The motivation behind this proposal is to design a new output implementation tha - 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 ### Diagrams @@ -70,66 +70,44 @@ The following sequence diagram illustrates the flow happening for a single rule ### Design Details -- When an `Emit` results in an error the response contains and error code and message - - Errored emits MUST be handled by Falco by sending the same event in the standard output enriched with the info about the failed `Emit` RPC -- The RPC communication is asynchronous and non-blocking -- The RPC communication is made of two (`Output` and `Response`) bi-directional streams -- `Output` and `Response` messages are correlated through the `id` field - - The `id` field is crafted by the gRPC output client -- The communication is secured using TLS and the builtin client authentication mechanism - Here is the proto3 contracts definitions for the client and the server SDK. ```proto3 -// Overview +syntax = "proto3"; -// The `FalcoOutputService` service defines the Emit RPC call -// that is used to do a bidirectional stream of events between the output server and Falco. +import "google/protobuf/timestamp.proto"; +import "schema.proto"; -// The `Output` message is the logical representation of the output model, -// it contains all the elements that Falco emits in an output along with the -// definitions for priorities and sources. It is given as an input to the Emit RPC call. +package falco.output; -// The `Response` message is the logical representation of the response to an Emit -// RPC call, it contains a message and the information on wether the server returned an error -// while handling the provided `Output`. +option go_package = "github.com/falcosecurity/client-go/pkg/api/output"; -// The `Output` and `Response` messages are enriched with an unique identifier that is needed -// because of the asynchronous nature of the streams in order to correlate them. - -service FalcoOutputService { - rpc Emit (stream Output) returns (stream Response); +// The `subscribe` service defines the RPC call +// to perform an output `request` which will lead to obtain an output `response`. +service service { + rpc subscribe(request) returns (stream response); } -message Output { - string id = 1; - Timestamp time = 2; - enum Priority { - EMERGENCY = 0; - ALERT = 1; - CRITICAL = 2; - ERROR = 3; - WARNING = 4; - NOTICE = 5; - INFORMATIONAL = 6; - DEBUG = 7; - } - Priority priority = 3; - enum Source { - SYSCALL = 0; - K8S_AUDIT = 1; - } - Source source = 4; - string rule = 5; - string format = 6; - string output = 7; - map output_fields = 8; +// The `request` message is the logical representation of the request model. +// It is the input of the `subscribe` service. +// It is used to configure the kind of subscription to the gRPC streaming server. +message request { + bool keepalive = 1; + // string duration = 2; // TODO(leodido, fntlnz): not handled yet but keeping for reference. + // repeated string tags = 3; // TODO(leodido, fntlnz): not handled yet but keeping for reference. } -message Response { - string id = 1; - int32 code = 2; - string message = 3; +// The `response` message is the logical 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 output_fields = 6; + // repeated string tags = 7; // TODO(leodido,fntlnz): tags not supported yet, keeping for reference } ```