Merge branch 'hugo-docs'

.github/workflows/docs.yaml

@@ -32,16 +32,20 @@ jobs:
       - name: Install Dart Sass
         run: sudo snap install dart-sass
       - name: Checkout
+        working-directory: docs-website
         uses: actions/checkout@v4
         with:
           submodules: recursive
           fetch-depth: 0
       - name: Setup Pages
         id: pages
+        working-directory: docs-website
         uses: actions/configure-pages@v4
       - name: Install Node.js dependencies
+        working-directory: docs-website
         run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
       - name: Build with Hugo
+        working-directory: docs-website
         env:
           HUGO_ENVIRONMENT: production
           HUGO_ENV: production
@@ -51,6 +55,7 @@ jobs:
             --minify \
             --baseURL "${{ steps.pages.outputs.base_url }}/"          
       - name: Upload artifact
+        working-directory: docs-website
         uses: actions/upload-pages-artifact@v2
         with:
           path: ./public
@@ -64,5 +69,6 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
+        working-directory: docs-website
         uses: actions/deploy-pages@v3
 

docs-website/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+- package-ecosystem: npm
+  directory: "/"
+  schedule:
+    interval: daily
+    time: '20:00'
+  open-pull-requests-limit: 10
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+    time: '20:00'
+  open-pull-requests-limit: 10

docs-website/.gitignore

@@ -0,0 +1,5 @@
+/public
+resources/
+node_modules/
+package-lock.json
+.hugo_build.lock

docs-website/assets/scss/_variables_project.scss

@@ -0,0 +1,6 @@
+/*
+
+Add styles or override variables from the theme here.
+
+*/
+

docs-website/content/en/_index.md

