{"id":13773361,"url":"https://github.com/falcosecurity/event-generator","last_synced_at":"2025-04-05T05:04:57.268Z","repository":{"id":37609848,"uuid":"252686903","full_name":"falcosecurity/event-generator","owner":"falcosecurity","description":"Generate a variety of suspect actions that are detected by Falco rulesets","archived":false,"fork":false,"pushed_at":"2024-10-29T08:56:33.000Z","size":570,"stargazers_count":93,"open_issues_count":12,"forks_count":39,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-10-29T10:04:36.020Z","etag":null,"topics":["go","kubernetes-auditing","security","security-testing","syscall"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/falcosecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-03T09:23:44.000Z","updated_at":"2024-10-27T18:32:13.000Z","dependencies_parsed_at":"2023-12-21T15:44:37.916Z","dependency_job_id":"0fb711d9-e395-486c-afb3-0782cec9a74a","html_url":"https://github.com/falcosecurity/event-generator","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":"falcosecurity/template-repository","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Fevent-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Fevent-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Fevent-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Fevent-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/falcosecurity","download_url":"https://codeload.github.com/falcosecurity/event-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289426,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","kubernetes-auditing","security","security-testing","syscall"],"created_at":"2024-08-03T17:01:14.792Z","updated_at":"2025-04-05T05:04:57.250Z","avatar_url":"https://github.com/falcosecurity.png","language":"Go","funding_links":[],"categories":["Tools","Official projects"],"sub_categories":["Simulation / Experimentation","Repositories"],"readme":"\n# event-generator\n[![Falco Ecosystem Repository](https://github.com/falcosecurity/evolution/blob/main/repos/badges/falco-ecosystem-blue.svg)](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#ecosystem-scope) [![Incubating](https://img.shields.io/badge/status-incubating-orange?style=for-the-badge)](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#incubating)\n\n[![Release](https://img.shields.io/github/release/falcosecurity/event-generator.svg?style=flat-square)](https://github.com/falcosecurity/event-generator/releases/latest)\n[![License](https://img.shields.io/github/license/falcosecurity/event-generator?style=flat-square)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/falcosecurity/event-generator?style=flat-square)](https://goreportcard.com/report/github.com/falcosecurity/event-generator)\n[![Docker pulls](https://img.shields.io/docker/pulls/falcosecurity/event-generator?style=flat-square)](https://hub.docker.com/r/falcosecurity/event-generator)\n![Architectures](https://img.shields.io/badge/ARCHS-x86__64%7Caarch64-blueviolet?style=flat-square)\n\nGenerate a variety of suspect actions that are detected by Falco rulesets.\n\n**Warning** — We strongly recommend that you run the program within Docker (see below), since some commands might alter your system. \n    For example, some actions modify files and directories below /bin, /etc, /dev, etc.\n    Make sure you fully understand what is the purpose of this tool before running any action.\n\n**Release notes**\n\n| Version | Notes |\n| ------- | ----- |\n| before `v0.11` |  Previous versions of the `event-generator` might be compatible Falco versions up to 0.36, however, we do not guarantee it. |\n| `v0.11` | Requires Falco 0.37.0 or newer. `k8saudit` is maintained on a best-effort basis. |\n| `v0.12` | Requires Falco 0.38.0 or newer. Events collection has been aligned with the `stable` Falco ruleset. |\n\n## Usage\n\nThe full command line documentation is [here](./docs/event-generator.md).\n\n### List actions\n\n```shell\n$ event-generator list --all\n\nhelper.CombinedServerClient\nhelper.DoNothing\nhelper.ExecLs\nhelper.InboundConnection\nhelper.NetworkActivity\nhelper.OutboundConnection\nhelper.RunShell\nk8saudit.ClusterRoleWithPodExecCreated\nk8saudit.ClusterRoleWithWildcardCreated\nk8saudit.ClusterRoleWithWritePrivilegesCreated\nk8saudit.CreateDisallowedPod\nk8saudit.CreateHostNetworkPod\nk8saudit.CreateModifyConfigmapWithPrivateCredentials\nk8saudit.CreateNodePortService\nk8saudit.CreatePrivilegedPod\nk8saudit.CreateSensitiveMountPod\nk8saudit.K8SConfigMapCreated\nk8saudit.K8SDeploymentCreated\nk8saudit.K8SServiceCreated\nk8saudit.K8SServiceaccountCreated\nsyscall.AddingSshKeysToAuthorizedKeys\nsyscall.ChangeNamespacePrivilegesViaUnshare\nsyscall.ChangeThreadNamespace\nsyscall.ClearLogActivities\nsyscall.ContactEC2InstanceMetadataServiceFromContainer\nsyscall.ContainerDriftDetectedChmod\nsyscall.ContainerDriftDetectedOpenCreate\nsyscall.CreateFilesBelowDev\nsyscall.CreateHardlinkOverSensitiveFiles\nsyscall.CreateHiddenFilesOrDirectories\nsyscall.CreateSymlinkOverSensitiveFiles\nsyscall.DbProgramSpawnedProcess\nsyscall.DebugfsLaunchedInPrivilegedContainer\nsyscall.DecodingPayloadInContainer\nsyscall.DeleteOrRenameShellHistory\nsyscall.DetectCryptoMinersUsingTheStratumProtocol\nsyscall.DetectReleaseAgentFileContainerEscapes\nsyscall.DirectoryTraversalMonitoredFileRead\nsyscall.DisallowedSSHConnectionNonStandardPort\nsyscall.DropAndExecuteNewBinaryInContainer\nsyscall.ExecutionFromDevShm\nsyscall.FilelessExecutionViaMemfdCreate\nsyscall.FindAwsCredentials\nsyscall.InterpretedProcsInboundNetworkActivity\nsyscall.InterpretedProcsOutboundNetworkActivity\nsyscall.JavaProcessClassFileDownload\nsyscall.KubernetesClientToolLaunchedInContainer\nsyscall.LaunchIngressRemoteFileCopyToolsInContainer\nsyscall.LaunchPackageManagementProcessInContainer\nsyscall.LaunchRemoteFileCopyToolsInContainer\nsyscall.LaunchSuspiciousNetworkToolInContainer\nsyscall.LaunchSuspiciousNetworkToolOnHost\nsyscall.MkdirBinaryDirs\nsyscall.ModifyBinaryDirs\nsyscall.ModifyContainerEntrypoint\nsyscall.ModifyShellConfigurationFile\nsyscall.MountLaunchedInPrivilegedContainer\nsyscall.NetcatRemoteCodeExecutionInContainer\nsyscall.NonSudoSetuid\nsyscall.PacketSocketCreatedInContainer\nsyscall.PolkitLocalPrivilegeEscalationVulnerabilityCVE20214034\nsyscall.PotentialLocalPrivilegeEscalationViaEnvironmentVariablesMisuse\nsyscall.ProgramRunWithDisallowedHttpProxyEnv\nsyscall.PtraceAntiDebugAttempt\nsyscall.PtraceAttachedToProcess\nsyscall.ReadEnvironmentVariableFromProcFiles\nsyscall.ReadSensitiveFileTrustedAfterStartup\nsyscall.ReadSensitiveFileUntrusted\nsyscall.ReadShellConfigurationFile\nsyscall.ReadSshInformation\nsyscall.RemoveBulkDataFromDisk\nsyscall.RunShellUntrusted\nsyscall.ScheduleCronJobs\nsyscall.SearchPrivateKeysOrPasswords\nsyscall.SetSetuidOrSetgidBit\nsyscall.SudoPotentialPrivilegeEscalation\nsyscall.SystemProcsNetworkActivity\nsyscall.SystemUserInteractive\nsyscall.UnexpectedUDPTraffic\nsyscall.UnprivilegedDelegationOfPageFaultsHandlingToAUserspaceProcess\nsyscall.UserMgmtBinaries\nsyscall.WriteBelowBinaryDir\nsyscall.WriteBelowEtc\nsyscall.WriteBelowMonitoredDir\nsyscall.WriteBelowRoot\nsyscall.WriteBelowRpmDatabase\n```\n\n### Run actions\n```\nevent-generator run [regexp]\n```\nWithout arguments, it runs all actions; otherwise, only those actions match the given regular expression.\n\nFor example, to run only those actions containing the word `Files` in their name:\n\n```shell\n$ sudo event-generator run syscall\\.\\*Files\\.\\*\n\nINFO sleep for 100ms                               action=syscall.ReadSensitiveFileUntrusted\nINFO action executed                               action=syscall.ReadSensitiveFileUntrusted\nINFO sleep for 100ms                               action=syscall.CreateSymlinkOverSensitiveFiles\nINFO action executed                               action=syscall.CreateSymlinkOverSensitiveFiles\nINFO sleep for 100ms                               action=syscall.DirectoryTraversalMonitoredFileRead\nINFO action executed                               action=syscall.DirectoryTraversalMonitoredFileRead\nINFO sleep for 100ms                               action=syscall.ReadSensitiveFileTrustedAfterStartup\nINFO spawn as \"httpd\"                              action=syscall.ReadSensitiveFileTrustedAfterStartup args=\"^syscall.ReadSensitiveFileUntrusted$ --sleep 6s\"\nINFO sleep for 6s                                  action=syscall.ReadSensitiveFileUntrusted as=httpd\nINFO action executed                               action=syscall.ReadSensitiveFileUntrusted as=httpd\n```\n\nUseful options:\n- `--loop` to run actions in a loop\n- `--sleep` to set the length of time to wait before running an action (default to `100ms`)\n\nAlso, note that not all actions are enabled by default. To run all actions, use the `--all` option.\n\nFurther options are documented [here](./docs/event-generator_run.md).\n\n\n#### With Docker\n\nRun all events with the Docker image locally:\n\n```shell\ndocker run -it --rm falcosecurity/event-generator run\n```\n\n\n#### With Kubernetes\n\nIt can be deployed in a Kubernetes cluster using the event-generator [helm chart](https://github.com/falcosecurity/charts/tree/master/charts/event-generator).\nBefore installing the chart, add the `falcosecurity` charts repository:\n\n```bash\nhelm repo add falcosecurity https://falcosecurity.github.io/charts\nhelm repo update\n```\n\nRun all events once using a Kubernetes job:\n\n```shell\nhelm install event-generator falcosecurity/event-generator \\\n  --namespace event-generator \\\n  --create-namespace \\\n  --set config.loop=false \\\n  --set config.actions=\"\"\n```\n\nRun all events in a loop using a Kubernetes deployment:\n\n```bash\nhelm install event-generator falcosecurity/event-generator \\\n  --namespace event-generator \\\n  --create-namespace \\\n  --set config.actions=\"\"\n```\n\n\n**N.B.**\nThe 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.\n\n## Collections\n\n### Generate System Call activity\nThe `syscall` collection performs a variety of suspect actions detected by the [default Falco ruleset](https://github.com/falcosecurity/rules/tree/main/rules).\n\nNote that only actions for [stable rules](https://github.com/falcosecurity/rules/blob/main/rules/falco_rules.yaml) are enabled by default. To enable all other actions, use the `--all` option.\n\n```shell\n$ docker run -it --rm falcosecurity/event-generator run syscall --loop\n```\n\nThe above command loops forever, incessantly generating a sample event every 100 miliseconds. \n\n\n### Generate activity for the k8saudit rules\n\u003e The `k8saudit` events collection in the `event-generator` is maintained on a best-effort basis and may not fully work.\n\nThe `k8saudit` collection generates activity that matches the [k8s audit event ruleset](https://github.com/falcosecurity/plugins/blob/master/plugins/k8saudit/rules/k8s_audit_rules.yaml).\n\nNote that all `k8saudit` are disabled by default. To enable them, use the `--all` option.\n\n```shell\n$ event-generator run k8saudit --all --loop --namespace `falco-eg-sandbox`\n```\n\u003e N.B.: the namespace must exist already.\n\nThe above command loops forever, creating resources in the `falco-eg-sandbox` namespace and deleting the after each iteration.\n\n**N.B.**\n- the namespace must already exist\n- to produce any effect the Kubernetes audit log must be enabled, see [here](https://falco.org/docs/event-sources/kubernetes-audit/)\n\n\n## Test rules\n\nSince `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.\n\n\u003e This feature requires Falco 0.24.0 or newer. Before using the command below, you need [Falco installed](https://falco.org/docs/installation/) and running with the [gRPC Output](https://falco.org/docs/grpc/) enabled.\n\n#### Test locally (`syscall` only)\n\nRun the following command to test `syscall` actions on a local Falco instance (connects via Unix socket to `/run/falco/falco.sock` by default):\n\n```shell\nsudo ./event-generator test syscall\n```\n\n#### Test on Kubernetes\n\nBefore running the following commands make sure you have added the `falcosecurity` charts repository as explained [here](#with-kubernetes).\n\nTest all events once using a Kubernetes job:\n\n```shell\nhelm install event-generator falcosecurity/event-generator \\\n  --namespace event-generator \\\n  --create-namespace \\\n  --set config.command=test \\\n  --set config.loop=false \\\n  --set config.actions=\"\"\n```\n\nTest all events in a loop using a Kubernetes deployment:\n\n```bash\nhelm install event-generator falcosecurity/event-generator \\\n  --namespace event-generator \\\n  --create-namespace \\\n  --set config.command=test \\\n  --set config.actions=\"\"\n```\n\nNote that to test `k8saudit` events, you need _Kubernetes Audit Log_ functionality enabled in Kubernetes and the [k8saudit plugin](https://github.com/falcosecurity/plugins/tree/master/plugins/k8saudit) in Falco.\n\n## Benchmark\n\nSince `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.\n\nBe 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](https://github.com/falcosecurity/falco/blob/e2bf87d207a32401da271835e15dadf957f68e8c/falco.yaml#L90-L104), otherwise EPS will be rate-limited by the throttling mechanism. \n\n### Run a benchmark\n\nBefore 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. \n\n\u003e You can find more details about the command-line usage [here](docs/event-generator_bench.md).\n\nPlease, 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](https://github.com/falcosecurity/event-generator/blob/7bf714aab8da5a3f6d930225f04852e97d682dac/events/syscall/read_sensitive_file_trusted_after_startup.go#L10)) thus cannot be used.\n\n**Benchmark example**\n\nA 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):\n\n```shell\nsudo event-generator bench \"ChangeThreadNamespace|ReadSensitiveFileUntrusted\" --all --loop --sleep 10ms --pid $(pidof -s falco)\n```\n\n## FAQ\n\n### What sample events can this tool generate?\nSee the [events registry](https://github.com/falcosecurity/event-generator/tree/main/events).\n\n### Can I contribute by adding new events?\nSure! \n\nCheck out the [events registry](https://github.com/falcosecurity/event-generator/tree/main/events) conventions, then feel free to open a PR!\n\nYour contribution is highly appreciated.\n\n### Can I use this project as a library?\nThis project provides three main packages that can be imported and used separately:\n\n- `/cmd` contains the CLI implementation\n- `/events` contains the events registry\n- `/pkg/runner` contains the actions runner implementations\n\nFeel free to use them as you like on your projects.\n\n## Acknowledgments\n\nSpecial thanks to Mark Stemm (**@mstemm**) — the author of the [first event generator](https://github.com/falcosecurity/falco/tree/2126616529e7015ff88653b7491dc1937d7e54e5/docker/event-generator).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalcosecurity%2Fevent-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffalcosecurity%2Fevent-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalcosecurity%2Fevent-generator/lists"}