docs: update documentation for test command

Signed-off-by: Leonardo Grasso <me@leonardograsso.com>

README.md

@@ -79,7 +79,7 @@ Useful options:
 All other options are documented [here](./docs/event-generator_run.md).
 
 
-### With Docker
+#### With Docker
 
 Run all events with the Docker image locally:
 
@@ -88,8 +88,7 @@ docker run -it --rm falcosecurity/event-generator run
 ```
 
 
-### With Kubernetes
-
+#### With Kubernetes
 
 Run the following command to create the Service Account (`falco-event-generator`), Cluster Role, and Role that will allow the tool to create objects in the current namespace:
 
@@ -139,6 +138,37 @@ The above command loops forever, creating resources in the `falco-eg-sandbox` na
 - the namespace must already exist
 - to produce any effect the Kubernetes audit log must be enabled, see [here](https://falco.org/docs/event-sources/kubernetes-audit/)
 
+
+## Test rules
+
+Since `v0.4.0`, this tool introduces a convenient integration test suite for Falco rules. Basically 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](https://falco.org/docs/installation/) and running with the [gRPC Output](https://falco.org/docs/grpc/) enabled.
+
+#### Test locally (`syscall` only)
+
+Run the following command to test `syscall` actions on a local Falco instance (connects via Unix socket to `/var/run/falco.sock` by default):
+
+```shell
+sudo ./event-generator test syscall
+```
+
+#### Test on Kubernetes
+
+Then, run the following command to create the Service Account (`falco-event-generator`), Cluster Role, and Role that will allow the tool to create objects in the current namespace:
+
+```shell
+kubectl apply -f deployment/role-rolebinding-serviceaccount.yaml
+```
+
+Finally:
+
+```shell
+kubectl apply -f deployment/run-test.yaml
+```
+
+Note that to test `k8saudit` events, you need [Kubernetes audit log] enabled both in Kubernetes and Falco.
+
 ## FAQ
 
 ### What sample events can be generated by this tool?
@@ -148,6 +178,7 @@ See the [events registry](https://github.com/falcosecurity/event-generator/tree/
 Sure! 
 
 Check out the [events registry](https://github.com/falcosecurity/event-generator/tree/master/events) conventions, then feel free to open a PR.
+
 Your contribution is highly appreciated.
 
 ### Can I use this project as a library?

docs/event-generator.md

@@ -22,4 +22,5 @@ event-generator [flags]
 
 * [event-generator list](event-generator_list.md)	 - List available actions
 * [event-generator run](event-generator_run.md)	 - Run actions
+* [event-generator test](event-generator_test.md)	 - Run and test actions
 

docs/event-generator_run.md

@@ -7,6 +7,7 @@ Run actions
 Performs a variety of suspect actions.
 Without arguments it runs all actions, otherwise only those actions matching the given regular expression.
 
+
 Warning:
   This command might alter your system. For example, some actions modify files and directories below
   /bin, /etc, /dev, etc.
@@ -20,6 +21,7 @@ event-generator run [regexp] [flags]
 ### Options
 
 ```
+      --all                            Run all actions, including those disabled by default
       --as string                      Username to impersonate for the operation
       --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
       --cache-dir string               Default HTTP cache directory (default "$HOME/.kube/http-cache")

docs/event-generator_test.md

@@ -0,0 +1,63 @@
+## event-generator test
+
+Run and test actions
+
+### Synopsis
+
+Performs a variety of suspect actions and test them against a running Falco instance.
+Without arguments it runs all actions, otherwise only those actions matching the given regular expression.
+
+
+Warning:
+  This command 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.
+
+
+```
+event-generator test [regexp] [flags]
+```
+
+### Options
+
+```
+      --all                            Run all actions, including those disabled by default
+      --as string                      Username to impersonate for the operation
+      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
+      --cache-dir string               Default HTTP cache directory (default "$HOME/.kube/http-cache")
+      --certificate-authority string   Path to a cert file for the certificate authority
+      --client-certificate string      Path to a client certificate file for TLS
+      --client-key string              Path to a client key file for TLS
+      --cluster string                 The name of the kubeconfig cluster to use
+      --context string                 The name of the kubeconfig context to use
+      --grpc-ca string                 CA root file path for connecting to a Falco gRPC server (default "/etc/falco/certs/ca.crt")
+      --grpc-cert string               Cert file path for connecting to a Falco gRPC server (default "/etc/falco/certs/client.crt")
+      --grpc-hostname string           Hostname for connecting to a Falco gRPC server (default "localhost")
+      --grpc-key string                Key file path for connecting to a Falco gRPC server (default "/etc/falco/certs/client.key")
+      --grpc-port uint16               Port for connecting to a Falco gRPC server (default 5060)
+      --grpc-unix-socket string        Unix socket path for connecting to a Falco gRPC server (default "unix:///var/run/falco.sock")
+  -h, --help                           help for test
+      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.
+      --loop                           Run in a loop
+      --match-server-version           Require server version to match client version
+  -n, --namespace string               If present, the namespace scope for this CLI request (default "default")
+      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
+  -s, --server string                  The address and port of the Kubernetes API server
+      --sleep duration                 The length of time to wait before running an action. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means no sleep. (default 1s)
+      --test-timeout duration          Test duration timeout (default 1m0s)
+      --token string                   Bearer token for authentication to the API server
+      --user string                    The name of the kubeconfig user to use
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string     Config file path (default $HOME/.falco-event-generator.yaml if exists)
+  -l, --loglevel string   Log level (default "info")
+```
+
+### SEE ALSO
+
+* [event-generator](event-generator.md)	 - A command line tool to perform a variety of suspect actions.
+