update: refine engine checksum docs and scoping

Signed-off-by: Jason Dellaluce <jasondellaluce@gmail.com>

.github/workflows/ci.yml

@@ -71,7 +71,7 @@ jobs:
 
       - name: Check Engine checksum
         run: |
-          prev_hash=$(grep FALCO_FIELDS_CHECKSUM "./userspace/engine/falco_engine_version.h" | awk '{print $3}' | sed -e 's/"//g')
+          prev_hash=$(grep FALCO_ENGINE_CHECKSUM "./userspace/engine/falco_engine_version.h" | awk '{print $3}' | sed -e 's/"//g')
           cur_hash=$(echo "${{ needs.build-dev.outputs.cmdout }}" | cut -d ' ' -f 2)
           
           if [ $prev_hash != $cur_hash ]; then
@@ -93,7 +93,7 @@ jobs:
 
       - name: Check Engine version
         run: |
-          base_hash=$(grep FALCO_FIELDS_CHECKSUM "./userspace/engine/falco_engine_version.h" | awk '{print $3}' | sed -e 's/"//g')
+          base_hash=$(grep FALCO_ENGINE_CHECKSUM "./userspace/engine/falco_engine_version.h" | awk '{print $3}' | sed -e 's/"//g')
           base_engine_ver=$(grep FALCO_ENGINE_VERSION "./userspace/engine/falco_engine_version.h" | awk '{print $3}' | sed -e 's/(//g' -e 's/)//g')
 
           cur_hash=$(echo "${{ needs.build-dev.outputs.cmdout }}" | cut -d ' ' -f 2)

RELEASE.md

@@ -217,7 +217,7 @@ This section provides more details around the versioning of the components that
 
 ### Falco repo (this repo)
 - Falco version is a git tag (`x.y.z`), see [Procedures](#procedures) section. Note that the Falco version is a sem-ver-like schema, but not fully compatible with sem-ver.
-- [FALCO_ENGINE_VERSION](https://github.com/falcosecurity/falco/blob/master/userspace/engine/falco_engine_version.h) is not sem-ver and must be bumped either when a backward incompatible change has been introduced to the rules files syntax and/or `FALCO_FIELDS_CHECKSUM` computed via `falco --list -N | sha256sum` has changed. The primary idea is that when new filter / display fields (see currently supported [Falco fields](https://falco.org/docs/rules/supported-fields/)) are introduced, a version change indicates that these fields were not available in previous engine versions. See the [rules release guidelines](https://github.com/falcosecurity/rules/blob/main/RELEASE.md#versioning-a-ruleset) to understand how this affects the versioning of Falco rules. Breaking changes introduced in the Falco engine are not necessarily tied to the drivers or libs versions. Lastly, `FALCO_ENGINE_VERSION` is typically incremented once during a Falco release cycle, while `FALCO_FIELDS_CHECKSUM` is bumped whenever necessary during the development and testing phases of the release cycle.
+- [FALCO_ENGINE_VERSION](https://github.com/falcosecurity/falco/blob/master/userspace/engine/falco_engine_version.h) is not sem-ver and must be bumped either when a backward incompatible change has been introduced to the rules files syntax and/or `FALCO_ENGINE_CHECKSUM` computed via `falco --list -N | sha256sum` has changed. The primary idea is that when new filter / display fields (see currently supported [Falco fields](https://falco.org/docs/rules/supported-fields/)) are introduced, a version change indicates that these fields were not available in previous engine versions. See the [rules release guidelines](https://github.com/falcosecurity/rules/blob/main/RELEASE.md#versioning-a-ruleset) to understand how this affects the versioning of Falco rules. Breaking changes introduced in the Falco engine are not necessarily tied to the drivers or libs versions. Lastly, `FALCO_ENGINE_VERSION` is typically incremented once during a Falco release cycle, while `FALCO_ENGINE_CHECKSUM` is bumped whenever necessary during the development and testing phases of the release cycle.
 - During development and release preparation, libs and driver reference commits are often bumped in Falco's cmake setup ([falcosecurity-libs cmake](https://github.com/falcosecurity/falco/blob/master/cmake/modules/falcosecurity-libs.cmake#L30) and [driver cmake](https://github.com/falcosecurity/falco/blob/master/cmake/modules/driver.cmake#L29)) in order to merge new Falco features. In practice, they are mostly bumped at the same time referencing the same `libs` commit. However, for the official Falco build `FALCOSECURITY_LIBS_VERSION` flag that references the stable libs version is used (read below).
 - Similarly, Falco plugins versions are bumped in Falco's cmake setup ([plugins cmake](https://github.com/falcosecurity/falco/blob/master/cmake/modules/plugins.cmake)) and those versions are the ones used for the Falco release.
 - At release time Plugin, Libs and Driver versions are compatible with Falco.

userspace/engine/falco_engine_version.h

@@ -1,5 +1,5 @@
 /*
-Copyright (C) 2021 The Falco Authors.
+Copyright (C) 2023 The Falco Authors.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -14,11 +14,16 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// The version of rules/filter fields/etc supported by this Falco
-// engine.
+// The version of this Falco engine.
 #define FALCO_ENGINE_VERSION (19)
 
 // This is the result of running "falco --list -N | sha256sum" and
 // represents the fields supported by this version of Falco. It's used
 // at build time to detect a changed set of fields.
-#define FALCO_FIELDS_CHECKSUM "1d7f91f22d40074c56c705f5e494b7fae51aee1b7ababc8c70cfa63c6d6671c2"
+
+// This is the result of running the following command:
+//   echo $(falco -c ./falco.yaml --version | grep 'Engine:' | awk '{print $2}') $(echo $(falco -c ./falco.yaml --version | grep 'Schema version:' | awk '{print $3}') $(falco -c ./falco.yaml --list --markdown | grep '^`' | sort) $(falco -c ./falco.yaml --list-syscall-events | sort) | sha256sum)
+// It represents the fields supported by this version of Falco,
+// the event types, and the underlying driverevent schema. It's used to
+// detetect changes in engine version in our CI jobs.
+#define FALCO_ENGINE_CHECKSUM "1d7f91f22d40074c56c705f5e494b7fae51aee1b7ababc8c70cfa63c6d6671c2"

userspace/falco/grpc_server_impl.cpp

@@ -77,7 +77,7 @@ void falco::grpc::server_impl::version(const context& ctx, const version::reques
 	version = FALCO_VERSION;
 
 	res.set_engine_version(FALCO_ENGINE_VERSION);
-	res.set_engine_fields_checksum(FALCO_FIELDS_CHECKSUM); 
+	res.set_engine_fields_checksum(FALCO_ENGINE_CHECKSUM); 
 
 	res.set_major(FALCO_VERSION_MAJOR);
 	res.set_minor(FALCO_VERSION_MINOR);