# 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);
      ...
    }
    ```