From 510d215558e53787c15843573d90cef4a56ea2b8 Mon Sep 17 00:00:00 2001 From: Leonardo Di Donato Date: Mon, 26 Aug 2019 18:52:31 +0200 Subject: [PATCH] docs(proposals): grpc output design details Co-Authored-by: Lorenzo Fontana Signed-off-by: Leonardo Di Donato --- proposals/20190826-grpc-outputs.md | 62 +++++++++++++++++------------- 1 file changed, 35 insertions(+), 27 deletions(-) diff --git a/proposals/20190826-grpc-outputs.md b/proposals/20190826-grpc-outputs.md index c6d6223c..fbfd85fc 100644 --- a/proposals/20190826-grpc-outputs.md +++ b/proposals/20190826-grpc-outputs.md @@ -7,13 +7,15 @@ * [Goals](#goals) * [Non-Goals](#non-goals) - [Proposal](#proposal) -- [Design Details](#design-details) + * [Use cases](#use-cases) + * [Diagrams](#diagrams) + * [Design Details](#design-details) ## Summary -We intend to build a simple gRPC contract and SDKs - eg., [falco#](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 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. ## Motivation @@ -29,6 +31,7 @@ The motivation behind this proposal is to design a new output implementation tha ### Goals +- To decouple the outputs from the Falco code base - To design and implement an additional output containing a gRPC client - To keep it as simple as possible - To have a simple contract interface @@ -53,41 +56,46 @@ The motivation behind this proposal is to design a new output implementation tha ## Proposal +### Use cases +- 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 -## Design Details +### Diagrams -```mermaid -sequenceDiagram - Syscall input ->> Bob: Hello Bob, how are you? - K8S audit input ->> Bob: Hello Bob, how are you? - Falco engine ->> Bob: Hello Bob, how are you? +The following sequence diagram illustrates the flow happening for a single rule being matched and the consequent alert through the gRPC output client. - Bob-->>John: How about you John? - Bob--x Alice: I am good thanks! - Bob-x John: I am good thanks! - Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row. +![Single alert sequence diagram](20190826-grpc-output-single-alert-sequence.png) - Bob-->Alice: Checking with John... - Alice->John: Yes... John, how are you? -``` +### Design Details -``` -Overview +- 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 -The `FalcoOutputService` service defines the Emit RPC call -that is used to do a bidirectional stream of events between the output server and Falco. +Here is the proto3 contracts definitions for the client and the server SDK. -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. +```proto3 +// Overview -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`. +// The `FalcoOutputService` service defines the Emit RPC call +// that is used to do a bidirectional stream of events between the output server and Falco. -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. +// 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. + +// 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`. + +// 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);