new(anomalydetection): init plugin / start dev

Signed-off-by: Melissa Kilby <[email protected]>

plugins/anomalydetection/.gitignore

@@ -0,0 +1,6 @@
+*.so
+*.a
+*.o
+.vscode
+build*
+libanomalydetection.so

plugins/anomalydetection/CMakeLists.txt

@@ -0,0 +1,43 @@
+cmake_minimum_required(VERSION 3.22)
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules")
+
+option(BUILD_TESTS "Enable tests" ON)
+
+# Project metadata
+project(
+  anomalydetection
+  VERSION 0.1.0
+  DESCRIPTION "Falco Anomaly Detection Plugin"
+  LANGUAGES CXX)
+
+# Dependencies
+include(FetchContent)
+include(plugin-sdk-cpp)
+include(libs) # Temporarily include libs for initial dev
+include(xxhash)
+
+# Project target
+file(GLOB_RECURSE anomalydetection_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp")
+add_library(anomalydetection SHARED ${anomalydetection_SOURCES} )
+set_target_properties(anomalydetection PROPERTIES CXX_EXTENSIONS OFF)
+
+# Project compilation options
+target_compile_options(anomalydetection PRIVATE "-fPIC")
+target_compile_options(anomalydetection PRIVATE "-Wl,-z,relro,-z,now")
+target_compile_options(anomalydetection PRIVATE "-fstack-protector-strong")
+# When compiling in Debug mode, this will define the DEBUG symbol for use in your code
+target_compile_options(anomalydetection PUBLIC "$<$<CONFIG:DEBUG>:-DDEBUG>")
+target_compile_features(anomalydetection PUBLIC cxx_std_17)
+
+# Project includes
+target_include_directories(
+  anomalydetection PRIVATE "${PLUGIN_SDK_INCLUDE}" "${XXHASH_INCLUDE}" "${LIBS_INCLUDE}")
+
+# Project linked libraries
+target_link_libraries(anomalydetection ${_REFLECTION})
+
+# Testing
+# if(BUILD_TESTS)
+#   add_subdirectory(test)
+# endif()

plugins/anomalydetection/Makefile

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (C) 2024 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. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+NAME := anomalydetection
+OUTPUT := lib$(NAME).so
+
+all: $(OUTPUT)
+
+clean:
+	rm -rf build $(OUTPUT)
+# Temporarily include libs for initial dev
+$(OUTPUT):
+	mkdir -p build \
+	&& cd build \
+	&& cmake \
+	-DCMAKE_BUILD_TYPE=Release \
+	-DMINIMAL_BUILD=ON \
+	-DUSE_BUNDLED_LIBELF=OFF \
+	-DCREATE_TEST_TARGETS=OFF \
+	../ \
+	&& make -j6 anomalydetection \
+	&& cp ./$(OUTPUT) ../$(OUTPUT)
+
+readme:
+	@$(READMETOOL) -p ./$(OUTPUT) -f README.md

plugins/anomalydetection/README.md

@@ -0,0 +1,95 @@
+# Falcosecurity `anomalydetection` Plugin
+
+This `anomalydetection` plugin has been created upon this [Proposal](https://github.com/falcosecurity/falco/blob/master/proposals/20230620-anomaly-detection-framework.md).
+
+## Introduction
+
+The `anomalydetection` plugin enhances {syscall} event analysis by incorporating anomaly detection estimates for probabilistic filtering.
+
+### Functionality
+
+The initial scope will focus exclusively on "CountMinSketch Powered Probabilistic Counting and Filtering" for a subset of syscalls and a selection of options to define behavior profiles. The primary objective of this new framework is to offer tangible advantages in real-world production environments and substantially improve the usability of standard Falco rules. Essentially, this framework eliminates the requirement for meticulous tuning of individual rules and facilitates the utilization of probabilistic count estimates to alleviate the impact of noisy rules. Additionally, it enables the creation of broader Falco rules. Read more in the [Proposal](https://github.com/falcosecurity/falco/blob/master/proposals/20230620-anomaly-detection-framework.md).
+
+### Plugin Official Name
+
+`anomalydetection`
+
+## Capabilities
+
+The `anomalydetection` plugin implements 2 capabilities:
+
+* `extraction`
+* `parsing`
+
+## Supported Fields
+
+Here is the current set of supported fields:
+
+<!-- README-PLUGIN-FIELDS -->
+|       NAME        |   TYPE   |       ARG       |                               DESCRIPTION                               |
+|-------------------|----------|-----------------|-------------------------------------------------------------------------|
+| `anomalydetection.count_min_sketch` | `uint64` | Key, Optional | Count Min Sketch Estimate according to the specified behavior profile for a predefined set of {syscalls} events. Access different behavior profiles/sketches using indices. For instance, anomalydetection.count_min_sketch[0] retrieves the first behavior profile defined in the plugins' `init_config`. |
+<!-- /README-PLUGIN-FIELDS -->
+
+## Usage
+
+### Configuration
+
+Here's an example of configuration of `falco.yaml`:
+
+```yaml
+plugins:
+  - name: anomalydetection
+    library_path: libanomalydetection.so
+    init_config:
+      n_sketches: 3
+
+load_plugins: [anomalydetection]
+```
+
+**Open Parameters**:
+
+This plugin does not have open params.
+
+**Rules**
+
+This plugin does not provide any custom rules. You can use the default Falco ruleset and add the necessary `anomalydetection` fields as output fields to obtain the Count Min Sketch estimates and/or use them in the familiar rules filter condition.
+
+Example of a standard Falco rule using the `anomalydetection` fields:
+
+```yaml
+- macro: spawned_process
+  condition: (evt.type in (execve, execveat) and evt.dir=<)
+- rule: execve count_min_sketch test
+  desc: "execve count_min_sketch test"
+  condition: spawned_process and proc.name=cat and anomalydetection.count_min_sketch > 10
+  output: '%anomalydetection.count_min_sketch %proc.pid %proc.ppid %proc.name %user.loginuid %user.name %user.uid %proc.cmdline %container.id %evt.type %evt.res %proc.cwd %proc.sid %proc.exepath %container.image.repository'
+  priority: NOTICE
+  tags: [maturity_sandbox, host, container, process, anomalydetection]
+```
+
+__NOTE__: Ensure you regularly execute `cat` commands. Once you have done so frequently enough, logs will start to appear. Alternatively, perform an inverse test to observe how quickly a very noisy rule gets silenced.
+
+### Running
+
+This plugin requires Falco with version >= **0.37.0**.
+Modify the `falco.yaml` with the provided [configuration](#configuration) above and you are ready to go!
+
+```shell
+sudo falco -c falco.yaml -r falco_rules.yaml
+```
+
+## Local Development
+
+### Build
+
+```bash
+git clone https://github.com/falcosecurity/plugins.git
+cd plugins/anomalydetection
+rm -f libanomalydetection.so; 
+rm -f build/libanomalydetection.so; 
+make;
+# Copy the shared library to the expected location for `falco.yaml`, which is `library_path: libanomalydetection.so`
+sudo mkdir -p /usr/share/falco/plugins/;
+sudo cp -f libanomalydetection.so /usr/share/falco/plugins/libanomalydetection.so;
+```

plugins/anomalydetection/cmake/modules/libs.cmake

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (C) 2024 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. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+message(STATUS "Fetching libs at 'https://github.com/falcosecurity/libs.git'")
+
+FetchContent_Declare(
+  libs
+  GIT_REPOSITORY https://github.com/falcosecurity/libs.git
+  GIT_TAG 844b275c52ee0ae5dab928c1d2f1a1b529a15ce7
+  CONFIGURE_COMMAND "" BUILD_COMMAND "")
+
+FetchContent_MakeAvailable(libs)
+set(LIBS_INCLUDE "${libs_SOURCE_DIR}")
+message(STATUS "Using xxhash include at '${LIBS_INCLUDE}'")

plugins/anomalydetection/cmake/modules/plugin-sdk-cpp.cmake

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (C) 2024 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. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+message(
+  STATUS
+    "Fetching plugin-sdk-cpp at 'https://github.com/falcosecurity/plugin-sdk-cpp.git'"
+)
+
+FetchContent_Declare(
+  plugin-sdk-cpp
+  GIT_REPOSITORY https://github.com/falcosecurity/plugin-sdk-cpp.git
+  GIT_TAG fddbaa63a09e3e78287f41a6a9947d91260c16ab)
+
+FetchContent_MakeAvailable(plugin-sdk-cpp)
+set(PLUGIN_SDK_INCLUDE "${plugin-sdk-cpp_SOURCE_DIR}/include")
+message(STATUS "Using plugin-sdk-cpp include at '${PLUGIN_SDK_INCLUDE}'")

plugins/anomalydetection/cmake/modules/xxhash.cmake

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (C) 2024 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. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+message(
+  STATUS
+    "Fetching xxhash at 'https://raw.githubusercontent.com/Cyan4973/xxHash/v0.8.2/xxhash.h'"
+)
+
+FetchContent_Declare(
+  # BSD 2-Clause License
+  xxhash
+  URL "https://raw.githubusercontent.com/Cyan4973/xxHash/v0.8.2/xxhash.h"
+  URL_HASH SHA256=be275e9db21a503c37f24683cdb4908f2370a3e35ab96e02c4ea73dc8e399c43 
+  DOWNLOAD_NAME "xxhash.h"
+  DOWNLOAD_NO_EXTRACT TRUE
+)
+
+FetchContent_MakeAvailable(xxhash)
+set(XXHASH_INCLUDE "${xxhash_SOURCE_DIR}")
+message(STATUS "Using xxhash include at '${XXHASH_INCLUDE}'")