cleanup(docs): adjust falco readme style and content #2594
Conversation
Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
poiana
added
size/L
release-note
and removed
do-not-merge/release-note-label-needed
labels
|
LGTM label has been added. Git tree hash: 40dd27954509fdd0c9c8a602a3fda73872546411
|
|
/cc @leogr /milestone 0.35.0 |
There was a problem hiding this comment.
Hey @incertum
I can only thank you for this PR 🤩
This is a great start to finally getting consistent information in the README.
So, willing to help, I was as exhaustive as possible in my suggestions. Some suggestions, however, are only minor aspects. Let me know what you think.
Anyway, overall, it SGTM!
README.md
Outdated
| @@ -58,107 +54,77 @@ Notes: | |||
| | deb-aarch64 | [][3] | [][4] | | |||
There was a problem hiding this comment.
I'd temporarily remove the development column since that shows the wrong information.
Then, we can add it back once #1672 has been solved.
Wdyt?
README.md
Outdated
| - A non-device file is written to `/dev`. | ||
| - A standard system binary, such as `ls`, is making an outbound network connection. | ||
| - A privileged pod is started in a Kubernetes cluster. | ||
| The [Falco Project](https://falco.org/), originally created by [Sysdig](https://sysdig.com), is an incubating project under the [CNCF](https://cncf.io). |
There was a problem hiding this comment.
| The [Falco Project](https://falco.org/), originally created by [Sysdig](https://sysdig.com), is an incubating project under the [CNCF](https://cncf.io). | |
| [Falco](https://falco.org/), originally created by [Sysdig](https://sysdig.com), is an incubating project under the [CNCF](https://cncf.io). |
OR
| The [Falco Project](https://falco.org/), originally created by [Sysdig](https://sysdig.com), is an incubating project under the [CNCF](https://cncf.io). | |
| [The Falco Project](https://falco.org/), originally created by [Sysdig](https://sysdig.com), is an incubating project under the [CNCF](https://cncf.io). |
See https://github.com/falcosecurity/falco/tree/master/brand#writing-about-falco
README.md
Outdated
|
|
||
| The official Falco rules are maintained and released in [falcosecurity/rules](https://github.com/falcosecurity/rules/). That repository also contains the Falco rules inventory [document](https://github.com/falcosecurity/rules/blob/main/rules_inventory/rules_overview.md), which provides additional details around the default rules Falco ships with. | ||
| 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. |
There was a problem hiding this comment.
| 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. | |
| 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. |
Ref https://www.cncf.io/blog/2018/09/04/the-cloud-native-computing-foundation-cncf-style-guide/
README.md
Outdated
|
|
||
| ## Installing Falco | ||
| At its core, Falco is a kernel event monitoring and detection agent that captures events, such as syscalls, based on custom rules. These events can be analyzed off-host in a SIEM or data lake. The [Falco ecosystem](https://github.com/falcosecurity/evolution/) is continuously evolving, aiming to enhance its functionality and interoperability by integrating with CNCF cloud native components. For detailed technical information and insights into the cyber threats that Falco can detect, visit the official [Falco Project](https://falco.org/) website. |
There was a problem hiding this comment.
| At its core, Falco is a kernel event monitoring and detection agent that captures events, such as syscalls, based on custom rules. These events can be analyzed off-host in a SIEM or data lake. The [Falco ecosystem](https://github.com/falcosecurity/evolution/) is continuously evolving, aiming to enhance its functionality and interoperability by integrating with CNCF cloud native components. For detailed technical information and insights into the cyber threats that Falco can detect, visit the official [Falco Project](https://falco.org/) website. | |
| At its core, Falco is a kernel event monitoring and detection agent that captures events, such as syscalls, based on custom rules. Falco can further enhance these events by integrating metadata from the container runtimes and Kubernetes. Ultimately, these events can be analyzed off-host in a SIEM or data lake. | |
| For detailed technical information and insights into the cyber threats that Falco can detect, visit the official [Falco Project](https://falco.org/) website. |
Rationales:
- Falco is a cloud native tool also because it natively integrates with container runtimes and Kubernetes
- I'm worried that mixing the evolution repository with the ecosystem concept will create more confusion than benefit. So, in the doubt, I'd omit it for now.
README.md
Outdated
| - [falcosecurity/falcosidekick](https://github.com/falcosecurity/falcosidekick): Companion tool that offers multiple output options for Falco. | ||
| - [falcosecurity/driverkit](https://github.com/falcosecurity/driverkit): Command line tool to build the Falco kernel module and eBPF probe. |
There was a problem hiding this comment.
| - [falcosecurity/falcosidekick](https://github.com/falcosecurity/falcosidekick): Companion tool that offers multiple output options for Falco. | |
| - [falcosecurity/driverkit](https://github.com/falcosecurity/driverkit): Command line tool to build the Falco kernel module and eBPF probe. |
Although these repositories have great relevance in the Falco ecosystem, it's incorrect to say they are interconnected with the Falco repository. I'd remove them from this list. Then we will find the right place to advertise their usage.
README.md
Outdated
| | Minikube | [Tutorial](https://falco.org/docs/getting-started/third-party/#minikube) | The Falco driver has been baked into minikube for easy deployment. | | ||
| | Kind | [Tutorial](https://falco.org/docs/getting-started/third-party/#kind) | Running Falco with kind requires a driver on the host system. | | ||
| | GKE | [Tutorial](https://falco.org/docs/getting-started/third-party/#gke) | We suggest using the eBPF driver for running Falco on GKE. | | ||
| This repo acts as the core of Falco, containing 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 repositories within the Falco ecosystem: |
There was a problem hiding this comment.
| This repo acts as the core of Falco, containing 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 repositories within the Falco ecosystem: | |
| 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: |
Just minor changes and removed the reference to the word "ecosystem". I'd reserve that word for a new set of repositories to collect non-core projects intended explicitly for the Falco ecosystem. wdyt?
README.md
Outdated
|
|
||
| Falco is designed to be extensible such that it can be built into cloud-native applications and infrastructure. | ||
| For more information, visit the official hub of the Falco ecosystem: [falcosecurity/evolution](https://github.com/falcosecurity/evolution). It provides valuable insights and information about the project's repositories. |
There was a problem hiding this comment.
| For more information, visit the official hub of the Falco ecosystem: [falcosecurity/evolution](https://github.com/falcosecurity/evolution). It provides valuable insights and information about the project's repositories. | |
| 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. |
README.md
Outdated
|
|
||
| The Falco Project maintains [various plugins](https://github.com/falcosecurity/plugins) and provides SDKs for plugin development. | ||
| 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. |
There was a problem hiding this comment.
| 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. | |
| 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. |
README.md
Outdated
|
|
||
| ### SDKs | ||
| Carefully review and follow the [official guide and documentation](https://falco.org/docs/getting-started/). Integration timelines may vary based on your organization's needs, typically taking several weeks of ramp-up time. |
There was a problem hiding this comment.
| Carefully review and follow the [official guide and documentation](https://falco.org/docs/getting-started/). Integration timelines may vary based on your organization's needs, typically taking several weeks of ramp-up time. | |
| Carefully review and follow the [official guide and documentation](https://falco.org/docs/getting-started/). |
The sentence I've removed sounds discouraging to me. Also, we don't have precise data points on how long it takes to start using Falco since it may vary significantly. So, I don't see a compelling reason to indicate a typical time range.
There was a problem hiding this comment.
🤦♀️ agree, but yeah it's a reflection of reality check ...
README.md
Outdated
|
|
||
| ## Developing | ||
| - [falcosecurity/libs](https://github.com/falcosecurity/libs): Falco's libraries are key to its core operations, accounting for over 80% of the source code and supporting essential features such as the kernel drivers. |
There was a problem hiding this comment.
| - [falcosecurity/libs](https://github.com/falcosecurity/libs): Falco's libraries are key to its core operations, accounting for over 80% of the source code and supporting essential features such as the kernel drivers. | |
| - [falcosecurity/libs](https://github.com/falcosecurity/libs): Falco's libraries are key to its core operations, making up the greater portion of the source code and supporting essential features such as the kernel drivers. |
Just nit: statistics and numbers may change over time 👼
Co-authored-by: Leonardo Grasso <me@leonardograsso.com> Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
|
@leogr addressed feedback, thank for the great suggestions! Added a roadmap mention on top, PTAL. |
|
re the release table, we may want to organize this better. Also will we have one separate binary for modern bpf or just one binary that now always included modern bpf? Added links to the artifacts repo containing the stable default drivers may be beneficial too? On that note happy to help updating the release markdown doc in a follow up PR. |
|
LGTM label has been added. Git tree hash: c269a26caaae20b38ae4664e9489a60ee27bf63d
|
No separate binary. It is always included.
Not sure, perhaps better in a follow-up PR. |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: cpanato, incertum, jasondellaluce, leogr The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
What type of PR is this?
/kind documentation
Any specific area of the project related to this PR?
What this PR does / why we need it:
Adjust falco readme style and content in order to make the information provided here more precise and relevant for adopters. Furthermore, start the transition towards the Falco website being a single consolidated source of information.
cc @falcosecurity/core-maintainers @leogr
Which issue(s) this PR fixes:
Fixes #
Special notes for your reviewer:
Does this PR introduce a user-facing change?: