Falco – gRPC API

Docs: Configuration

Mon, 01 Jan 0001 00:00:00 +0000

The gRPC Output as well as the embedded gRPC server have been deprecated in Falco 0.43.0 and will be removed in a future release. Until removal and since Falco 0.43.0, using any of them will result in a warning informing the user about the deprecation. Users are encouraged to leverage another output and/or Falcosidekick, as the usage will result in an error after the removal.

Enabling the Server

The Falco gRPC server and the Falco gRPC Outputs APIs are not enabled by default.

To enable them, edit the falco.yaml Falco configuration file. A sample Falco configuration file is given below:

# Falco supports running a gRPC server with two main binding types
# 1. Over the network with mandatory mutual TLS authentication (mTLS)
# 2. Over a local unix socket with no authentication
# By default, the gRPC server is disabled, with no enabled services (see grpc_output)
# please comment/uncomment and change accordingly the options below to configure it.
# Important note: if Falco has any troubles creating the gRPC server
# this information will be logged, however the main Falco daemon will not be stopped.
# gRPC server over network with (mandatory) mutual TLS configuration.
# This gRPC server is secure by default so you need to generate certificates and update their paths here.
# By default the gRPC server is off.
# You can configure the address to bind and expose it.
# By modifying the threadiness configuration you can fine-tune the number of threads (and context) it will use.
grpc:
 enabled: true
 bind_address: "0.0.0.0:5060"
 threadiness: 8
 private_key: "/etc/falco/certs/server.key"
 cert_chain: "/etc/falco/certs/server.crt"
 root_certs: "/etc/falco/certs/ca.crt"

As you can see, binding to a network address requires you to generate and specify a set of TLS certificates as shown in the next section.

Alternatively, if you want something simpler, you can tell Falco to bind the gRPC server to a local unix socket, this does not require you to generate certificates for mTLS but also comes without any authentication mechanism.

# gRPC server using an unix socket
grpc:
 enabled: true
 bind_address: "unix:///run/falco/falco.sock"
 threadiness: 8

Then, remember to enable the services you need. Otherwise, the gRPC server won't expose anything.

For the outputs use:

# gRPC output service.
# By default it is off.
# By enabling this all the output events will be kept in memory until you read them with a gRPC client.
# Make sure to have a consumer for them or leave this disabled.
grpc_output:
 enabled: true

Certificates

When configured to bind to a network address, the Falco gRPC server works only with mutual TLS by design. Therefore, you have to generate the certificates and update the paths in the above configuration.

The Falco authors plan to automate the certificate generation soon.

In the meantime, use the following script to generate the certificates.

Note: Ensure that you configure the -passin, -passout, and -subj flags according to your settings.

Generate CA

Run the following commands:

$ openssl genrsa -des3 -passout pass:1234 -out ca.key 4096

$ openssl req -new \
 -x509 \
 -days 365 \
 -key ca.key \
 -out ca.crt \
 -passin pass:1234 \
 -subj "/C=SP/ST=Italy/L=Ornavasso/O=Test/OU=Test/CN=Root CA"

Generate Server Key/Cert

Run the following command:

$ openssl genrsa -des3 -passout pass:1234 -out server.key 4096

$ openssl req -new \
 -key server.key \
 -out server.csr \
 -passin pass:1234 \
 -subj "/C=SP/ST=Italy/L=Ornavasso/O=Test/OU=Server/CN=localhost"

$ openssl x509 -req \
 -days 365 \
 -CA ca.crt \
 -CAkey ca.key \
 -in server.csr \
 -out server.crt \
 -set_serial 01 \
 -passin pass:1234

Remove passphrase from Server Key

Run the following command:

$ openssl rsa -in server.key -out server.key -passin pass:1234

Generate Client Key/Cert

Run the following command:

$ openssl genrsa -des3 -passout pass:1234 -out client.key 4096

$ openssl req -new \
 -passin pass:1234 \
 -key client.key \
 -out client.csr \
 -subj "/C=SP/ST=Italy/L=Ornavasso/O=Test/OU=Client/CN=localhost"

$ openssl x509 -req \
 -days 365 \
 -CA ca.crt \
 -CAkey ca.key \
 -set_serial 01 \
 -in client.csr \
 -out client.crt \
 -passin pass:1234

Remove passphrase from Client Key

Run the following command:

$ openssl rsa -in client.key -out client.key -passin pass:1234

Usage

When the configuration is complete, Falco is ready to expose its gRPC server and its Outputs APIs.

To do so, simply run Falco. For example:

$ falco -c falco.yaml -r rules/falco_rules.yaml -r rules/falco_rules.local.yaml

