Emit a warning when a rule with a condition using "evt.dir" field is
encountered.
The direction have been deprecated in the scope of enter event
suppression initiative.
Signed-off-by: Iacopo Rozzo <iacopo.rozzo@iacopo.rozzo>
User can configure a list of actions that are taken when Falco
detects a threshold exceeding value in drop statistics.
However, the logic that handles the list of configured actions
is designed to process only a single action; it takes only the
first action of the list. This approach has the problem that the
order of the actions comes as the deciding factor in choosing
which action is taken in case there are more than one action.
This fix enables Falco to process all actions on the list.
Signed-off-by: Tero Kauppinen <tero.kauppinen@est.tech>
Enter events are no longer tracked by the Falco libs, this change
deprecates the Prometheus metrics related to enter event drops.
Signed-off-by: Iacopo Rozzo <iacopo@sysdig.com>
Make Falco's libs internal auto thread purging interval and timeout
configurable and set their default values to 5 minutes. This helps
controlling the memory impact of process exit events dropping and
events re-ordering.
Signed-off-by: Leonardo Di Giovanna <leonardodigiovanna1@gmail.com>
When there is no work to do, i.e. when all config watching is disabled,
there is no need to keep the restart_handler running. Disable it in this
case.
This is helpful to do on nodes where there is little to no headroom in
terms of open inotify watches (as per the inotify/max_user_instances
configuration), as can happen on nodes populated with other software
that also watch the filesystem for changes. If Falco is run on such a
node, it may fail to start due to functionality the app does not even
intend on using.
This has one change in terms of behaviour, however: the dry-run restarts
will no longer occur. As there is still never going to happen a real
restart, I understand it as unlikely for there to be a proper need for
dry-run restarts.
Signed-off-by: Mariell Hoversholm <mariell@grafana.com>
As buster reached its EOL, the official debian repo URL doesn't
host anymore buster packages info. For this reason, change the URLs
to point to the `20250630T203427Z` snapshot, which still contains
them.
Signed-off-by: Leonardo Di Giovanna <leonardodigiovanna1@gmail.com>
In case multiple sources are enabled, each source has its own `libs_metrics_collector`
with correct flags, so that it can retrieve all metrics.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Moreover, rename `falco_metrics::` methods to better expose
they return prometheus metrics.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Co-authored-by: Samuel Gaist <samuel.gaist@idiap.ch>
Refactor `::to_text` a bit to be more clear.
Also, we will push agent_info and machine_info only for the first
inspector that exposes them, to avoid duplicated entries in the prometheus text.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
* For consistency don't make first run metrics log special
* Remove firt tick variable altogether to enable metrics logging immediately after startup/reload
Co-authored-by: Federico Di Pierro <nierro92@gmail.com>
Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
distributions such as SLES. The cmake file for c-ares sets
'CARES_LIB' destination directory to '${CARES_SRC}/lib' but when the
bundled c-ares is compiled it produces a binary which is placed in
the '${CARES_SRC}/lib64' directory.
This is due to the fact that the bundled c-ares expands
${CMAKE_INSTALL_LIBDIR} to 'lib64' and not to 'lib' which is
expected by 'CARES_LIB'.
The fix is to enforce the building process of the bundled c-ares
to place the produced binary in 'lib'.
Signed-off-by: Tero Kauppinen <tero.kauppinen@est.tech>
Merge-strategy for included config files must now be
specified as yaml map of the form:
- path: foo
strategy: bar
If `strategy` is omitted, or the old `string-only` form is used,
`append` strategy is enforced.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
By default we now use the `append` merge-strategy:
* existing sequence keys will be appended
* existing scalar keys will be overridden
* non-existing keys will be added
We also have an `override` merge-strategy:
* existing keys will be overridden
* non-existing keys will be added
Finally, there is an `add-only` merge-strategy:
* existing keys will be ignored
* non-existing keys will be added
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Refs #3503: we need it because rpm pre/post install/remove scripts
are evaluated at rpm package building time.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Defining `exceptions` with empty `values` is a legitimate use case since the values can be added to another rules file. Even when values are not populated elsewhere, Falco can work without issues; that's the reason why the `values` field is not required. With this change, we avoid emitting useless validation warnings in situations where exceptions are just defined but not actually used because values are not being provided.
Signed-off-by: Leonardo Grasso <me@leonardograsso.com>
Container plugin cannot be dynamically loaded on musl build, therefore
some falcosecurity/testing tests are failing on it.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Also, remove `container_id container_name` fields from `-pc` output.
These fields are now automatically appended since the `container` plugin
marks them as suggested.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Also, default falco.yaml will only host container plugin configuration but won't enable the plugin.
Instead, a configuration override file will be installed only on linux non-musl deployments, enabled the plugin.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Move actions not requiring config to be loaded before `load_config`
action. This avoid resource waste. Notably, `print_help` is
promoted as first execution action. Moreover, set actions lists to
constant expressions.
Signed-off-by: Leonardo Di Giovanna <leonardodigiovanna1@gmail.com>
Add additional unit tests to verify that rule loading fails when a
second rules object has a different source but the name of an existing
rules object.
Also add tests for additional rules having an empty source.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
In places where a second rule definition might replace, append to, or
replace items from a base rule, ensure that the source of the second
rule definiton matches the first.
This already existed for defines, but for other changes. There was a
bug where a second definition might exist for a different source, but
the additional rule was used anyway.
This now returns the same error for these other changes e.g. "Rule has
been re-defined..." as define.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
It's possible that someone might want to override a property for a
non-syscall rule source. To assist in this, decode any source property
for rules with append/override and save it in the rule_update_info
object. For the source property only, the value for source can be
empty e.g. 'source: ' or an empty string e.g. 'source: ""'. Both of
those are considered valid but result in an empty source.
A later change will ensure that the sources match up when
appending/redefining/overriding/enabling.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add a test for checking that compile_output::clone() returns equal
values, specifically in the case of derived values.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add an equality operator for indexed_vector.
As indexed_vectors commonly hold falco lists/macros/rules, also add
equality operators for those structs. For condition/sinsp_filter
shared_ptrs, the operator checks that the shared_ptrs point to the
same underlying memory.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add a clone() method that can be overridden by subclasses. This allows
copying compile state when needed in a way that preserves
polymorphism.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Introduce host_netinfo stats family to hold information regarding host
networking. At the moment, it only provides ipv4 and ipv6 addresses
list for each interface available on the host. The naming schema for
the introduced stats is
falco.host_netinfo.interfaces.<ifname>.protocols.<ipv4|ipv6>.addresses.
Signed-off-by: Leonardo Di Giovanna <leonardodigiovanna1@gmail.com>
Using JSON as value prevents any meaningful aggregation for the stats.
Splitting these information into multiple labels can drastically
increase the number of dimensions, as the number of interfaces and
addresses can be high in some environment. Moreover, these information
are not currently refreshed, even if they can frequently change. Given
these reasons, remove ifinfo_json from stats and metrics.
Signed-off-by: Leonardo Di Giovanna <leonardodigiovanna1@gmail.com>
Also, moved yaml_helper under engine/ folder.
Ported rule json schema validation in the engine.
Also, updated rule_loader tests to check for validation.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
There are systems, like Nix derivations where the build process
does not have network access in order to enforce reproducibility.
This patch allows people building Falco to optionally skip the build
of falcoctl with `-DADD_FALCOCTL_DEPENDENCY=OFF` and point to their own
self-backed, or pre-fetched rules files with
`-DFALCOSECURITY_RULES_FALCO_PATH=<some-path>` and
`-DFALCOSECURITY_RULES_LOCAL_PATH=<some-path>`.
For context, I needed to apply these patches while building the
project with Nix in https://github.com/tembleking/falco-nix but I think
that would be benefitial for the community to have also these options
open, and that would also make Falco feasible to be added to the
nixpkgs repository at https://github.com/nixos/nixpkgs
Signed-off-by: Fede Barcelona <fede_rico_94@hotmail.com>
Modify evttype_index_ruleset to derive from indexable_ruleset instead
of having its own implementation of segregating filters by ruleset
id/event type.
An evttype_index_wrapper contains a falco rule and filter, and
implements the methods required by the template. run_wrappers()
evaluate the filter as before, without the segregation by ruleset
id/event type.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Now that custom rules loading implementations (and related, custom
rulesets) can be swapped into falco in a customizable way, there is
some functionality in evttype_index_ruleset that could be used by
other rulesets, specifically the part that segregates filters by
ruleset and enables/disables filters based on name substring + tags.
To allow for this, create a new template indexable_ruleset<class
filter_wrapper> which derives from filter_ruleset and segregates the
filter_wrappers by ruleset. It also optionally segregates
filter_wrappers by event type.
The filter_wrapper class is an object that can return a name, tags,
and sc/event codes.
The main interfaces for classes that derive from indexable_ruleset are:
- add_wrapper(), which provides a filter_wrapper to the
indexable_ruleset. This is generally called from
add()/add_compile_output(), which must be implemented by the derived class.
- run_wrappers(), which must be implemented by the derived class and
is called for event processing.
Most of the methods required by filter_ruleset are implemented by
indexable_ruleset and do not need to be implemented by the derived
class.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Also, rename `Experimental` -> `Incubating` and move `prometheus_metrics_enabled` to `Incubating`.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
As agreed upon during review, use this name to get started. If more
backends were to be added, the configuration structure will be updated.
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
As falco may update its state at any time and thus its inspectors objects,
keeping pointers to them may end up in using dangling values.
Therefore, use the state of the application when requesting metrics.
Optimizations such as caching of mostly static values will be done in
a follow up patch.
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
This makes things easier to pass around like when starting the
web server.
This has the added benefit of simplifying further extension such as
making the metrics endpoint name configurable without adding yet another
parameter to the start function.
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
It was checking twice for prometheus configuration rather than metrics and then prometheus.
Co-authored-by: Federico Di Pierro <nierro92@gmail.com>
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
Moreover, do not trigger an exception when an included file is not present; just print a warning.
Finally, add more tests.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
The PR introduces a `includes` keyword in the config file,
that points to a list of strings (paths to other config files).
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Includes a handful of naming changes. A notice to
https://falco.org/docs/metrics/falco-metrics/ will be added well
in advance of Falco 0.38.0
falco.hostname -> evt.hostname to be consistent with the newer evt.hostname filtercheck
cpu_usage_perc_total_host -> host_cpu_usage_perc
memory_used_host -> host_memory_used_kb (or host_memory_used_mb)
procs_running_host -> host_procs_running
open_fds_host -> host_open_fds
memory_rss -> memory_rss_kb (or memory_rss_mb)
memory_pss -> memory_pss_kb (or memory_pss_mb)
memory_vsz -> memory_vsz_kb (or memory_vsz_mb)
container_memory_used -> container_memory_used_bytes (or container_memory_used_mb)
Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
When hitting that part, the restart signal is triggered and the code
leaves the loop, hence setting should_restart as false makes no sense
in this context.
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
The implementation provides more or less the same implementation
and thus it makes more sense to base it on std::runtime_error.
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
Added option for insecure http driver download in the docker-entrypoint.sh script. By passing --http-insecure to the container via an argument, the flag is forwarded to the falcoctl driver install command.
Signed-off-by: Tom Müller <60851960+toamto94@users.noreply.github.com>
Add a unit test for providing an alternate rules loader that also
demonstrates how users can define sub-classes that may want to extend
the falco rules syntax.
This test creates a test rules reader/collector/compiler that supports
top-level objects "test_object". The reader reads them and saves them
in the collector. The compiler iterates over all test_objects and puts
the property values into a single set<string>.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Move the part of compile_rule_infos that actually compiled a condition
string into a sinsp_filter into a standalone method
compile_condition(). That way it can be used by classes that derive
from rule_loader::compiler() and want to compile condition strings.
This implementation also saves the compiled filter as a part of the
falco_rule object so it does not need to be compiled again wihin the
falco engine after rules loading.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Some rulesets may need information which is held by the falco_engine
that created this ruleset. So define a set of functions in a struct
and have setters/getters for those functions in the base class.
Derived classes can use the struct's functions to obtain the falco
engine information.
The only function so far is to obtain the filter_ruleset for a given
event source.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
To support subclasses that may extend the falco rules format, add
additional error/warning/item types for an extension item.
When subclasses report errors and warnings, they can use these
codes/item types in context objects and still provide an exact
line/column context.
Also make some previously static functions in rules reader protected
methods so they can be used in sub-classes.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
In order to support external rules loaders that may extend the falco
rules format with new top level objects, move away from providing
individual filter objects to the filter_ruleset via calls to add().
Instead, pass the entire compile output returned by the compiler to
the ruleset using a new method add_compile_output(). Custom users can
then cast back the compile output to the appropriate derived class for
use in the ruleset.
Move the declaration of the compile output to a standalone class so it
can be used by rulesets without including the entire rules loader
header files, and add a new factory method new_compile_output() to the
compiler so it can create a derived class if necessary.
This change is
backwards-compatible with existing rulesets, as the default
implementation of add_compile_output() simply iterates over rules and
calls add() for each rule.
This change also speeds up rule loading. Previously, each rule
condition was compiled twice:
1. First, in the compiler, to see if it was valid.
2. Second, in the falco engine before providing each rule to the
ruleset.
Add the compiled filter to the falco_rule object instead of throwing
it away in the compiler.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
In some cases, a user of the falco engine may want to extend the falco
rules format to provide additional objects to the rules file.
To support that, add a new method set_rule_loader() that allows a user
to provide classes that derive from
rule_loader::{reader,collector,compiler} and read those additional
objects from the rules file.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add unit tests for add_source() and its related find_*_for_source()
methods. The test just verifies that the values provided to
add_source() are the same as the values returned by the find methods.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add methods that allow looking up the factories provided to
add_source(). This allows not having to keep track of the factories
outside of the engine.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Inline find_source as it can be called in the event processing path.
Also take the cached variant that assigns/uses m_syscall_source_idx
and put it in find_source() instead of process_event().
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add unit tests for enabling/disabling rules, covering:
- matching names by substring
- using "" to match all rules
- matching names exactly
- using ruleset ids in addition to ruleset names
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Add alternate enable_* methods that allow enabling rulesets by ruleset
id in addition to name. This might be used by some filter_rulesets to
enable/disable rules on the fly via the falco engine.
Signed-off-by: Mark Stemm <mark.stemm@gmail.com>
Also, env variables always have precedence over dialog (ie: if they are set, we always skip dialog).
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Also, properly warn the user that deprecated CLI options will be ignored
when the new `engine` configuration key is in use.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Moreover, renamed driver kinds to use better naming, and move driver's related
config keys under `driver.$kind`.
Added DEPRECTATION notices on CLI options, and in falco.yaml.
DEPRECATED options (both CLI and config ones) will have priority over the new ones,
to retain compatibility with existing configs.
DEPRECATED options will be dropped in Falco 0.38.
Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
Co-authored-by: Andrea Terzolo <andreaterzolo3@gmail.com>
This `init({});` in the falco_configuration constructor is unnecessary
since when we call the action `load_config`, if we don't have a config
file, we will call the same `init` we have just removed. This cleanup
avoids calling `falco_configuration::init` 2 times.
Signed-off-by: Andrea Terzolo <andreaterzolo3@gmail.com>
address
Currently the webserver is listening on the hard coded 0.0.0.0. This
patch keeps this default but allows the administrator to change it.
Signed-off-by: Samuel Gaist <samuel.gaist@idiap.ch>
Open Source Security Foundation Scorecard [1] is an automated tool
that assesses a number of important checks associated with
software security and assigns each check a score of 0-10.
Also, the OSSF Scorecard is one of the metrics monitored by
the CNCF CLO Monitor [2].
1. https://github.com/ossf/scorecard
2. https://github.com/cncf/clomonitor
Signed-off-by: Massimiliano Giovagnoli <me@maxgio.it>
In order to allow the user to supply environment variables in standard
ways performed in other applications the get_scalar function has been
extended to support defining an environment variable in the format
`${FOO}`. Environment variables can be escaped via defining as `$${FOO}`.
As this handles some additional complexity, a unit test has been added
to cover this new functionality
Signed-off-by: Daniel Wright <danielwright@bitgo.com>
Fixes#2352
Needed to refactor the target_id code paths to allow this to be used in
env printing and sourcing.
Signed-off-by: hjenkins <henry@henryjenkins.name>
Old gcc versions (e.g. 4.8.3) won't allow move elision
but newer versions (e.g. 10.2.1) would complain about
the redundant move.
Signed-off-by: Jason Dellaluce <jasondellaluce@gmail.com>
Deprecate `-d` option (currently broken).
Symptoms included the message queue filling up without popping any messages
even though events were handled normally.
Maintainers decided to deprecate not needed `-d` option while keeping
the useful `pidfile` command args option.
Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
In https://github.com/falcosecurity/falco/pull/2043 we've added logic
for relocating tools on Flatcar when running falco-driver-loader in kmod
mode. This logic is relevant for BPF mode, too, which is currently
broken on Flatcar. Call flatcar_relocate_tools in BPF mode, too.
Signed-off-by: Johanan Liebermann <jliebermann@microsoft.com>
Added a set method for the rule matching strategy on the engine.
This allows to modify the stategy at runtime withotu the need to
rebuild an engine from scratch.
Signed-off-by: Lorenzo Susini <susinilorenzo1@gmail.com>
bump Ubuntu version on tests-driver-loader-integration job to fix a
verifier issue as a temp workaround
Signed-off-by: Andrea Terzolo <andreaterzolo3@gmail.com>
This commit will unquote URL's allowing them to be supported by
libcurl and eliminate any errors when a valid (quoted) URL is supplied
by a user.
Closes#2579
Signed-off-by: Daniel Wright danielwright@bitgo.com
2023-06-05 11:09:32 +02:00
516 changed files with 25334 additions and 24117 deletions
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
This PR may bring feature or behavior changes in the Falco engine and may require the engine version to be bumped.
Please double check **userspace/engine/falco_engine_version.h** file. See [versioning for FALCO_ENGINE_VERSION](https://github.com/falcosecurity/falco/blob/master/RELEASE.md#falco-repo-this-repo).
@@ -43,6 +43,8 @@ This is a list of production adopters of Falco (in alphabetical order):
* [MathWorks](https://mathworks.com) - MathWorks develops mathematical computing software for engineers and scientists. MathWorks uses Falco for Kubernetes threat detection, unexpected application behavior, and maps Falco rules to their cloud infrastructure's security kill chain model. MathWorks presented their Falco use case at [KubeCon + CloudNativeCon North America 2020](https://www.youtube.com/watch?v=L-5RYBTV010).
* [NETWAYS Web Services](https://nws.netways.de/en/) - NETWAYS Web Services provides cloud and managed services tailored to their customers needs. From VPCs to managed databases and Kubernetes clusters, NETWAYS Web Services enables their customers to run infrastructure and applications without worries. Falco plays its part for NETWAYS Managed Services to ensure their platform conforms to ISO 27001 at all times and that their clients' workloads behave as expected by detecting anomalies in real-time.
* [Pocteo](https://pocteo.co) - Pocteo helps with Kubernetes adoption in enterprises by providing a variety of services such as training, consulting, auditing and mentoring. We build CI/CD pipelines the GitOps way, as well as design and run k8s clusters. Pocteo uses Falco as a runtime monitoring system to secure clients' workloads against suspicious behavior and ensure k8s pods immutability. We also use Falco to collect, process and act on security events through a response engine and serverless functions.
* [Preferral](https://www.preferral.com) - Preferral is a HIPAA-compliant platform for Referral Management and Online Referral Forms. Preferral streamlines the referral process for patients, specialists and their referral partners. By automating the referral process, referring practices spend less time on the phone, manual efforts are eliminated, and patients get the right care from the right specialist. Preferral leverages Falco to provide a Host Intrusion Detection System to meet their HIPAA compliance requirements.
@@ -58,6 +60,8 @@ This is a list of production adopters of Falco (in alphabetical order):
* [Shopify](https://www.shopify.com) - Shopify is the leading multi-channel commerce platform. Merchants use Shopify to design, set up, and manage their stores across multiple sales channels, including mobile, web, social media, marketplaces, brick-and-mortar locations, and pop-up shops. The platform also provides merchants with a powerful back-office and a single view of their business, from payments to shipping. The Shopify platform was engineered for reliability and scale, making enterprise-level technology available to businesses of all sizes. Shopify uses Falco to complement its Host and Network Intrusion Detection Systems.
* [SafeDep](https://safedep.io/) - SafeDep is a open source software supply chain security platform that helps organizations identify and mitigate risks in their dependencies. At its core, SafeDep offers [`vet`](https://github.com/safedep/vet) a free and open source tool for detecting vulnerabilities, malicious code, and quality issues in open source components, while the enterprise offering, SafeDep Cloud, provides centralized control, data aggregation, and advanced features like malware analysis for large-scale deployments across thousands of repositories.
* [Sight Machine](https://www.sightmachine.com) - Sight Machine is the category leader for manufacturing analytics and used by Global 500 companies to make better, faster decisions about their operations. Sight Machine uses Falco to help enforce SOC2 compliance as well as a tool for real time security monitoring and alerting in Kubernetes.
* [Skyscanner](https://www.skyscanner.net) - Skyscanner is the world's travel search engine for flights, hotels and car rentals. Most of our infrastructure is based on Kubernetes, and our Security team is using Falco to monitor anomalies at runtime, integrating Falco's findings with our internal ChatOps tooling to provide insight on the behavior of our machines in production. We also postprocess and store Falco's results to generate dashboards for auditing purposes.
@@ -68,12 +72,20 @@ This is a list of production adopters of Falco (in alphabetical order):
* [Shapesecurity/F5](https://www.shapesecurity.com/) Shapesecurity defends against application fraud attacks like Account Take Over, Credential Stuffing, Fake Accounts, etc. Required by FedRamp certification, we needed to find a FIM solution to help monitor and protect our Kubernetes clusters. Traditional FIM solutions were not scalable and not working for our environment, but with Falco we found the solution we needed. Falco's detection capabilities have helped us identify anomalous behaviour within our clusters. We leverage Sidekick (https://github.com/falcosecurity/charts/tree/master/falcosidekick) to send Falco alerts to a PubSub which in turn publishes those alerts to our SIEM (SumoLogic)
* [Yahoo! JAPAN](https://www.yahoo.co.jp/) Yahoo! JAPAN is a leading company of internet in Japan. We build an AI Platform in our private cloud and provide it to scientists in our company. AI Platform is a multi-tenant Kubernetes environment and more flexible, faster, more efficient Machine Learning environment. Falco is used to detect unauthorized commands and malicious access and our AI Platform is monitored and alerted by Falco.
* [Sysdig](https://www.sysdig.com/) Sysdig originally created Falco in 2016 to detect unexpected or suspicious activity using a rules engine on top of the data that comes from the sysdig kernel system call driver. Sysdig provides tooling to help with vulnerability management, compliance, detection, incident response and forensics in Cloud-native environments. Sysdig Secure has extended Falco to include: a rule library, the ability to update macros, lists & rules via the user interface and API, automated tuning of rules, and rule creation based on profiling known system behavior. On top of the basic Falco rules, Sysdig Secure implements the concept of a "Security policy" that can comprise several rules which are evaluated for a user-defined infrastructure scope like Kubernetes namespaces, OpenShift clusters, deployment workload, cloud regions etc.
* [Thales Group](https://www.thalesgroup.com) Thales is a global technology leader with more than 81,000 employees on five continents. The Thales Group is investing in digital and “deep tech” innovations – Big Data, artificial intelligence, connectivity, cybersecurity and quantum technology – to build a future we can all trust. In the past few years, the Cloud-Native paradigms and its frameworks and tools have challenged the way applications and services are developed, delivered, and instantiated. All sorts of services are container-based workloads managed by higher level layers of orchestration such as the Kubernetes environment. Thales is committed to develop Cloud-Native services and to provide its customers with security features that ensure their applications and services are protected against cyber threats. Falco is a framework that can help Thales' products and services reach the level of trust, security and safety our clients need.
* [Thought Machine](https://www.thoughtmachine.net) Thought Machine builds Vault Core and Vault Payments: cloud-native core and payments technology enabling banks and fintechs to remain competitive and flourish into the future. Vault Core and Vault Payments are the foundation layer of a bank's technology stack. They can run any bank, any product, and any payment set. Thought Machine uses Falco to perform cloud agnostic real time detections of suspicious container behaviour.
* [Tulip Retail](https://tulip.com) Tulip Retail uses Falco to monitor container activity in our environments. It's numerous integration points, easy deployment and easily customizable rules were the main reasons we chose Falco.
* [Vinted](https://vinted.com/) Vinted uses Falco to continuously monitor container activities, identifying security threats, and ensuring compliance. The container-native approach, rule-based real-time threat detection, community support, extensibility, and compliance capabilities are the main factors why we chose it to enhance Vinted Kubernetes security. Falco Sidekick is used to send critical and warning severity alerts to our incident management solution (RTIR).
* [Xenit AB](https://xenit.se/contact/) Xenit is a growth company with services within cloud and digital transformation. We provide an open-source Kubernetes framework that we leverage to help our customers get their applications to production as quickly and as securely as possible. We use Falco's detection capabilities to identify anomalous behaviour within our clusters in both Azure and AWS.
* [Yahoo! JAPAN](https://www.yahoo.co.jp/) Yahoo! JAPAN is a leading company of internet in Japan. We build an AI Platform in our private cloud and provide it to scientists in our company. AI Platform is a multi-tenant Kubernetes environment and more flexible, faster, more efficient Machine Learning environment. Falco is used to detect unauthorized commands and malicious access and our AI Platform is monitored and alerted by Falco.
## Projects that use Falco libs
* [R6/Phoenix](https://r6security.com/) is an attack surface protection company that uses moving target defense to provide fully automated, proactive and devops friendly security to its customers. There are a set of policies you can add to enable the moving target defense capabilities. Some of them are triggered by a combination of Falco's findings. You can kill, restart and rename pods according to the ever changing policies.
@@ -82,6 +94,8 @@ This is a list of production adopters of Falco (in alphabetical order):
* [StackRox](https://stackrox.io) is the industry’s first Kubernetes-native security platform enabling organizations to build, deploy, and run cloud-native applications securely. The platform works with Kubernetes environments and integrates with DevOps and security tools, enabling teams to operationalize and secure their supply chain, infrastructure, and workloads. StackRox aims to harness containerized applications’ development speed while giving operations and security teams greater context and risk profiling. StackRox leverages cloud-native principles and declarative artifacts to automate DevSecOps best practices.
* [Wireshark](https://www.wireshark.org) is the world's most powerful and popular network protocol analyzer. The Wireshark team is combining Wireshark's features and Falco libs to create Logray, a cloud and system log analyzer with advanced filtering, capture, and scripting capabilities.
## Adding a name
If you would like to add your name to this file, submit a pull request with your change.
This document introduces the coding style that will be applied in this repository.
This coding style involves all the following files: `.c`, `.h`, `.cpp`, `.cmake`, `CMakeLists.txt`. To enforce it we rely on two main tools:
1.`clang-format` version `18.1.8`.
2.`cmake-format` version `0.6.13`.
> __Please note__: tools versions are important! Different versions will enforce slightly different changes on the code. For example `clang-format-18` will produce a slightly different output respect to `clang-format-17` always respecting the imposed style.
The coding style is expressed through the 2 configuration file that you find in this repo: `.clang-format`, `.cmake-format.json`.
### Enforce the style locally
There are many ways to enforce the style locally, here we will describe two of them:
1. Use `pre-commit` framework.
2. Use the repo `Makefile`.
#### 1.Pre-commit framework (suggested if you don't have the 2 tools already installed on your machine)
The `pre-commit` framework allows you to automatically install different `git-hooks` that will run at every new commit. More precisely, if you use the `.pre-commit-config.yaml` in this repo you will install 3 different hooks:
1. The `clang-format` hook: this is a `pre-commit` git hook that runs `clang-format` on your staged changes.
2. The `cmake-format` hook: this is a `pre-commit` git hook that runs `cmake-format` on your staged changes.
3. The `DCO signed-off` hook: this is a `pre-commit-msg` git hook that adds the `DCO` on your commit if not present. This hook is not strictly related to the coding style so we will talk about it in a separate section: [Add DCO signed-off to your commits](#add-dco-signed-off-to-your-commits).
Now let's see what we need to use `pre-commit` framework.
##### Step 1
Install `pre-commit` framework following the [official documentation](https://pre-commit.com/#installation).
> __Please note__: you have to follow only the "Installation" section.
##### Step 2
Once you have installed `pre-commit`, you don't need to install anything else! This is the good point of using a framework like `pre-commit`, all the tools necessary to format your code will be directly managed by the framework. But in order to be ready, you need to install the git hooks in your local repo.
This simple command allows you to install the two `pre-commit` git hooks, `clang-format` and `cmake-format`.
If you want to install also the `pre-commit-msg` git hook for the DCO you have to type the following command, but be sure to have configured all you need as said in the [dedicated section]((#add-dco-signed-off-to-your-commits))
In order to use the repo `Makefile`, you need to install on your local machine the two aforementioned tools:
__clang-format v18.1.8__
One of the easiest ways to install `clang-format` could be directly downloading its static binary from [here](https://github.com/muttleyxd/clang-tools-static-binaries).
There are other ways for example you can download the package for your distro or you can also build it from sources.
__cmake-format v0.6.13__
To install `cmake-format` you can follow the official documentation [here](https://cmake-format.readthedocs.io/en/latest/installation.html).
> __NOTE__: Please check the versions of the two tool with `clang-format --version` and `cmake-format --version`.
##### Step 2
Once you have installed the __right__ versions of the 2 tools, you can simply type `make format-all` from the root directory of the project (`/libs`) to format all your code according to the coding style.
Remember to do that before submitting a new patch upstream! 😁
#### Other solutions
Obviously, you can also install the 2 tools locally and enable some extension of your favorite IDE (like `VScode`) to format your code every time you save your files!
## Add DCO signed-off to your commits 🔏
### Introduction
Another requirement for contributing to the `libs` repository, is applying the [DCO](https://cert-manager.io/docs/contributing/sign-off/) to every commit you want to push upstream.
Before doing this you have to configure your git user `name` and `email` if you haven't already done it. To check your actual `name` and `email` type:
```bash
git config --get user.name
git config --get user.email
```
If they are correct you have done, otherwise, you have to set them:
>__Please note__: If you have problems in doing this you can read the full documentation [here](https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git).
### Enforce the DCO locally
Now you are ready to sign your commits! You have two main ways to do this:
1. Manually with `git` tool.
2. Use the `pre-commit-msg` hook quoted before.
### Manually
To do this you just need to remember the `-s` while performing your commits:
```bash
git commit -s
```
or with the inline message:
```bash
git commit -s -m "my first commit"
```
### Use `pre-commit` hook
Here if you have already added the hook in the [previous section](#step-2), you have to do nothing otherwise you have to simply install the DCO hook with:
And you have done! Now you don't have to remember the `-s` option every time you commit something, the DCO hook will automatically add the DCO if you forget it! 😄
## Some best practices 📏
### Class variables
To know whether a variable belongs to a `class` or a `function`, we start member variables with `m_`.
Example:
```c
publicint32_tm_counter;
```
### Global variables
To know whether the variable is global or not, we start globals with `g_`.
Example:
```c
intg_nplugins;
```
### Capitalization
The naming convention is camel-cased "Unix" style, i.e. always lower case. Words are separated by underscores.
Example:
```c
int32_tg_global_bean_counter;
int32_tcount_beans();
```
and not,
```c
int32_tGlobalBeanCounter;
int32_tCountBeans();
```
### Packed Structures
Packed structures should use the GCC and MSVC-style supported `pragma`:
Example:
```c
#pragma pack(push,1)
structframe_control
{
structfields....
};
#pragma pack(pop)
```
### 64-bit constants
Put an `LL` at the end of your `64-bit` constants. Without the `LL`, some platform compilers try to interpret the constant on the right-hand side as a `long integer` instead of a `long long` and this could lead to an error at building time.
[Falco](https://falco.org/) is a cloud native runtime security tool for Linux operating systems. It is designed to detect and alert on abnormal behavior and potential security threats in real-time.
Parameters are configured for fetching packages from S3 before
(filtered by prefix, sorted in ascending order) and for picking
the latest package by using an XPath selector after.
At its core, Falco is a kernel monitoring and detection agent that observes events, such as syscalls, based on custom rules. Falco can enhance these events by integrating metadata from the container runtime and Kubernetes. The collected events can be analyzed off-host in SIEM or data lake systems.
For comprehensive information on the latest updates and changes to the project, please refer to the [change log](CHANGELOG.md). Additionally, we have documented the [release process](RELEASE.md) for delivering new versions of Falco.
## Introduction to Falco
[Falco](https://falco.org/), originally created by [Sysdig](https://sysdig.com), is an incubating project under the [CNCF](https://cncf.io).
Falco is a cloud native runtime security tool for Linux operating systems. It is designed to detect and alert on abnormal behavior and potential security threats in real-time.
At its core, Falco is a kernel event monitoring and detection agent that captures events, such as syscalls, based on custom rules. Falco can enhance these events by integrating metadata from the container runtime and Kubernetes. The collected events can be analyzed off-host in SIEM or data lake systems.
Falco, originally created by [Sysdig](https://sysdig.com), is a **graduated project** under the [Cloud Native Computing Foundation](https://cncf.io) (CNCF) used in production by various [organisations](https://github.com/falcosecurity/falco/blob/master/ADOPTERS.md).
For detailed technical information and insights into the cyber threats that Falco can detect, visit the official [Falco](https://falco.org/) website.
For comprehensive information on the latest updates and changes to the project, please refer to the [Change Log](CHANGELOG.md).
## Falco Repo: Powering the Core of The Falco Project
## The Falco Project
This is the main Falco repository which contains the source code for building the Falco binary. By utilizing its [libraries](https://github.com/falcosecurity/libs) and the [falco.yaml](falco.yaml) configuration file, this repository forms the foundation of Falco's functionality. The Falco repository is closely interconnected with the following *core* repositories:
The Falco Project codebase is maintained under the [falcosecurity GitHub organization](https://github.com/falcosecurity). The primary repository, [falcosecurity/falco](https://github.com/falcosecurity/falco), holds the source code for the Falco binary, while other sub-projects are hosted in dedicated repositories. This approach of isolating components into specialized repositories enhances modularity and focused development. Notable [core repositories](https://github.com/falcosecurity/evolution?tab=readme-ov-file#core) include:
- [falcosecurity/libs](https://github.com/falcosecurity/libs): Falco's libraries are key to its fundamental operations, making up the greater portion of the source code of the Falco binary and providing essential features such as kernel drivers.
- [falcosecurity/rules](https://github.com/falcosecurity/rules): Contains the official ruleset for Falco, providing pre-defined detection rules for various security threats and abnormal behaviors.
- [falcosecurity/plugins](https://github.com/falcosecurity/plugins/): Falco plugins facilitate integration with external services, expand Falco's capabilities beyond syscalls and container events, and are designed to evolve with specialized functionality in future releases.
- [falcosecurity/falcoctl](https://github.com/falcosecurity/falcoctl): Command-line utility for managing and interacting with Falco.
- [falcosecurity/libs](https://github.com/falcosecurity/libs): This repository hosts Falco's core libraries, which constitute the majority of the binary’s source code and provide essential features, such as kernel drivers.
- [falcosecurity/rules](https://github.com/falcosecurity/rules): It contains the official ruleset for Falco, offering pre-defined detection rules for various security threats and abnormal behaviors.
- [falcosecurity/plugins](https://github.com/falcosecurity/plugins): This repository supports integration with external services through plugins that extend Falco's capabilities beyond syscalls and container events, with plans for evolving specialized functionalities in future releases.
- [falcosecurity/falcoctl](https://github.com/falcosecurity/falcoctl): A command-line utility designed for managing and interacting with Falco.
- [falcosecurity/charts](https://github.com/falcosecurity/charts): This repository provides Helm charts for deploying Falco and its ecosystem, simplifying the installation and management process.
For more information, visit the official hub of The Falco Project: [falcosecurity/evolution](https://github.com/falcosecurity/evolution). It provides valuable insights and information about the project's repositories.
For further insights into our repositories and additional details about our governance model, please visit the official hub of The Falco Project: [falcosecurity/evolution](https://github.com/falcosecurity/evolution).
## Getting Started with Falco
Carefully review and follow the [official guide and documentation](https://falco.org/docs/getting-started/).
If you're new to Falco, begin your journey with our [Getting Started](https://falco.org/docs/getting-started/) guide. For production deployments, please refer to our comprehensive [Setup](https://falco.org/docs/setup/) documentation.
Considerations and guidance for Falco adopters:
As final recommendations before deploying Falco, verify environment compatibility, define your detection goals, optimize performance, choose the appropriate build, and plan for SIEM or data lake integration to ensure effective incident response.
1. Understand dependencies: Assess the environment where you'll run Falco and consider kernel versions and architectures.
2. Define threat detection objectives: Clearly identify the threats you want to detect and evaluate Falco's strengths and limitations.
3. Consider performance and cost: Assess compute performance overhead and align with system administrators or SREs. Budget accordingly.
4. Choose build and customization approach: Decide between the open source Falco build or creating a custom build pipeline. Customize the build and deployment process as necessary, including incorporating unique tests or approaches, to ensure a resilient deployment with fast deployment cycles.
5. Integrate with output destinations: Integrate Falco with SIEM, data lake systems, or other preferred output destinations to establish a robust foundation for comprehensive data analysis and enable effective incident response workflows.
## How to Contribute
Please refer to the [contributing guide](https://github.com/falcosecurity/.github/blob/main/CONTRIBUTING.md) and the [code of conduct](https://github.com/falcosecurity/evolution/CODE_OF_CONDUCT.md) for more information on how to contribute.
### Demo Environment
A demo environment is provided via a docker-compose file that can be started on a docker host which includes falco, falcosidekick, falcosidekick-ui and its required redis database. For more information see the [docker-compose section](docker/docker-compose/)
## Join the Community
To get involved with the Falco Project please visit the [community repository](https://github.com/falcosecurity/community) to find more information and ways to get involved.
To get involved with the Falco Project please visit the [Community](https://github.com/falcosecurity/community) repository to find more information and ways to get involved.
If you have any questions about Falco or contributing, do not hesitate to file an issue or contact the Falco maintainers and community members for assistance.
@@ -116,15 +54,81 @@ How to reach out?
Full reports of various security audits can be found [here](./audits/).
In addition, you can refer to the [falco security](https://github.com/falcosecurity/falco/security) and [libs security](https://github.com/falcosecurity/libs/security) sections for detailed updates on security advisories and policies.
In addition, you can refer to the [falco](https://github.com/falcosecurity/falco/security) and [libs](https://github.com/falcosecurity/libs/security) security sections for detailed updates on security advisories and policies.
To report security vulnerabilities, please follow the community process outlined in the documentation found [here](https://github.com/falcosecurity/.github/blob/main/SECURITY.md).
## What's next for Falco?
## Building
For comprehensive, step-by-step instructions on building Falco from source, please refer to the [official documentation](https://falco.org/docs/developer-guide/source/).
## Testing
<details>
<summary>Expand Testing Instructions</summary>
Falco's [Build Falco from source](https://falco.org/docs/developer-guide/source/) is the go-to resource to understand how to build Falco from source. In addition, the [falcosecurity/libs](https://github.com/falcosecurity/libs) repository offers additional valuable information about tests and debugging of Falco's underlying libraries and kernel drivers.
Here's an example of a `cmake` command that will enable everything you need for all unit tests of this repository:
Optionally, build the driver of your choice and test run the Falco binary to perform manual tests.
Lastly, The Falco Project has moved its Falco regression tests to [falcosecurity/testing](https://github.com/falcosecurity/testing).
</details>
</br>
## How to Contribute
Please refer to the [Contributing](https://github.com/falcosecurity/.github/blob/main/CONTRIBUTING.md) guide and the [Code of Conduct](https://github.com/falcosecurity/evolution/blob/main/CODE_OF_CONDUCT.md) for more information on how to contribute.
## FAQs
### Why is Falco in C++ rather than Go or {language}?
<details>
<summary>Expand Information</summary>
1. The first lines of code at the base of Falco were written some time ago, where Go didn't yet have the same level of maturity and adoption as today.
2. The Falco execution model is sequential and mono-thread due to the statefulness requirements of the tool, and so most of the concurrency-related selling points of the Go runtime would not be leveraged at all.
3. The Falco code deals with very low-level programming in many places (e.g. some headers are shared with the eBPF probe and the Kernel module), and we all know that interfacing Go with C is possible but brings tons of complexity and tradeoffs to the table.
4. As a security tool meant to consume a crazy high throughput of events per second, Falco needs to squeeze performance in all hot paths at runtime and requires deep control on memory allocation, which the Go runtime can't provide (there's also garbage collection involved).
5. Although Go didn't suit the engineering requirements of the core of Falco, we still thought that it could be a good candidate for writing Falco extensions through the plugin system. This is the main reason we gave special attention and high priority to the development of the plugin-sdk-go.
6. Go is not a requirement for having statically-linked binaries. In fact, we provide fully-static Falco builds since few years. The only issue with those is that the plugin system can't be supported with the current dynamic library model we currently have.
7. The plugin system has been envisioned to support multiple languages, so on our end maintaining a C-compatible codebase is the best strategy to ensure maximum cross-language compatibility.
8. In general, plugins have GLIBC requirements/dependencies because they have low-level C bindings required for dynamic loading. A potential solution for the future could be to also support plugin to be statically-linked at compilation time and so released as bundled in the Falco binary. Although no work started yet in this direction, this would solve most issues you reported and would provide a totally-static binary too. Of course, this would not be compatible with dynamic loading anymore, but it may be a viable solution for our static-build flavor of Falco.
9. Memory safety is definitely a concern and we try our best to keep an high level of quality even though C++ is quite error prone. For instance, we try to use smart pointers whenever possible, we build the libraries with an address sanitizer in our CI, we run Falco through Valgrind before each release, and have ways to stress-test it to detect performance regressions or weird memory usage (e.g. https://github.com/falcosecurity/event-generator). On top of that, we also have third parties auditing the codebase by time to time. None of this make a perfect safety standpoint of course, but we try to maximize our odds. Go would definitely make our life easier from this perspective, however the tradeoffs never made it worth it so far due to the points above.
10. The C++ codebase of falcosecurity/libs, which is at the core of Falco, is quite large and complex. Porting all that code to another language would be a major effort requiring lots of development resource and with an high chance of failure and regression. As such, our approach so far has been to choose refactors and code polishing instead, up until we'll reach an optimal level of stability, quality, and modularity, on that portion of code. This would allow further developments to be smoother and more feasibile in the future.
</details>
</br>
### What's next for Falco?
Stay updated with Falco's evolving capabilities by exploring the [Falco Roadmap](https://github.com/orgs/falcosecurity/projects/5), which provides insights into the features currently under development and planned for future releases.
## License
Falco is licensed to you under the [Apache 2.0](./COPYING) open source license.
@@ -138,13 +142,6 @@ Falco is licensed to you under the [Apache 2.0](./COPYING) open source license.
@@ -66,7 +66,7 @@ Changes and new features are organized into [milestones](https://github.com/falc
The release process is mostly automated, requiring only a few manual steps to initiate and complete.
Moreover, we assign owners for each release (typically pairing a new person with an experienced one). Assignees and due dates for releases are proposed during the [weekly community call](https://github.com/falcosecurity/community).
Moreover, we assign owners for each release (typically pairing a new person with an experienced one). Assignees and due dates for releases are proposed during the [community call](https://github.com/falcosecurity/community).
At a high level each Falco release needs to follow a pre-determined sequencing of releases and build order:
@@ -84,11 +84,15 @@ Before proceeding with the release, make sure to complete the following preparat
### 1. Release notes
- Find the previous release date (`YYYY-MM-DD`) by looking at the [Falco releases](https://github.com/falcosecurity/falco/releases)
- Double-check, by using the following filters, if there is any closed issue/merge PR with no milestone assigned:
- Assign any issue/PR identified in the previous point to the milestone corresponding to the currently undergoing release
- Check the release note block of every PR matching the `is:pr is:merged closed:>YYYY-MM-DD` [filter](https://github.com/falcosecurity/falco/pulls?q=is%3Apr+is%3Amerged+closed%3A%3EYYYY-MM-DD)
- Ensure the release note block follows the [commit convention](https://github.com/falcosecurity/.github/blob/master/CONTRIBUTING.md#commit-convention), otherwise fix its content
- If the PR has no milestone, assign it to the milestone currently undergoing release
- Check issues without a milestone (using `is:pr is:merged no:milestone closed:>YYYY-MM-DD` [filter](https://github.com/falcosecurity/falco/pulls?q=is%3Apr+is%3Amerged+no%3Amilestone+closed%3A%3EYYYY-MM-DD) ) and add them to the milestone currently undergoing release
- Double-check that there are no more merged PRs without the target milestone assigned with the `is:pr is:merged no:milestone closed:>YYYY-MM-DD` [filter](https://github.com/falcosecurity/falco/pulls?q=is%3Apr+is%3Amerged+no%3Amilestone+closed%3A%3EYYYY-MM-DD), if any, update those missing
### 2. Milestones
@@ -102,7 +106,7 @@ Its naming will be `release/M.m.x`; for example: `release/0.34.x`.
The same branch will then be used for any eventual cherry pick for patch releases.
For patch releases, instead, the `release/M.m.x` branch should already be in place; no more steps are needed.
Doublecheck that any PR that should be part of the tag has been cherry-picked from master!
Double-check that any PR that should be part of the tag has been cherry-picked from master!
### 4. Release PR
@@ -112,7 +116,7 @@ The release PR is meant to be made against the respective `release/M.m.x` branch
- If any, manually correct it then open an issue to automate version number bumping later
- Versions table in the `README.md` updates itself automatically
- Generate the change log using [rn2md](https://github.com/leodido/rn2md):
<!-- Substitute <changelog> with the one generated by [rn2md](https://github.com/leodido/rn2md) -->
### Statistics
| Merged PRs | Number |
| --------------- | ------ |
| Not user-facing | x |
| Release note | x |
| Total | x |
<!-- Calculate stats and fill the above table -->
#### Release Manager <github handle>
<!-- Substitute GitHub handle with the release manager's one -->
```
- Finally, publish the release!
-Do NOT fill body, since it will be autogenerated by the [github release workflow](.github/workflows/release.yaml)
- Publish the release!
- The release pipeline will start automatically upon publication and all packages and container images will be uploaded to the stable repositories.
In order to check the status of the release pipeline click on the [GitHub Actions tab](https://github.com/falcosecurity/falco/actions?query=event%3Arelease) in the Falco repository and filter by release.
@@ -196,7 +162,7 @@ For each release we archive the meeting notes in git for historical purposes.
- The notes from the Falco meetings can be [found here](https://hackmd.io/3qYPnZPUQLGKCzR14va_qg).
- Note: There may be other notes from working groups that can optionally be added as well as needed.
- Add the entire content of the document to a new file in [github.com/falcosecurity/community/tree/master/meeting-notes](https://github.com/falcosecurity/community/tree/master/meeting-notes) as a new file labeled `release-M.m.p.md`
- Add the entire content of the document to a new file in [github.com/falcosecurity/community/tree/main/meeting-notes](https://github.com/falcosecurity/community/tree/main/meeting-notes) as a new file labeled `release-M.m.p.md`
- Open up a pull request with the new change.
@@ -204,10 +170,10 @@ For each release we archive the meeting notes in git for historical purposes.
Announce the new release to the world!
- IFF the ongoing release introduces a **new minor version**, [archive a snapshot of the Falco website](https://github.com/falcosecurity/falco-website/blob/master/release.md#documentation-versioning)
- Publish a blog on [Falco website](https://github.com/falcosecurity/falco-website) ([example](https://github.com/falcosecurity/falco-website/blob/master/content/en/blog/falco-0-28-1.md))
- Send an announcement to cncf-falco-dev@lists.cncf.io (plain text, please)
- Let folks in the slack #falco channel know about a new release came out
- IFF the on going release introduces a **new minor version**, [archive a snapshot of the Falco website](https://github.com/falcosecurity/falco-website/blob/master/release.md#documentation-versioning)
## Falco Components Versioning
@@ -217,11 +183,9 @@ 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 loading logic, and/or when `FALCO_ENGINE_CHECKSUM` has changed. The checksum is computed by considering the available rules fields (see currently supported [Falco fields](https://falco.org/docs/reference/rules/supported-fields/)), the event types (see currently supported [Falco events](https://falco.org/docs/reference/rules/supported-events/)), and the supported driver schema version. A checksum indicates that something was 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. The version number must be incremented every time and only when a single change or an atomic group of changes - which meet the criteria described above - is included in the `master` branch. Thus, a version bump can occur multiple times during the development and testing phases of a given release cycle. A given version bump must not group multiple changes that occurred sporadically during 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.
- If you use the standard Falco setup leveraging driver-loader, [driver-loader script](https://github.com/falcosecurity/falco/blob/master/scripts/falco-driver-loader) will fetch the kernel space artifact (object file) corresponding to the default `DRIVER_VERSION` Falco was shipped with (read more below under Libs).
@@ -7,13 +7,9 @@ Falco is an open source security project whose brand and identity are governed b
This document describes the official branding guidelines of The Falco Project. Please see the [Falco Branding](https://falco.org/community/falco-brand/) page on our website for further details.
Content in this document can be used to publicly share about Falco.
### Logo
There are 3 logos available for use in this directory. Use the primary logo unless required otherwise due to background issues, or printing.
There are 3 logos available for use in this directory. Use the primary logo unless required otherwise due to background issues or printing.
The Falco logo is Apache 2 licensed and free to use in media and publication for the CNCF Falco project.
@@ -36,55 +32,6 @@ The primary colors are those in the first two rows.
> Cloud Native Runtime Security
### What is Falco?
Falco is a runtime security project originally created by Sysdig, Inc.
Falco was contributed to the CNCF in October 2018.
The CNCF now owns The Falco Project.
### What is Runtime Security?
Runtime security refers to an approach to preventing unwanted activity on a computer system.
With runtime security, an operator deploys **both** prevention tooling (access control, policy enforcement, etc) along side detection tooling (systems observability, anomaly detection, etc).
Runtime security is the practice of using detection tooling to detect unwanted behavior, such that it can then be prevented using prevention techniques.
Runtime security is a holistic approach to defense, and useful in scenarios where prevention tooling either was unaware of an exploit or attack vector, or when defective applications are ran in even the most secure environment.
### What does Falco do?
Falco consumes signals from the Linux kernel, and container management tools such as Docker and Kubernetes.
Falco parses the signals and asserts them against security rules.
If a rule has been violated, Falco triggers an alert.
### How does Falco work?
Falco traces kernel events and reports information about the system calls being executed at runtime.
Falco leverages the extended berkeley packet filter (eBPF) which is a kernel feature implemented for dynamic crash-resilient and secure code execution in the kernel.
Falco enriches these kernel events with information about containers running on the system.
Falco also can consume signals from other input streams such as the containerd socket, the Kubernetes API server and the Kubernetes audit log.
At runtime, Falco will reason about these events and assert them against configured security rules.
Based on the severity of a violation an alert is triggered.
These alerts are configurable and extensible, for instance sending a notification or [plumbing through to other projects like Prometheus](https://github.com/falcosecurity/falco-exporter).
### Benefits of using Falco
- **Strengthen Security** Create security rules driven by a context-rich and flexible engine to define unexpected application behavior.
- **Reduce Risk** Immediately respond to policy violation alerts by plugging Falco into your current security response workflows and processes.
- **Leverage up-to-date Rules** Alert using community-sourced detections of malicious activity and CVE exploits.
### Falco and securing Kubernetes
Securing Kubernetes requires putting controls in place to detect unexpected behavior that could be malicious or harmful to a cluster or application(s).
Examples of malicious behavior include:
- Exploits of unpatched and new vulnerabilities in applications or Kubernetes itself.
- Insecure configurations in applications or Kubernetes itself.
- Leaked or weak credentials or secret material.
- Insider threats from adjacent applications running at the same layer.
Falco is capable of [consuming the Kubernetes audit logs](https://kubernetes.io/docs/tasks/debug-application-cluster/falco/#use-falco-to-collect-audit-events).
By adding Kubernetes application context, and Kubernetes audit logs teams can understand who did what.
### Writing about Falco
##### Yes
@@ -100,49 +47,31 @@ Notice the capitalization of the following terms.
- the falco project
- the Falco project
### Encouraged Phrasing
Below are phrases that the project has reviewed, and found to be effective ways of messaging Falco's value add.
Even when processes are in place for vulnerability scanning and implementing pod security and network policies, not every risk will be addressed. You still need mechanisms to confirm these security barriers are effective, help configure them, and provide with a last line of defense when they fail.
##### Falco as a factory
This term refers to the concept that Falco is a stateless processing engine. A large amount of data comes into the engine, but meticulously crafted security alerts come out.
##### The engine that powers...
Falco ultimately is a security engine. It reasons about signals coming from a system at runtime, and can alert if an anomaly is detected.
##### Anomaly detection
This refers to an event that occurs with something unusual, concerning, or odd occurs.
We can associate anomalies with unwanted behavior, and alert in their presence.
##### Detection tooling
Falco does not prevent unwanted behavior.
Falco however alerts when unusual behavior occurs.
This is commonly referred to as **detection** or **forensics**.
---
# Glossary
# Glossary
#### Probe
This section contains key terms specifically used within the context of The Falco Project. For a more comprehensive list of Falco-related terminology, we invite you to visit the [Glossary](https://falco.org/docs/reference/glossary/) page on our official website.
#### eBPF Probe
Used to describe the `.o` object that would be dynamically loaded into the kernel as a secure and stable (e)BPF probe.
This is one option used to pass kernel events up to userspace for Falco to consume.
Sometimes this word is incorrectly used to refer to a `module`.
#### Module
#### Modern eBPF Probe
More robust [eBPF probe](#ebpf-probe), which brings the CO-RE paradigm, better performances, and maintainability.
Unlike the legacy probe, the modern eBPF probe is not shipped as a separate artifact but bundled into the Falco binary itself.
This is one option used to pass kernel events up to userspace for Falco to consume.
#### Kernel Module
Used to describe the `.ko` object that would be loaded into the kernel as a potentially risky kernel module.
This is one option used to pass kernel events up to userspace for Falco to consume.
Sometimes this word is incorrectly used to refer to a `probe`.
#### Driver
The global term for the software that sends events from the kernel. Such as the eBPF `probe` or the `kernel module`.
The global term for the software that sends events from the kernel. Such as the [eBPF probe](#ebpf-probe), the [Modern eBPF probe](#modern-ebpf-probe), or the [Kernel Module](#kernel-module).
#### Plugin
@@ -150,13 +79,5 @@ Used to describe a dynamic shared library (`.so` files in Unix, `.dll` files in
#### Falco
The name of the project, and also the name of [the main engine](https://github.com/falcosecurity/falco) that the rest of the project is built on.
#### Sysdig, Inc
The name of the company that originally created The Falco Project, and later donated to the CNCF.
#### sysdig
A [CLI tool](https://github.com/draios/sysdig) used to evaluate kernel system events at runtime.
The name of the project and also the name of [the main engine](https://github.com/falcosecurity/falco) that the rest of the project is built on.
message(STATUS"cppcheck command not found, static code analysis using cppcheck will not be available.")
message(
STATUS
"cppcheck command not found, static code analysis using cppcheck will not be available."
)
else()
message(STATUS"cppcheck found at: ${CPPCHECK}")
# we are aware that cppcheck can be run
# along with the software compilation in a single step
# using the CMAKE_CXX_CPPCHECK variables.
# However, for practical needs we want to keep the
# two things separated and have a specific target for it.
# Our cppcheck target reads the compilation database produced by CMake
set(CMAKE_EXPORT_COMPILE_COMMANDSOn)
add_custom_target(
cppcheck
COMMAND${CPPCHECK}
"--enable=all"
"--force"
"--inconclusive"
"--inline-suppr"# allows to specify suppressions directly in source code
"--xml"# we want to generate a report
"--output-file=${CMAKE_CURRENT_BINARY_DIR}/static-analysis-reports/cppcheck/cppcheck.xml"# generate the report under the reports folder in the build folder
"-i${CMAKE_CURRENT_BINARY_DIR}"# exclude the build folder
"${CMAKE_SOURCE_DIR}"
)
message(STATUS"cppcheck found at: ${CPPCHECK}")
# we are aware that cppcheck can be run along with the software compilation in a single step
# using the CMAKE_CXX_CPPCHECK variables. However, for practical needs we want to keep the two
# things separated and have a specific target for it. Our cppcheck target reads the compilation
# database produced by CMake
set(CMAKE_EXPORT_COMPILE_COMMANDSOn)
add_custom_target(
cppcheck
COMMAND
${CPPCHECK}"--enable=all""--force""--inconclusive""--inline-suppr"# allows to
@@ -4,14 +4,9 @@ This directory contains various ways to package Falco as a container and related
## Currently Supported Images
| Name | Directory | Description |
|---|---|---|
| [falcosecurity/falco:latest](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:master](https://hub.docker.com/repository/docker/falcosecurity/falco) | docker/falco | Falco (DEB built from git tag or from the master) with all the building toolchain. |
| _not yet published (experimental)_ | docker/ubi | Falco (built from RedHat's UBI base image) with the building toolchain. |
| [falcosecurity/falco-driver-loader:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:master](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader) | docker/driver-loader | `falco-driver-loader` as entrypoint with the building toolchain. |
| [falcosecurity/falco-no-driver:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-no-driver), [falcosecurity/falco-no-driver:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco-no-driver),[falcosecurity/falco-no-driver:master](https://hub.docker.com/repository/docker/falcosecurity/falco-no-driver) | docker/no-driver | Falco (TGZ built from git tag or from the master) without the building toolchain. |
| [falcosecurity/falco-builder:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-builder) | docker/builder | The complete build tool chain for compiling Falco from source. See [the documentation](https://falco.org/docs/getting-started/source/) for more details on building from source. Used to build Falco (CI). |
| [falcosecurity/falco-tester:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-tester) | docker/tester | Container image for running the Falco test suite. Used to run Falco integration tests (CI). |
| _not to be published_ | docker/local | Built on-the-fly and used by falco-tester. |
> Note: `falco-builder`, `falco-tester` (and the `docker/local` image that it's built on the fly) are not integrated into the release process because they are development and CI tools that need to be manually pushed only when updated.
| [falcosecurity/falco:latest](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:master](https://hub.docker.com/repository/docker/falcosecurity/falco) | docker/falco | Distroless image based on the latest released tar.gz of Falco. No tools are included in the image. |
| [falcosecurity/falco:latest-debian](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:_tag_-debian](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:master-debian](https://hub.docker.com/repository/docker/falcosecurity/falco) | docker/falco-debian | Debian-based image. Include some tools (i.e. jq, curl). No driver-building toolchain support. |
| [falcosecurity/falco-driver-loader:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:master](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader) | docker/driver-loader | Based on falcosecurity/falco:x.y.z-debian (see above) plus the driver building toolchain support and falcoctl. This is intended to be used as an installer or an init container when modern eBPF cannot be used. |
| [falcosecurity/falco-driver-loader:latest-buster](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:_tag_-buster](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader),[falcosecurity/falco-driver-loader:master-debian](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader) | docker/driver-loader-buster | Similar to falcosecurity/falco-driver-loader (see above) but based on a legacy Debian image (i.e. buster ). Recommended only for old kernel versions. |
* We use `Dockerfile` to build the `centos7` Falco builder image.
* We use `modern-falco-builder.Dockerfile` to build Falco with the modern probe and return it as a Dockerfile output. This Dockerfile doesn't generate a Docker image but returns as output (through the `--output` command):
This environment is provided for demonstration purposes only and does not represent a production ready deployment of Falco.
# Components
The components that this docker-compose file spins up are [Falco](https://falco.org/), [falcosidekick](https://github.com/falcosecurity/falcosidekick), [falcosidekick-ui](https://github.com/falcosecurity/falcosidekick-ui) and a [redis](https://redis.io/) database.
# Running
To start this environment run `docker-compose up`.
Note: You may need to use sudo for Falco to start correctly.
# Cleaning up
To clean up run `docker-compose rm`.
# Generating events
If you'd like to generate events that will trigger rules and show up in the UI you can run `docker run -it --rm falcosecurity/event-generator run syscall --loop`
RUNtest -n "$FALCO_VERSION"||(echo"FALCO_VERSION not set"&&false)
ENVFALCO_VERSION=${FALCO_VERSION}
LABEL"name"="Falco Runtime Security"
LABEL"vendor"="Falco"
LABEL"version"="${FALCO_VERSION}"
LABEL"release"="${FALCO_VERSION}"
LABEL"ubi-version"="${UBI_VERSION}"
LABEL"summary"="Falco is a security policy engine that monitors system calls and cloud events, and fires alerts when security policies are violated."
LABEL"description"="Falco is a security policy engine that monitors system calls and cloud events, and fires alerts when security policies are violated."
LABEL"io.k8s.display-name"="Falco"
LABEL"io.k8s.description"="Falco is a security policy engine that monitors system calls and cloud events, and fires alerts when security policies are violated."
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.