github/falco
1
0
Fork 0
mirror of https://github.com/falcosecurity/falco.git synced 2025-09-16 23:08:16 +00:00
Code Issues Projects Releases Wiki Activity

docs(proposals): grpc output design details

Browse Source 
Co-Authored-by: Lorenzo Fontana <lo@linux.com>
Signed-off-by: Leonardo Di Donato <leodidonato@gmail.com>
This commit is contained in:
Leonardo Di Donato
2019-08-26 18:52:31 +02:00
committed by Leo Di Donato
parent 734d48204d
commit 510d215558
1 changed files with 35 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
proposals/20190826-grpc-outputs.md
View File

@@ -7,13 +7,15 @@
* [Goals](#goals) * [Goals](#goals)
* [Non-Goals](#non-goals) * [Non-Goals](#non-goals)
- [Proposal](#proposal) - [Proposal](#proposal)
- [Design Details](#design-details) * [Use cases](#use-cases)
* [Diagrams](#diagrams)
* [Design Details](#design-details)
<!-- tocstop --> <!-- tocstop -->
## Summary ## 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 ## Motivation
@@ -29,6 +31,7 @@ The motivation behind this proposal is to design a new output implementation tha
### Goals ### 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 containing a gRPC client
- To keep it as simple as possible - To keep it as simple as possible
- To have a simple contract interface - To have a simple contract interface
@@ -53,41 +56,46 @@ The motivation behind this proposal is to design a new output implementation tha
## Proposal ## 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 The following sequence diagram illustrates the flow happening for a single rule being matched and the consequent alert through the gRPC output client.
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?
Bob-->>John: How about you John? ![Single alert sequence diagram](20190826-grpc-output-single-alert-sequence.png)
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
Bob-->Alice: Checking with John... ### Design Details
Alice->John: Yes... John, how are you?
```
``` - When an `Emit` results in an error the response contains and error code and message
Overview - 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 Here is the proto3 contracts definitions for the client and the server SDK.
that is used to do a bidirectional stream of events between the output server and Falco.
The `Output` message is the logical representation of the output model, ```proto3
it contains all the elements that Falco emits in an output along with the // Overview
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 // The `FalcoOutputService` service defines the Emit RPC call
RPC call, it contains a message and the information on wether the server returned an error // that is used to do a bidirectional stream of events between the output server and Falco.
while handling the provided `Output`.
The `Output` and `Response` messages are enriched with an unique identifier that is needed // The `Output` message is the logical representation of the output model,
because of the asynchronous nature of the streams in order to correlate them. // 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 { service FalcoOutputService {
rpc Emit (stream Output) returns (stream Response); rpc Emit (stream Output) returns (stream Response);