feat(docs): Updating readme to match falco.org

Signed-off-by: Kris Nova <kris@nivenly.com>

.github/stale.yml

@@ -6,6 +6,7 @@ daysUntilClose: 7
 exemptLabels:
   - cncf
   - roadmap
+  - enhancement
   - "help wanted"
 # Label to use when marking an issue as stale
 staleLabel: wontfix
@@ -14,7 +15,5 @@ markComment: >
   This issue has been automatically marked as stale because it has not had
   recent activity. It will be closed if no further activity occurs. Thank you
   for your contributions.
-  Issues labeled "cncf", "roadmap" and "help wanted" will not be automatically closed.
-  Please refer to a maintainer to get such label added if you think this should be kept open.
 # Comment to post when closing a stale issue. Set to `false` to disable
-closeComment: false
+closeComment: false

OWNERS

@@ -3,7 +3,6 @@ approvers:
   - kris-nova
   - leodido
   - mstemm
-  - leogr
 reviewers:
   - fntlnz
   - kaizhe
@@ -11,4 +10,3 @@ reviewers:
   - leodido
   - mfdii
   - mstemm
-  - leogr

README.md

@@ -7,7 +7,7 @@
 
 [![Build Status](https://img.shields.io/circleci/build/github/falcosecurity/falco/master?style=for-the-badge)](https://circleci.com/gh/falcosecurity/falco) [![CII Best Practices Summary](https://img.shields.io/cii/summary/2317?label=CCI%20Best%20Practices&style=for-the-badge)](https://bestpractices.coreinfrastructure.org/projects/2317) [![GitHub](https://img.shields.io/github/license/falcosecurity/falco?style=for-the-badge)](COPYING)
 
-#### Latest releases
+### Download
 
 Read the [change log](CHANGELOG.md).
 
@@ -19,13 +19,15 @@ Read the [change log](CHANGELOG.md).
 
 ---
 
-Falco is a behavioral activity monitor designed to detect anomalous activity in your applications. Falco audits a system at the most fundamental level, the kernel. Falco then enriches this data with other input streams such as container runtime metrics, and Kubernetes metrics. Falco lets you continuously monitor and detect container, application, host, and network activity—all in one place—from one source of data, with one set of rules.
+The Falco Project supports a cloud-native runtime security tool, as well as ancillary projects and integrations that surround it.
+Falco is a daemon that can run either directly on a host, or in a container.
+Falco observes system calls at runtime and builds a model of the system in memory.
+As events occur the events are parsed through a rules engine.
+If a rule is violated, an alert occurs.
+Alerts are dynamic and configurable using the Falco SDKs.
 
-Falco is hosted by the Cloud Native Computing Foundation (CNCF) as a sandbox level project. If you are an organization that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF. For details read the [Falco CNCF project proposal](https://github.com/cncf/toc/tree/master/proposals/falco.adoc).
 
-#### What kind of behaviors can Falco detect?
-
-Falco can detect and alert on any behavior that involves making Linux system calls. Falco alerts can be triggered by the use of specific system calls, their arguments, and by properties of the calling process. For example, Falco can easily detect incidents including but not limited to:
+Falco ships with a sane set of default rules. These rules look for things like:
 
 - A shell is running inside a container.
 - A container is running in privileged mode, or is mounting a sensitive path, such as `/proc`, from the host.

cmake/modules/sysdig.cmake

@@ -26,8 +26,8 @@ file(MAKE_DIRECTORY ${SYSDIG_CMAKE_WORKING_DIR})
 # To update sysdig version for the next release, change the default below
 # In case you want to test against another sysdig version just pass the variable - ie., `cmake -DSYSDIG_VERSION=dev ..`
 if(NOT SYSDIG_VERSION)
-  set(SYSDIG_VERSION "85c88952b018fdbce2464222c3303229f5bfcfad")
-  set(SYSDIG_CHECKSUM "SHA256=6c3f5f2d699c9540e281f50cbc5cb6b580f0fc689798bc65d4a77f57f932a71c")
+  set(SYSDIG_VERSION "422ab408c5706fbdd45432646cc197eb79459169")
+  set(SYSDIG_CHECKSUM "SHA256=367db2a480bca327a46f901bcc8384f151231bcddba88c719a06cf13971f4ab5")
 endif()
 set(PROBE_VERSION "${SYSDIG_VERSION}")
 

docker/falco/docker-entrypoint.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# Copyright (C) 2020 The Falco Authors.
+# Copyright (C) 2019 The Falco Authors.
 #
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,14 +16,10 @@
 # limitations under the License.
 #
 
-# todo(leogr): remove deprecation notice within a couple of releases
-if [[ ! -z "${SKIP_MODULE_LOAD}" ]]; then
-    echo "* SKIP_MODULE_LOAD is deprecated and will be removed soon, use SKIP_DRIVER_LOADER instead"
-fi
 
-# Set the SKIP_DRIVER_LOADER variable to skip loading the driver
+# Set the SKIP_MODULE_LOAD variable to skip loading the kernel module
 
-if [[ -z "${SKIP_DRIVER_LOADER}" ]] && [[ -z "${SKIP_MODULE_LOAD}" ]]; then
+if [[ -z "${SKIP_MODULE_LOAD}" ]]; then
     echo "* Setting up /usr/src links from host"
 
     for i in "$HOST_ROOT/usr/src"/*

docker/local/docker-entrypoint.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# Copyright (C) 2020 The Falco Authors.
+# Copyright (C) 2019 The Falco Authors.
 #
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,9 +17,9 @@
 #
 
 
-# Set the SKIP_DRIVER_LOADER variable to skip loading the driver
+# Set the SKIP_MODULE_LOAD variable to skip loading the kernel module
 
-if [[ -z "${SKIP_DRIVER_LOADER}" ]]; then
+if [[ -z "${SKIP_MODULE_LOAD}" ]]; then
     echo "* Setting up /usr/src links from host"
 
     for i in "$HOST_ROOT/usr/src"/*

falco.yaml

@@ -182,8 +182,7 @@ http_output:
 # grpc:
 #   enabled: true
 #   bind_address: "0.0.0.0:5060"
-#   # when threadiness is 0, Falco sets it by automatically figuring out the number of online cores
-#   threadiness: 0
+#   threadiness: 8
 #   private_key: "/etc/falco/certs/server.key"
 #   cert_chain: "/etc/falco/certs/server.crt"
 #   root_certs: "/etc/falco/certs/ca.crt"
@@ -192,8 +191,7 @@ http_output:
 grpc:
   enabled: false
   bind_address: "unix:///var/run/falco.sock"
-  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
-  threadiness: 0
+  threadiness: 8
 
 # gRPC output service.
 # By default it is off.

rules/k8s_audit_rules.yaml

@@ -44,17 +44,9 @@
   items: ["vpa-recommender", "vpa-updater"]
 
 - list: allowed_k8s_users
-  items:
-    [
-      "minikube",
-      "minikube-user",
-      "kubelet",
-      "kops",
-      "admin",
-      "kube",
-      "kube-proxy",
-      "kube-apiserver-healthcheck",
-      vertical_pod_autoscaler_users,
+  items: [
+    "minikube", "minikube-user", "kubelet", "kops", "admin", "kube", "kube-proxy", "kube-apiserver-healthcheck",
+    vertical_pod_autoscaler_users,
     ]
 
 - rule: Disallowed K8s User
@@ -123,7 +115,6 @@
   condition: ka.uri=/healthz
 
 - rule: Create Disallowed Pod
-  required_engine_version: 5
   desc: >
     Detect an attempt to start a pod with a container image outside of a list of allowed images.
   condition: kevt and pod and kcreate and not allowed_k8s_containers
@@ -133,7 +124,6 @@
   tags: [k8s]
 
 - rule: Create Privileged Pod
-  required_engine_version: 5
   desc: >
     Detect an attempt to start a pod with a privileged container
   condition: kevt and pod and kcreate and ka.req.pod.containers.privileged intersects (true) and not ka.req.pod.containers.image.repository in (falco_privileged_images)
@@ -147,7 +137,6 @@
     (ka.req.pod.volumes.hostpath intersects (/proc, /var/run/docker.sock, /, /etc, /root, /var/run/crio/crio.sock, /home/admin, /var/lib/kubelet, /var/lib/kubelet/pki, /etc/kubernetes, /etc/kubernetes/manifests))
 
 - rule: Create Sensitive Mount Pod
-  required_engine_version: 5
   desc: >
     Detect an attempt to start a pod with a volume from a sensitive host directory (i.e. /proc).
     Exceptions are made for known trusted images.
@@ -159,7 +148,6 @@
 
 # Corresponds to K8s CIS Benchmark 1.7.4
 - rule: Create HostNetwork Pod
-  required_engine_version: 5
   desc: Detect an attempt to start a pod using the host network.
   condition: kevt and pod and kcreate and ka.req.pod.host_network intersects (true) and not ka.req.pod.containers.image.repository in (falco_hostnetwork_images)
   output: Pod started using host network (user=%ka.user.name pod=%ka.resp.name ns=%ka.target.namespace images=%ka.req.pod.containers.image)
@@ -167,13 +155,10 @@
   source: k8s_audit
   tags: [k8s]
 
-- macro: user_known_node_port_service
-  condition: (k8s_audit_never_true)
-
 - rule: Create NodePort Service
   desc: >
     Detect an attempt to start a service with a NodePort service type
-  condition: kevt and service and kcreate and ka.req.service.type=NodePort and not user_known_node_port_service
+  condition: kevt and service and kcreate and ka.req.service.type=NodePort
   output: NodePort Service Created (user=%ka.user.name service=%ka.target.name ns=%ka.target.namespace ports=%ka.req.service.ports)
   priority: WARNING
   source: k8s_audit
@@ -190,7 +175,7 @@
 
 - rule: Create/Modify Configmap With Private Credentials
   desc: >
-    Detect creating/modifying a configmap containing a private credential (aws key, password, etc.)
+     Detect creating/modifying a configmap containing a private credential (aws key, password, etc.)
   condition: kevt and configmap and kmodify and contains_private_credentials
   output: K8s configmap with private credential (user=%ka.user.name verb=%ka.verb configmap=%ka.req.configmap.name config=%ka.req.configmap.obj)
   priority: WARNING
@@ -216,13 +201,10 @@
 # attach request was created privileged or not. For now, we have a
 # less severe rule that detects attaches/execs to any pod.
 
-- macro: user_known_exec_pod_activities
-  condition: (k8s_audit_never_true)
-
 - rule: Attach/Exec Pod
   desc: >
     Detect any attempt to attach/exec to a pod
-  condition: kevt_started and pod_subresource and kcreate and ka.target.subresource in (exec,attach) and not user_known_exec_pod_activities
+  condition: kevt_started and pod_subresource and kcreate and ka.target.subresource in (exec,attach)
   output: Attach/Exec to pod (user=%ka.user.name pod=%ka.target.name ns=%ka.target.namespace action=%ka.target.subresource command=%ka.uri.param[command])
   priority: NOTICE
   source: k8s_audit
@@ -240,32 +222,19 @@
   source: k8s_audit
   tags: [k8s]
 
-- list: user_trusted_image_list
-  items: []
-
-- macro: trusted_pod
-  condition: (ka.req.pod.containers.image.repository in (user_trusted_image_list))
-
 # Detect any new pod created in the kube-system namespace
 - rule: Pod Created in Kube Namespace
-  required_engine_version: 5
   desc: Detect any attempt to create a pod in the kube-system or kube-public namespaces
-  condition: kevt and pod and kcreate and ka.target.namespace in (kube-system, kube-public) and not trusted_pod
+  condition: kevt and pod and kcreate and ka.target.namespace in (kube-system, kube-public)
   output: Pod created in kube namespace (user=%ka.user.name pod=%ka.resp.name ns=%ka.target.namespace images=%ka.req.pod.containers.image)
   priority: WARNING
   source: k8s_audit
   tags: [k8s]
 
-- list: user_known_sa_list
-  items: []
-
-- macro: trusted_sa
-  condition: (ka.target.name in (user_known_sa_list))
-
 # Detect creating a service account in the kube-system/kube-public namespace
 - rule: Service Account Created in Kube Namespace
   desc: Detect any attempt to create a serviceaccount in the kube-system or kube-public namespaces
-  condition: kevt and serviceaccount and kcreate and ka.target.namespace in (kube-system, kube-public) and response_successful and not trusted_sa
+  condition: kevt and serviceaccount and kcreate and ka.target.namespace in (kube-system, kube-public) and response_successful
   output: Service account created in kube namespace (user=%ka.user.name serviceaccount=%ka.target.name ns=%ka.target.namespace)
   priority: WARNING
   source: k8s_audit
@@ -293,7 +262,6 @@
   tags: [k8s]
 
 - rule: ClusterRole With Wildcard Created
-  required_engine_version: 5
   desc: Detect any attempt to create a Role/ClusterRole with wildcard resources or verbs
   condition: kevt and (role or clusterrole) and kcreate and (ka.req.role.rules.resources intersects ("*") or ka.req.role.rules.verbs intersects ("*"))
   output: Created Role/ClusterRole with wildcard (user=%ka.user.name role=%ka.target.name rules=%ka.req.role.rules)
@@ -306,7 +274,6 @@
     (ka.req.role.rules.verbs intersects (create, update, patch, delete, deletecollection))
 
 - rule: ClusterRole With Write Privileges Created
-  required_engine_version: 5
   desc: Detect any attempt to create a Role/ClusterRole that can perform write-related actions
   condition: kevt and (role or clusterrole) and kcreate and writable_verbs
   output: Created Role/ClusterRole with write privileges (user=%ka.user.name role=%ka.target.name rules=%ka.req.role.rules)
@@ -315,7 +282,6 @@
   tags: [k8s]
 
 - rule: ClusterRole With Pod Exec Created
-  required_engine_version: 5
   desc: Detect any attempt to create a Role/ClusterRole that can exec to pods
   condition: kevt and (role or clusterrole) and kcreate and ka.req.role.rules.resources intersects ("pods/exec")
   output: Created Role/ClusterRole with pod exec privileges (user=%ka.user.name role=%ka.target.name rules=%ka.req.role.rules)
@@ -478,26 +444,20 @@
   source: k8s_audit
   tags: [k8s]
 
+
 # This macro disables following rule, change to k8s_audit_never_true to enable it
 - macro: allowed_full_admin_users
   condition: (k8s_audit_always_true)
 
 # This list includes some of the default user names for an administrator in several K8s installations
 - list: full_admin_k8s_users
-  items:
-    [
-      "admin",
-      "kubernetes-admin",
-      "kubernetes-admin@kubernetes",
-      "kubernetes-admin@cluster.local",
-      "minikube-user",
-    ]
+  items: ["admin", "kubernetes-admin",  "kubernetes-admin@kubernetes", "kubernetes-admin@cluster.local", "minikube-user"]
 
-# This rules detect an operation triggered by an user name that is
-# included in the list of those that are default administrators upon
-# cluster creation. This may signify a permission setting too broader.
-# As we can't check for role of the user on a general ka.* event, this
-# may or may not be an administrator. Customize the full_admin_k8s_users
+# This rules detect an operation triggered by an user name that is 
+# included in the list of those that are default administrators upon 
+# cluster creation. This may signify a permission setting too broader. 
+# As we can't check for role of the user on a general ka.* event, this 
+# may or may not be an administrator. Customize the full_admin_k8s_users 
 # list to your needs, and activate at your discrection.
 
 # # How to test:
@@ -516,6 +476,8 @@
   source: k8s_audit
   tags: [k8s]
 
+
+
 - macro: ingress
   condition: ka.target.resource=ingresses
 
@@ -547,10 +509,12 @@
   output: >
     K8s Ingress Without TLS Cert Created (user=%ka.user.name ingress=%ka.target.name
     namespace=%ka.target.namespace)
-  source: k8s_audit
+  source: k8s_audit    
   priority: WARNING
   tags: [k8s, network]
 
+
+
 - macro: node
   condition: ka.target.resource=nodes
 
@@ -593,3 +557,4 @@
   priority: WARNING
   source: k8s_audit
   tags: [k8s]
+

test/rules/k8s_audit/allow_nginx_container.yaml

@@ -1,2 +1,3 @@
 - macro: allowed_k8s_containers
   condition: (ka.req.pod.containers.image.repository in (nginx))
+

userspace/engine/falco_utils.cpp

@@ -52,12 +52,6 @@ std::string wrap_text(const std::string& str, uint32_t initial_pos, uint32_t ind
 	return ret;
 }
 
-uint32_t hardware_concurrency()
-{
-	auto hc = std::thread::hardware_concurrency();
-	return hc ? hc : 1;
-}
-
 void readfile(const std::string& filename, std::string& data)
 {
 	std::ifstream file(filename.c_str(), std::ios::in);

userspace/engine/falco_utils.h

@@ -21,7 +21,6 @@ limitations under the License.
 #include <fstream>
 #include <iostream>
 #include <string>
-#include <thread>
 #include <nonstd/string_view.hpp>
 
 #pragma once
@@ -35,9 +34,6 @@ namespace utils
 std::string wrap_text(const std::string& str, uint32_t initial_pos, uint32_t indent, uint32_t line_len);
 
 void readfile(const std::string& filename, std::string& data);
-
-uint32_t hardware_concurrency();
-
 namespace network
 {
 static const std::string UNIX_SCHEME("unix://");

userspace/engine/json_evt.cpp

@@ -45,7 +45,7 @@ const json &json_event::jevt()
 	return m_jevt;
 }
 
-uint64_t json_event::get_ts() const
+uint64_t json_event::get_ts()
 {
 	return m_event_ts;
 }

userspace/engine/json_evt.h

@@ -38,14 +38,14 @@ public:
 	void set_jevt(nlohmann::json &evt, uint64_t ts);
 	const nlohmann::json &jevt();
 
-	uint64_t get_ts() const;
+	uint64_t get_ts();
 
-	inline uint16_t get_source() const
+	inline uint16_t get_source()
 	{
 		return ESRC_K8S_AUDIT;
 	}
 
-	inline uint16_t get_type() const
+	inline uint16_t get_type()
 	{
 		// All k8s audit events have the single tag "1". - see falco_engine::process_k8s_audit_event
 		return 1;

userspace/falco/configuration.cpp

@@ -1,5 +1,5 @@
 /*
-Copyright (C) 2020 The Falco Authors.
+Copyright (C) 2019 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.
@@ -20,7 +20,6 @@ limitations under the License.
 #include <sys/types.h>
 #include <sys/stat.h>
 #include <unistd.h>
-#include "falco_utils.h"
 
 #include "configuration.h"
 #include "logger.h"
@@ -149,12 +148,11 @@ void falco_configuration::init(string conf_filename, list<string> &cmdline_optio
 
 	m_grpc_enabled = m_config->get_scalar<bool>("grpc", "enabled", false);
 	m_grpc_bind_address = m_config->get_scalar<string>("grpc", "bind_address", "0.0.0.0:5060");
-	m_grpc_threadiness = m_config->get_scalar<uint32_t>("grpc", "threadiness", 0);
+	m_grpc_threadiness = m_config->get_scalar<uint32_t>("grpc", "threadiness", 8); // todo > limit it to avoid overshubscription? std::thread::hardware_concurrency()
 	if(m_grpc_threadiness == 0)
 	{
-		m_grpc_threadiness = falco::utils::hardware_concurrency();
+		throw logic_error("error reading config file (" + m_config_file + "): gRPC threadiness must be greater than 0");
 	}
-	// todo > else limit threadiness to avoid oversubscription?
 	m_grpc_private_key = m_config->get_scalar<string>("grpc", "private_key", "/etc/falco/certs/server.key");
 	m_grpc_cert_chain = m_config->get_scalar<string>("grpc", "cert_chain", "/etc/falco/certs/server.crt");
 	m_grpc_root_certs = m_config->get_scalar<string>("grpc", "root_certs", "/etc/falco/certs/ca.crt");
@@ -346,4 +344,4 @@ void falco_configuration::set_cmdline_option(const string &opt)
 	{
 		m_config->set_scalar(keyval.first, keyval.second);
 	}
-}
+}

userspace/falco/configuration.h

@@ -206,7 +206,7 @@ public:
 	bool m_time_format_iso_8601;
 
 	bool m_grpc_enabled;
-	uint32_t m_grpc_threadiness;
+	int m_grpc_threadiness;
 	std::string m_grpc_bind_address;
 	std::string m_grpc_private_key;
 	std::string m_grpc_cert_chain;

userspace/falco/falco.cpp

@@ -140,9 +140,9 @@ static void usage()
 	   " -P, --pidfile <pid_file>      When run as a daemon, write pid to specified file\n"
        " -r <rules_file>               Rules file/directory (defaults to value set in configuration file, or /etc/falco_rules.yaml).\n"
        "                               Can be specified multiple times to read from multiple files/directories.\n"
-	   " -s <stats_file>               If specified, append statistics related to Falco's reading/processing of events\n"
-	   "                               to this file (only useful in live mode).\n"
-	   " --stats-interval <msec>       When using -s <stats_file>, write statistics every <msec> ms.\n"
+	   " -s <stats_file>               If specified, write statistics related to falco's reading/processing of events\n"
+	   "                               to this file. (Only useful in live mode).\n"
+	   " --stats_interval <msec>       When using -s <stats_file>, write statistics every <msec> ms.\n"
 	   "                               This uses signals, so don't recommend intervals below 200 ms.\n"
 	   "                               Defaults to 5000 (5 seconds).\n"
 	   " -S <len>, --snaplen <len>\n"
@@ -479,7 +479,7 @@ int falco_init(int argc, char **argv)
         {"print-base64", no_argument, 0, 'b'},
         {"print", required_argument, 0, 'p'},
         {"snaplen", required_argument, 0, 'S'},
-        {"stats-interval", required_argument, 0},
+        {"stats_interval", required_argument, 0},
         {"support", no_argument, 0},
         {"unbuffered", no_argument, 0, 'U'},
         {"validate", required_argument, 0, 'V'},
@@ -646,7 +646,7 @@ int falco_init(int argc, char **argv)
 						list_flds_source = optarg;
 					}
 				}
-				else if (string(long_options[long_index].name) == "stats-interval")
+				else if (string(long_options[long_index].name) == "stats_interval")
 				{
 					stats_interval = atoi(optarg);
 				}
@@ -1206,7 +1206,6 @@ int falco_init(int argc, char **argv)
 		// gRPC server
 		if(config.m_grpc_enabled)
 		{
-			falco_logger::log(LOG_INFO, "gRPC server threadiness equals to " + to_string(config.m_grpc_threadiness) + "\n");
 			// TODO(fntlnz,leodido): when we want to spawn multiple threads we need to have a queue per thread, or implement
 			// different queuing mechanisms, round robin, fanout? What we want to achieve?
 			grpc_server.init(
@@ -1264,7 +1263,7 @@ int falco_init(int argc, char **argv)
 		// Honor -M also when using a trace file.
 		// Since inspection stops as soon as all events have been consumed
 		// just await the given duration is reached, if needed.
-		if(!trace_filename.empty() && duration_to_tot>0)
+		if(!trace_filename.empty() && duration_to_tot>0) 
 		{
 			std::this_thread::sleep_for(std::chrono::seconds(duration_to_tot));
 		}

userspace/falco/lua/output.lua

@@ -18,7 +18,7 @@ local mod = {}
 local outputs = {}
 
 function mod.stdout(event, rule, source, priority, priority_num, msg, format, hostname, options)
-   mod.stdout_message(priority, priority_num, msg, options)
+   mod.stdout_message(priority, priority_num, msg, outputs)
 end
 
 function mod.stdout_message(priority, priority_num, msg, options)

userspace/falco/statsfilewriter.cpp

@@ -58,8 +58,8 @@ bool StatsFileWriter::init(sinsp *inspector, string &filename, uint32_t interval
 		return false;
 	}
 
-	timer.it_value.tv_sec = interval_msec / 1000;
-	timer.it_value.tv_usec = (interval_msec % 1000) * 1000;
+	timer.it_value.tv_sec = 0;
+	timer.it_value.tv_usec = interval_msec * 1000;
 	timer.it_interval = timer.it_value;
 	if (setitimer(ITIMER_REAL, &timer, NULL) == -1)
 	{