README.md

Falco Go Client

Go client and SDK for Falco

Learn more about the gRPC API by reading the docs.

Install

go get -u github.com/falcosecurity/client-go

Usage

Network Client creation

If you are binding the Falco gRPC server to a network socket with mTLS (mutual TLS authentication) you need this one. Please remember that since this is enabling mTLS you will need to generate a pair of certificates for this client specifically and provide the CA certificate. If you need something simpler, go for the unix socket.

package main

imports(
    "context"
    "github.com/falcosecurity/client-go/pkg/client"
)

func main() {
    c, err := client.NewForConfig(context.Background(), &client.Config{
        Hostname:   "localhost",
        Port:       5060,
        CertFile:   "/etc/falco/certs/client.crt",
        KeyFile:    "/etc/falco/certs/client.key",
        CARootFile: "/etc/falco/certs/ca.crt",
    })
}

Unix Socket Client creation

If you are binding the Falco gRPC server to unix socket, this is what you need.

package main

imports(
    "context"
    "github.com/falcosecurity/client-go/pkg/client"
)

func main() {
    c, err := client.NewForConfig(context.Background(), &client.Config{
        UnixSocketPath:   "unix:///run/falco/falco.sock",
    })
}

Falco outputs API

outputsClient, err := c.Outputs()
if err != nil {
    log.Fatalf("unable to obtain an output client: %v", err)
}

ctx := context.Background()
fcs, err := outputsClient.Get(ctx, &outputs.Request{})
if err != nil {
    log.Fatalf("could not subscribe: %v", err)
}

for {
    res, err := fcs.Recv()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatalf("error closing stream after EOF: %v", err)
    }
    fmt.Printf("rule: %s\n", res.Rule)
}

Falco version API

// Set up a connection to the server.
c, err := client.NewForConfig(context.Background(), &client.Config{
    Hostname:   "localhost",
    Port:       5060,
    CertFile:   "/etc/falco/certs/client.crt",
    KeyFile:    "/etc/falco/certs/client.key",
    CARootFile: "/etc/falco/certs/ca.crt",
})
if err != nil {
    log.Fatalf("unable to create a Falco client: %v", err)
}
defer c.Close()
versionClient, err := c.Version()
if err != nil {
    log.Fatalf("unable to obtain a version client: %v", err)
}

ctx := context.Background()
res, err := versionClient.Version(ctx, &version.Request{})
if err != nil {
    log.Fatalf("error obtaining the Falco version: %v", err)
}
fmt.Printf("%v\n", res)

Full Examples

• Outputs events over mTLS example
• Outputs events over Unix socket example
• Outputs events over mTLS bidirectional example
• Outputs events over Unix socket bidirectional example
• Version over mTLS example
• Version over Unix socket example

Update protos

Perform the following edits to the Makefile:

1. Update the PROTOS array with the destination path of the .proto file.
2. Update the PROTO_URLS array with the URL from which to download it.
3. Update the PROTO_SHAS array with the SHA256 sum of the file to download.
4. Execute the following commands:

make clean
make protos

Generate mocks for protos

1. Follow the steps in the Update protos section
2. Execute the following commands:

make mocks