mirror of
https://github.com/falcosecurity/falco.git
synced 2025-07-10 05:03:37 +00:00
cb4cec6f57
Found by running the following command: codespell -f -H -L aks,creat,chage -S .git Signed-off-by: Mateusz Gozdek <mgozdek@microsoft.com>
127 lines
3.4 KiB
Markdown
127 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
- [falcoctl](https://github.com/falcosecurity/falcoctl)
|
|
- [falco-exporter](https://github.com/falcosecurity/falco-exporter)
|
|
|
|
## 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,
|
|
```proto3
|
|
# 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.
|
|
|
|
```proto3
|
|
# 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,
|
|
```proto3
|
|
service api {
|
|
rpc version(request) returns (response);
|
|
rpc outputs(request) returns (stream response);
|
|
rpc drops(request) returns (stream response);
|
|
...
|
|
}
|
|
```
|