@@ -0,0 +1,42 @@
+---
+title: Falco Talon
+---
+
+{{< blocks/cover title="Welcome to the Falco Talon project: A tailor made response engine for Falco!" image_anchor="top" height="full" >}}
+<a class="btn btn-lg btn-primary me-3 mb-4" href="/docs/">
+  Documentation <i class="fas fa-arrow-alt-circle-right ms-2"></i>
+</a>
+<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/issif/falco-talon">
+  Contribute <i class="fab fa-github ms-2 "></i>
+</a>
+
+<p class="lead mt-5">React in real time to the threats detected by Falco!</p>
+
+{{< blocks/link-down color="info" >}}
+{{< /blocks/cover >}}
+
+
+{{% blocks/lead color="primary" %}}
+The Falco Talon project is a community-driven no-code solution to create a fully customisable reponse engine to work in pair with Falco, the runtime security component. 
+
+It allows you to run series of actions following the name, the priority, the tags, the fields and more of the received Falco events. Falco Talon comes with multiple pre-integrated actions allowing you to focus on your rules and parameters and not on writing code.
+{{% /blocks/lead %}}
+
+
+{{% blocks/section color="dark" type="row" %}}
+
+{{% blocks/feature icon="fab fa-slack" title="Come to discuss!" url="https://kubernetes.slack.com/falco" %}}
+The Falco maintainers are all on Slack! Join us to get help or just chat!
+{{% /blocks/feature %}}
+
+{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="https://github.com/google/docsy-example" %}}
+We do a [Pull Request](https://github.com/google/docsy-example/pulls) contributions workflow on **GitHub**. New users are always welcome!
+{{% /blocks/feature %}}
+
+{{% blocks/feature icon="fab fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/docsydocs" %}}
+For announcement of latest features etc.
+{{% /blocks/feature %}}
+
+{{% /blocks/section %}}
+
+

docs-website/content/en/about/_index.md

@@ -0,0 +1,30 @@
+---
+title: About Falco Talon
+linkTitle: About
+# menu: {main: {weight: 0}}
+---
+
+{{% blocks/cover title="About Falco Talon" image_anchor="bottom" height="auto" %}}
+
+{.mt-5}
+
+{{% /blocks/cover %}}
+
+{{% blocks/lead %}}
+
+
+{{% /blocks/lead %}}
+
+{{% blocks/section %}}
+
+# This is another section
+{.text-center}
+
+{{% /blocks/section %}}
+
+{{% blocks/section %}}
+
+# This is another section
+{.text-center}
+
+{{% /blocks/section %}}

docs-website/content/en/community/_index.md

@@ -0,0 +1,6 @@
+---
+title: Community
+menu: {main: {weight: 40}}
+---
+
+<!--add blocks of content here to add more sections to the community page -->

docs-website/content/en/docs/_index.md

@@ -0,0 +1,29 @@
+---
+title: Documentation
+linkTitle: Docs
+menu: {main: {weight: 20}}
+weight: 20
+---
+
+{{% pageinfo %}}
+This is a placeholder page that shows you how to use this template site.
+{{% /pageinfo %}}
+
+This section is where the user documentation for your project lives - all the
+information your users need to understand and successfully use your project.
+
+For large documentation sets we recommend adding content under the headings in
+this section, though if some or all of them don’t apply to your project feel
+free to remove them or add your own. You can see an example of a smaller Docsy
+documentation site in the [Docsy User Guide](https://docsy.dev/docs/), which
+lives in the [Docsy theme
+repo](https://github.com/google/docsy/tree/master/userguide) if you'd like to
+copy its docs section.
+
+Other content such as marketing material, case studies, and community updates
+should live in the [About](/about/) and [Community](/community/) pages.
+
+Find out how to use the Docsy theme in the [Docsy User
+Guide](https://docsy.dev/docs/). You can learn more about how to organize your
+documentation (and how we organized this site) in [Organizing Your
+Content](https://docsy.dev/docs/best-practices/organizing-content/).

docs-website/content/en/docs/actionners/_index.md

@@ -0,0 +1,16 @@
+---
+title: Actionners
+weight: 5
+description: >
+  Actionners are the built-it actions to react to the events
+---
+
+The `Actionners` define the actions to apply when an event matches a rule, they are named with pattern `category:action`.
+The `category` allows to group `actions` and avoid multiple initializations (eg, multi Kubernetes API client, multi AWS clients, ...).
+
+Each `actionner` is configured with:
+* `parameters`: `key:value` map of parameters passed to the action, the value can be a string, a list (array) or a map (map[string]string). Example: list of `labels` for `kubernetes:labelize`.
+
+{{% alert title="Warning" color="warning" %}}
+Some actionners have by default the `Continue: false` setting, this stops the evaluation of the next actions of the rule. It can be overridden.
+{{% /alert %}}

docs-website/content/en/docs/actionners/list.md

@@ -0,0 +1,74 @@
+---
+title: List of Actionners
+weight: 5
+description: >
+  Available actionners
+---
+
+The `required fields` are the field elements that must be present in your Falco events to allow the actionner to do its work.
+
+## `kubernetes:terminate`
+
+* Description: **Terminate pod**
+* Continue: `false`
+* Parameters:
+  * `grace_period_seconds`: The duration in seconds before the pod should be deleted. The value zero indicates delete immediately.
+  * `ignore_daemonsets`: If true, the pods which belong to a Daemonset are not terminated.
+  * `ignore_statefulsets`: If true, the pods which belong to a Statefulset are not terminated.
+  * `min_healthy_replicas`: Minimum number of healthy pods to allow the termination, can be an absolute or % value (the value must be a quoted string).
+* Required fields:
+  * `k8s.pod.name`
+  * `k8s.ns.name`
+
+## `kubernetes:labelize`
+
+* Description: **Add, modify or delete labels of pod**
+* Continue: `true`
+* Parameters: 
+  * `labels`: key:value map of labels to add/modify/delete (empty value means label deletion)
+* Required fields:
+  * `k8s.pod.name`
+  * `k8s.ns.name`
+
+## `kubernetes:networkpolicy`
+
+* Description: **Create, update a network policy to block all egress traffic for pod**
+* Continue: `true`
+* Parameters:
+  * `allow`: list of CIDR to allow anyway (eg: private subnets)
+* Required fields:
+  * `k8s.pod.name`
+  * `k8s.ns.name`
+
+## `kubernetes:exec`
+
+* Description: **Exec a command in a pod**
+* Continue: `true`
+* Parameters:
+  * `shell`: SHELL used to run the command (default: `/bin/sh`)
+  * `command` Command to run
+* Required fields:
+  * `k8s.pod.name`
+  * `k8s.ns.name`
+
+## `kubernetes:script`
+
+* Description: **Run a script in a pod**
+* Continue: `true`
+* Parameters:
+  * `shell`: SHELL used to run the script (default; `/bin/sh`)
+  * `script`: Script to run (use `|` to use multilines) (can't be used at the same time than `file`)
+  * `file`: Shell script file (can't be used at the same time than `script`)
+* Required fields:
+  * `k8s.pod.name`
+  * `k8s.ns.name`
+
+## `kubernetes:log`
+
+* Description: **Get logs from a pod**
+* Continue: `true`
+* Parameters:
+  * `tail_lines`: The number of lines from the end of the logs to show (default: `1000`)
+* Required fields:
+  * `k8s.pod.name`
+  * `k8s.ns.name`

docs-website/content/en/docs/concepts/_index.md

@@ -0,0 +1,43 @@
+---
+title: Concepts
+weight: 2
+description: >
+  What does your user need to understand about your project in order to use it - or potentially contribute to it?
+---
+
+# Concepts
+
+* Tailor made for the Falco events
+* No-code for the users
+* UX close to Falco with the rules (yaml files with append, override mechanisms)
+* Allow to set up sequential actions to run
+* Structured logs (with a trace id)
+* Helm chart
+* The actions are triggered if match:
+  * Falco rule name `(=)`
+  * priority (`=`, `>=`)
+  * tags (`=`)
+  * output fields (`=`, `!=`)
+
+## Architecture
+
+`Falco Talon` can receive the `events` from [`Falco`](https://falco.org) or [`Falcosidekick`](https://github.com/falcosecurity/falcosidekick):
+
+
+```
+┌──────────┐      ┌───────────────┐      ┌─────────────┐
+│  Falco   ├──────► Falcosidekick ├──────► Falco Talon │
+└──────────┘      └───────────────┘      └─────────────┘
+or
+┌──────────┐      ┌─────────────┐
+│  Falco   ├──────► Falco Talon │
+└──────────┘      └─────────────┘
+```
+
+## Glossary
+
+* `event`: an event detected by `Falco` and sent to its outputs
+* `rule`: defines criterias for linking the events with the actions to apply
+* `action`: each rule can sequentially run actions, each action refers to an actionner
+* `actionner`: defines what to the action will do
+* `notifier`: defines what outputs to notify with the result of the action

docs-website/content/en/docs/configuration/_index.md

@@ -0,0 +1,39 @@
+---
+title: Configuration
+weight: 2
+description: Configuration file
+---
+
+## Configuration
+
+The static configuration of `Falco Talon` is set with a `.yaml` file (default: `./config.yaml`) or with environment variables.
+
+|       Setting       |       Env var       |  Default  |                           Description                           |
+| ------------------- | ------------------- | :-------: | --------------------------------------------------------------- |
+| `listen_address`    | `LISTEN_ADDRESS`    | `0.0.0.0` | Listten Address                                                 |
+| `listen_port`       | `LISTEN_PORT`       |  `2803`   | Listten Port                                                    |
+| `rules_files`       | `RULES_FILES`       |    n/a    | File with rules                                                 |
+| `watch_rules`       | `WATCH_RULES`       |  `true`   | Reload rules if they change                                     |
+| `print_all_events`  | `PRINT_ALL_EVENTS`  |  `true`   | Print in logs all received events, not only those which match   |
+| `kubeconfig`        | `KUBECONFIG`        |    n/a    | Kube config file, only if `Falco Talon` runs outside Kubernetes |
+| `log_format`        | `LOG_FORMAT`        |  `color`  | Log Format: text, color, json                                   |
+| `default_notifiers` | `DEFAULT_NOTIFIERS` |    n/a    | List of `notifiers` which are enabled for all rules             |
+| `notifiers_x`       | `NOTIFIERS_X`       |    n/a    | List of `notifiers` with their settings                         |
+
+Example:
+
+```yaml
+listen_address: "0.0.0.0"
+listen_port: "2803"
+rules_files: "./rules.yaml"
+kubeconfig: "./kubeconfig.yaml"
+
+default_notifiers:
+  - slack
+
+notifiers:
+  slack:
+    webhook_url: "https://hooks.slack.com/services/XXXX"
+    username: "Falco Talon"
+    footer: ""
+```