Refer to the Go client documentation to learn how to receive and consume Falco output events.

Docs: Go Client

Mon, 01 Jan 0001 00:00:00 +0000

The client-go Go library provides:

type and service mappings for the Falco gRPC API. For more information, see output schema.
Client and Config structs that simplify the connection to the gRPC server. For more information, see documentation.

Refer to the fully-functional example to see how the Go client connects to the Falco gRPC Outputs API and displays the events in JSON.

Additional examples for various APIs are located in the examples directory of the client-go repository.

Ensure that you have the certificates in the example's path at /etc/falco/certs/{client.crt,client.key,ca.crt}.

In the client-go root directory, run:

$ go run examples/output/main.go | jq

The output events start flowing in depending on the set of rules in the Falco instance.

{
 "time": {
 "seconds": 1570094449,
 "nanos": 259268899
 },
 "priority": 3,
 "rule": "Modify binary dirs",
 "output": "09:20:49.259268899: Error File below known binary directory renamed/removed (user=vagrant command=lua /home/vagrant/.dotfiles/zsh/.config/zsh/plugins/z.lua/z.lua --init zsh once enhanced pcmdline=zsh operation=rena
me file=<NA> res=0 oldpath=/usr/bin/realpath newpath=/usr/bin/realpath container_id=host image=<NA>)",
 "output_fields": {
 "container.id": "host",
 "container.image.repository": "<NA>",
 "evt.args": "res=0 oldpath=/usr/bin/realpath newpath=/usr/bin/realpath ",
 "evt.time": "09:20:49.259268899",
 "evt.type": "rename",
 "fd.name": "<NA>",
 "proc.cmdline": "lua /home/vagrant/.dotfiles/zsh/.config/zsh/plugins/z.lua/z.lua --init zsh once enhanced",
 "proc.pcmdline": "zsh",
 "user.name": "vagrant"
 }
}
{
 "time": {
 "seconds": 1570094449,
 "nanos": 620298462
 },
 "priority": 4,
 "rule": "Delete or rename shell history",
 "output": "09:20:49.620298462: Warning Shell history had been deleted or renamed (user=vagrant type=unlink command=zsh fd.name=<NA> name=<NA> path=/home/vagrant/.zsh_history.LOCK oldpath=<NA> host (id=host))",
 "output_fields": {
 "container.id": "host",
 "container.name": "host",
 "evt.arg.name": "<NA>",
 "evt.arg.oldpath": "<NA>",
 "evt.arg.path": "/home/vagrant/.zsh_history.LOCK",
 "evt.time": "09:20:49.620298462",
 "evt.type": "unlink",
 "fd.name": "<NA>",
 "proc.cmdline": "zsh",
 "user.name": "vagrant"
 }
}

Docs: Outputs

Mon, 01 Jan 0001 00:00:00 +0000

// SPDX-License-Identifier: Apache-2.0
/*
Copyright (C) 2023 The Falco Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

syntax = "proto3";

import "google/protobuf/timestamp.proto";
import "schema.proto";

package falco.outputs;

option go_package = "github.com/falcosecurity/client-go/pkg/api/outputs";

// This service defines the RPC methods
// to `request` a stream of output `response`s.
service service {
 // Subscribe to a stream of Falco outputs by sending a stream of requests.
 rpc sub(stream request) returns (stream response);
 // Get all the Falco outputs present in the system up to this call.
 rpc get(request) returns (stream response);
}

// The `request` message is the logical representation of the request model.
// It is the input of the `output.service` service.
message request {
 // TODO(leodido,fntlnz): tags not supported yet, keeping it for reference.
 // repeated string tags = 1;
}

// The `response` message is the 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_deprecated = 3 [deprecated=true];
 string rule = 4;
 string output = 5;
 map<string, string> output_fields = 6;
 string hostname = 7;
 repeated string tags = 8;
 string source = 9;
}

Docs: Version

Mon, 01 Jan 0001 00:00:00 +0000

// SPDX-License-Identifier: Apache-2.0
/*
Copyright (C) 2023 The Falco Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

syntax = "proto3";

package falco.version;

option go_package = "github.com/falcosecurity/client-go/pkg/api/version";

// This service defines a RPC call
// to request the Falco version.
service service {
 rpc version(request) returns (response);
}

// The `request` message is an empty one.
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
{
// falco version
 string version = 1;
 uint32 major = 2;
 uint32 minor = 3;
 uint32 patch = 4;
 string prerelease = 5;
 string build = 6;
// falco engine version
 uint32 engine_minor = 7;
 string engine_fields_checksum = 8;
 uint32 engine_major = 9;
 uint32 engine_patch = 10;
 string engine_version = 11;
}