Generate a variety of suspect actions that are detected by Falco rulesets.
Warning — We strongly recommend that you run the program within Docker (see below), since some commands might alter your system. For example, some actions modify files and directories below /bin, /etc, /dev, etc. Make sure you fully understand what is the purpose of this tool before running any action.
Release notes
Version | Notes |
---|---|
before v0.11 |
Previous versions of the event-generator might be compatible Falco versions up to 0.36, however, we do not guarantee it. |
v0.11 |
Requires Falco 0.37.0 or newer. k8saudit is maintained on a best-effort basis. |
v0.12 |
Requires Falco 0.38.0 or newer. Events collection has been aligned with the stable Falco ruleset. |
The full command line documentation is here.
$ event-generator list --all
helper.CombinedServerClient
helper.DoNothing
helper.ExecLs
helper.InboundConnection
helper.NetworkActivity
helper.OutboundConnection
helper.RunShell
k8saudit.ClusterRoleWithPodExecCreated
k8saudit.ClusterRoleWithWildcardCreated
k8saudit.ClusterRoleWithWritePrivilegesCreated
k8saudit.CreateDisallowedPod
k8saudit.CreateHostNetworkPod
k8saudit.CreateModifyConfigmapWithPrivateCredentials
k8saudit.CreateNodePortService
k8saudit.CreatePrivilegedPod
k8saudit.CreateSensitiveMountPod
k8saudit.K8SConfigMapCreated
k8saudit.K8SDeploymentCreated
k8saudit.K8SServiceCreated
k8saudit.K8SServiceaccountCreated
syscall.AddingSshKeysToAuthorizedKeys
syscall.ChangeNamespacePrivilegesViaUnshare
syscall.ChangeThreadNamespace
syscall.ClearLogActivities
syscall.ContactEC2InstanceMetadataServiceFromContainer
syscall.ContainerDriftDetectedChmod
syscall.ContainerDriftDetectedOpenCreate
syscall.CreateFilesBelowDev
syscall.CreateHardlinkOverSensitiveFiles
syscall.CreateHiddenFilesOrDirectories
syscall.CreateSymlinkOverSensitiveFiles
syscall.DbProgramSpawnedProcess
syscall.DebugfsLaunchedInPrivilegedContainer
syscall.DecodingPayloadInContainer
syscall.DeleteOrRenameShellHistory
syscall.DetectCryptoMinersUsingTheStratumProtocol
syscall.DetectReleaseAgentFileContainerEscapes
syscall.DirectoryTraversalMonitoredFileRead
syscall.DisallowedSSHConnectionNonStandardPort
syscall.DropAndExecuteNewBinaryInContainer
syscall.ExecutionFromDevShm
syscall.FilelessExecutionViaMemfdCreate
syscall.FindAwsCredentials
syscall.InterpretedProcsInboundNetworkActivity
syscall.InterpretedProcsOutboundNetworkActivity
syscall.JavaProcessClassFileDownload
syscall.KubernetesClientToolLaunchedInContainer
syscall.LaunchIngressRemoteFileCopyToolsInContainer
syscall.LaunchPackageManagementProcessInContainer
syscall.LaunchRemoteFileCopyToolsInContainer
syscall.LaunchSuspiciousNetworkToolInContainer
syscall.LaunchSuspiciousNetworkToolOnHost
syscall.MkdirBinaryDirs
syscall.ModifyBinaryDirs
syscall.ModifyContainerEntrypoint
syscall.ModifyShellConfigurationFile
syscall.MountLaunchedInPrivilegedContainer
syscall.NetcatRemoteCodeExecutionInContainer
syscall.NonSudoSetuid
syscall.PacketSocketCreatedInContainer
syscall.PolkitLocalPrivilegeEscalationVulnerabilityCVE20214034
syscall.PotentialLocalPrivilegeEscalationViaEnvironmentVariablesMisuse
syscall.ProgramRunWithDisallowedHttpProxyEnv
syscall.PtraceAntiDebugAttempt
syscall.PtraceAttachedToProcess
syscall.ReadEnvironmentVariableFromProcFiles
syscall.ReadSensitiveFileTrustedAfterStartup
syscall.ReadSensitiveFileUntrusted
syscall.ReadShellConfigurationFile
syscall.ReadSshInformation
syscall.RemoveBulkDataFromDisk
syscall.RunShellUntrusted
syscall.ScheduleCronJobs
syscall.SearchPrivateKeysOrPasswords
syscall.SetSetuidOrSetgidBit
syscall.SudoPotentialPrivilegeEscalation
syscall.SystemProcsNetworkActivity
syscall.SystemUserInteractive
syscall.UnexpectedUDPTraffic
syscall.UnprivilegedDelegationOfPageFaultsHandlingToAUserspaceProcess
syscall.UserMgmtBinaries
syscall.WriteBelowBinaryDir
syscall.WriteBelowEtc
syscall.WriteBelowMonitoredDir
syscall.WriteBelowRoot
syscall.WriteBelowRpmDatabase
event-generator run [regexp]
Without arguments, it runs all actions; otherwise, only those actions match the given regular expression.
For example, to run only those actions containing the word Files
in their name:
$ sudo event-generator run syscall\.\*Files\.\*
INFO sleep for 100ms action=syscall.ReadSensitiveFileUntrusted
INFO action executed action=syscall.ReadSensitiveFileUntrusted
INFO sleep for 100ms action=syscall.CreateSymlinkOverSensitiveFiles
INFO action executed action=syscall.CreateSymlinkOverSensitiveFiles
INFO sleep for 100ms action=syscall.DirectoryTraversalMonitoredFileRead
INFO action executed action=syscall.DirectoryTraversalMonitoredFileRead
INFO sleep for 100ms action=syscall.ReadSensitiveFileTrustedAfterStartup
INFO spawn as "httpd" action=syscall.ReadSensitiveFileTrustedAfterStartup args="^syscall.ReadSensitiveFileUntrusted$ --sleep 6s"
INFO sleep for 6s action=syscall.ReadSensitiveFileUntrusted as=httpd
INFO action executed action=syscall.ReadSensitiveFileUntrusted as=httpd
Useful options:
--loop
to run actions in a loop--sleep
to set the length of time to wait before running an action (default to 100ms
)Also, note that not all actions are enabled by default. To run all actions, use the --all
option.
Further options are documented here.
Run all events with the Docker image locally:
docker run -it --rm falcosecurity/event-generator run
It can be deployed in a Kubernetes cluster using the event-generator helm chart.
Before installing the chart, add the falcosecurity
charts repository:
helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update
Run all events once using a Kubernetes job:
helm install event-generator falcosecurity/event-generator \
--namespace event-generator \
--create-namespace \
--set config.loop=false \
--set config.actions=""
Run all events in a loop using a Kubernetes deployment:
helm install event-generator falcosecurity/event-generator \
--namespace event-generator \
--create-namespace \
--set config.actions=""
N.B.
The above commands apply to the event-generator
namespace. Use a different name to use a different namespace. It will generate events in the same namespace.
The syscall
collection performs a variety of suspect actions detected by the default Falco ruleset.
Note that only actions for stable rules are enabled by default. To enable all other actions, use the --all
option.
$ docker run -it --rm falcosecurity/event-generator run syscall --loop
The above command loops forever, incessantly generating a sample event every 100 miliseconds.
The
k8saudit
events collection in theevent-generator
is maintained on a best-effort basis and may not fully work.
The k8saudit
collection generates activity that matches the k8s audit event ruleset.
Note that all k8saudit
are disabled by default. To enable them, use the --all
option.
$ event-generator run k8saudit --all --loop --namespace `falco-eg-sandbox`
N.B.: the namespace must exist already.
The above command loops forever, creating resources in the falco-eg-sandbox
namespace and deleting the after each iteration.
N.B.
Since v0.4.0
, this tool introduces a convenient integration test suite for Falco rules. The event-generator test
command can run actions and test them against a running Falco instance.
This feature requires Falco 0.24.0 or newer. Before using the command below, you need Falco installed and running with the gRPC Output enabled.
syscall
only)Run the following command to test syscall
actions on a local Falco instance (connects via Unix socket to /run/falco/falco.sock
by default):
sudo ./event-generator test syscall
Before running the following commands make sure you have added the falcosecurity
charts repository as explained here.
Test all events once using a Kubernetes job:
helm install event-generator falcosecurity/event-generator \
--namespace event-generator \
--create-namespace \
--set config.command=test \
--set config.loop=false \
--set config.actions=""
Test all events in a loop using a Kubernetes deployment:
helm install event-generator falcosecurity/event-generator \
--namespace event-generator \
--create-namespace \
--set config.command=test \
--set config.actions=""
Note that to test k8saudit
events, you need Kubernetes Audit Log functionality enabled in Kubernetes and the k8saudit plugin in Falco.
Since v0.5.0
, the event-generator
can also be used for benchmarking a running instance of Falco. The command event-generator bench
generates a high number of Event Per Second (EPS) to show you events throughput allowed by your Falco installation.
Be aware that before Falco 0.37 a rate-limiter for notifications that affects the gRPC Outputs APIs was present. You probably need to increase the outputs.rate
and outputs.max_burst
values within the Falco configuration, otherwise EPS will be rate-limited by the throttling mechanism.
Before starting a benchmark, the most important thing to understand is that the --sleep
option controls the number of EPS (default to 250ms
): reducing this value will increase the EPS. Furthermore, if the --loop
option is set, the sleeping duration is automatically halved on each round. The --pid
option can be used to monitor the Falco process.
You can find more details about the command-line usage here.
Please, keep in mind that not all actions can be used for benchmarking since some of them take too long to generate a high number of EPS. For example, k8saudit
actions are not supposed to work, since those actions need some time to create Kubernetes resources. Also, some syscall
actions sleep for a while (like the syscall.ReadSensitiveFileUntrusted) thus cannot be used.
Benchmark example
A common way for benchmarking a local Falco instance is by running the following command (that connects via Unix socket to /run/falco/falco.sock
by default):
sudo event-generator bench "ChangeThreadNamespace|ReadSensitiveFileUntrusted" --all --loop --sleep 10ms --pid $(pidof -s falco)
See the events registry.
Sure!
Check out the events registry conventions, then feel free to open a PR!
Your contribution is highly appreciated.
This project provides three main packages that can be imported and used separately:
/cmd
contains the CLI implementation/events
contains the events registry/pkg/runner
contains the actions runner implementationsFeel free to use them as you like on your projects.
Special thanks to Mark Stemm (@mstemm) — the author of the first event generator.