https://github.com/falcosecurity/client-go
Go client and SDK for Falco
https://github.com/falcosecurity/client-go
client falco go golang grpc
Last synced: about 1 month ago
JSON representation
Go client and SDK for Falco
- Host: GitHub
- URL: https://github.com/falcosecurity/client-go
- Owner: falcosecurity
- License: apache-2.0
- Created: 2019-09-09T08:57:21.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-21T17:34:17.000Z (about 2 months ago)
- Last Synced: 2025-03-22T22:16:31.998Z (about 1 month ago)
- Topics: client, falco, go, golang, grpc
- Language: Go
- Homepage:
- Size: 367 KB
- Stars: 53
- Watchers: 7
- Forks: 19
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Falco Go Client
[](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#ecosystem-scope) [](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#incubating)
[](https://godoc.org/github.com/falcosecurity/client-go/pkg/client)
> Go client and SDK for Falco
Learn more about the gRPC API by reading [the docs](https://falco.org/docs/grpc/).
## Install
```bash
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.
```go
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.
```go
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
```go
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
```go
// 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](examples/output/main.go)
- [Outputs events over Unix socket example](examples/output_unix_socket/main.go)
- [Outputs events over mTLS bidirectional example](examples/output_bidi/main.go)
- [Outputs events over Unix socket bidirectional example](examples/output_unix_socket_bidi/main.go)
- [Version over mTLS example](examples/version/main.go)
- [Version over Unix socket example](examples/version_unix_socket/main.go)
## 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:
```console
make clean
make protos
```
## Generate mocks for protos
1. Follow the steps in the `Update protos` section
2. Execute the following commands:
```console
make mocks
```