up

Author: blotus

crowdsec-docs/docs/log_processor/service-discovery-setup/detect-yaml.md

@@ -4,8 +4,11 @@ title: detect.yaml file format
 sidebar_position: 1
 ---
 
-# File layout: `detect.yaml`
-A minimal detection file is a YAML map with a top‐level `detect:` key. Under it, each entry describes one service plan:
+#  `detect.yaml` syntax
+
+A minimal detection file is a YAML map with a top‐level `detect:` key. 
+
+Under it, each entry describes one service plan:
 
 ```yaml
 # detect.yaml
@@ -27,19 +30,58 @@ detect:
           type: apache2
 ```
 
-Fields
+## Fields
+
+### `when`
+
+A list of expression that must return a boolean.
+
+If multiple expressions are provided, they must all return `true` for the service to be included.
+
+```yaml
+when:
+ - Host.OS == "linux"
+ - Systemd.UnitInstalled("<unit>")
+```
+
+You can use any of the helper referenced [here](/log_processor/service-discovery-setup/expr.md).
+)
+
+### `hub_spec`
+
+A map of hub items to install.
+
+Specifying an invalid item type or item will log an error but will not prevent the detection to continue.
+
+```yaml
+hub_spec:
+ collections:
+  - crowdsecurity/linux
+ parsers:
+  - crowdsecurity/nginx-logs
+ scenarios:
+  - crowdsecurity/http-bf
+```
+
+### `acquisition_spec`
+
+This item defines the acquisition that will be written to disk
+
+```yaml
+acquisition_spec:
+ filename: foobar.yaml
+ datasource:
+  source: docker
+  container_name: foo
+  labels:
+   type: bar
+```
+
+The `filename` attribute will be used to generate the name of file in the form of `acquis.d/setup.<filename>.yaml`.
 
-- `when`: a list of boolean expressions evaluated on the host. Examples include:
-  - `Systemd.UnitInstalled("<unit>")`, `Windows.ServiceEnabled("<name>")`
-  - `Host.OS == "linux"`, `Host.OS == "windows"`
-  - `Path.Exists("/path/file")`, `len(Path.Glob("/path/*.log")) > 0`
-  - `System.ProcessRunning("<binary>")`
-- `hub_spec`: which Hub items to install (collections/parsers/scenarios, etc.). Unknown item types are preserved and passed through.
-- `acquisition_spec`: how to generate a per‐service acquisition file:
-  - `filename`: base name (no slashes). The actual path will be `acquis.d/setup.<filename>.yaml`.
-  - `datasource`: a map validated against the selected `source` (e.g., `file`, `journalctl`, `docker`, `wineventlog`, `cloudwatch`, `kinesis`, …). Required fields vary per source; the CLI validates them for you.
+The content of `datasource` will be validated (syntax, required fields depending on the datasource configured) and be written as-is to the file.
 
-Examples
+## Examples
 
 Basic OS / Hub only:
 
@@ -49,7 +91,8 @@ detect:
     when:
       - Host.OS == "linux"
     hub_spec:
-      collections: [crowdsecurity/linux]
+      collections:
+        - crowdsecurity/linux
 ```
 
 `journalctl` source with a filter:
@@ -61,12 +104,14 @@ detect:
       - Systemd.UnitInstalled("caddy.service")
       - len(Path.Glob("/var/log/caddy/*.log")) == 0
     hub_spec:
-      collections: [crowdsecurity/caddy]
+      collections:
+       - crowdsecurity/caddy
     acquisition_spec:
       filename: caddy.yaml
       datasource:
         source: journalctl
-        labels: {type: caddy}
+        labels:
+         type: caddy
         journalctl_filter:
           - "_SYSTEMD_UNIT=caddy.service"
 ```
@@ -76,45 +121,22 @@ Windows event log:
 ```yaml
 detect:
   windows_auth:
-    when: [ Host.OS == "windows" ]
+    when:
+     - Host.OS == "windows"
     hub_spec:
-      collections: [crowdsecurity/windows]
+      collections: 
+       - crowdsecurity/windows
     acquisition_spec:
       filename: windows_auth.yaml
       datasource:
         source: wineventlog
         event_channel: Security
-        event_ids: [4625, 4623]
+        event_ids: 
+         - 4625
+         - 4623
         event_level: information
-        labels: {type: eventlog}
+        labels: 
+         type: eventlog
 ```
 
 
-## Expression Helpers Reference
-
-Expressions run against an environment that exposes helpers and facts via these names:
-
-- Host — host facts from gopsutil/host.InfoStat. See https://pkg.go.dev/github.com/shirou/gopsutil/host#InfoStat
-    Example: Host.OS == "linux".
-
-- Path — filesystem helpers:
-  - Path.Exists(path) -> bool
-  - Path.Glob(pattern) -> []string
-    Example: len(Path.Glob("/var/log/nginx/*.log")) > 0.
-
-- System — process helpers:
-  - System.ProcessRunning(name) -> bool (by process name)
-
-- Systemd (Linux) — systemd unit helpers:
-  - Systemd.UnitInstalled(unit) -> bool
-  - Systemd.UnitConfig(unit, key) -> string (empty string if unit missing; error if key missing)
-  - Systemd.UnitLogsToJournal(unit) -> bool (true if stdout/stderr go to journal or journal+console)
-
-- Windows (Windows builds only):
-  - Windows.ServiceEnabled(service) -> bool (true if the service exists and is Automatic start; returns false on non-Windows builds)
-
-- Version — semantic version checks (can be used with Host.PlatformVersion):
-  - Version.Check(version, constraint) -> bool
-  - Supports operators like =, !=, <, <=, >, >=, ranges (1.1.1 - 1.3.4), AND with commas (>1, <3), and ~ compatible ranges.
-
-

crowdsec-docs/docs/log_processor/service-discovery-setup/expr.md

@@ -0,0 +1,151 @@
+---
+id: setup-expr-helpers
+title: Expr Helpers
+sidebar_position: 1
+---
+
+# Expression Helpers Reference
+
+Various helpers are available for use in the `detect.yaml` file to determine how crowdsec should be configured.
+
+## Host
+
+    This object gives access to various information about the current state of the operating system
+
+### `Host.Hostname`
+
+    Returns the hostname of the machine
+
+> `Host.Hostname == "mymachine"`
+
+### `Host.Uptime`
+
+    Returns the uptime of the machine in seconds.
+
+### `Host.Boottime`
+
+    Returns the unix timestamp of the time the machine booted.
+
+### `Host.Procs`
+
+    Returns the number of processes on the machine.
+
+### `Host.OS`
+
+    Returns the name of the OS (`linux`, `freebsd`, `windows`, ...)
+
+> `Host.OS == "linux"`
+
+### `Host.Platform`
+
+    Returns the variant of the OS (`ubuntu`, `linuxmint`,  ....)
+
+> `Host.Platform == "ubuntu"`
+
+### `Host.PlatformFamily`
+
+    Returns the family of the OS (`debian`, `rhel`, ...)
+
+> `Host.Platform == "debian"`
+
+### `Host.KernelVersion`
+
+    Returns the current kernel version as returned by `uname -r`
+
+> `Host.KernelVersion == "6.16.2"
+
+### `Host.KernelArch`
+
+    Returns the native architecture of the system (`x86_64`, ...)
+
+> `Host.KernelArch == "x86_64"`
+
+### `Host.VirtualizationSystem`
+
+    Returns the name of the virtualization system in use if any.
+
+> `Host.VirtualizationSystem == "kvm"`
+
+### `Host.VirtualizationRole`
+
+    Returns the virtualization role of the system if any (`guest`, `host`)
+
+> `Host.VirtualizationRole == "host"`
+
+### `Host.HostID`
+
+    Returns a unique ID specific to the system.
+
+## Path
+
+This object exposes helpers functions for the filesystem
+
+### `Exists(path) bool`
+
+    Returns `true` if the specified path exists.
+
+> `Path.Exists("/var/log/nginx/access.log") == true`
+
+### `Glob(pattern) []string`
+
+    Returns a list of files matching the provided pattern.
+
+    Returns an empty list if the glob pattern is invalid
+
+> `len(Path.Glob("/var/log/nginx/*.log")) > 0`
+
+## System
+
+### `ProcessRunning(name) bool`
+
+    Returns `true` if there's any with the specified name running
+
+> `System.ProcessRunning("nginx") == true`
+
+## Systemd
+
+    This object exposes helpers to get informations about systemd units.
+
+    Only available on Linux.
+
+### `UnitInstalled(unitName) bool`
+
+    Returns `true` if the provided unit is installed.
+
+> `Systemd.UnitInstalled("nginx") == true`
+
+### `UnitConfig(unitName, key) string`
+
+    Returns the value of the specified key from the specified unit.
+
+    Returns an empty value if the unit if not installed and an error if the key does not exist.
+
+> `Systemd.UnitConfig("nginx", "StandardOutput") == "journal"`
+
+### `UnitLogsToJournal(unitName) bool`
+
+    Returns `true` if unit stdout/stderr are redirect to journal or journal+console.
+
+> `Systemd.UnitLogsToJournal("nginx") == true`
+
+## Windows
+
+    This object exposes helpers to get informations about Windows services.
+
+    Only available on Windows.
+
+### `ServiceEnabled(serviceName) bool`
+
+    Returns `true` if the specified service exists and is configured to start automatically on boot.
+
+> `Windows.ServiceEnabled("MSSSQLSERVER") == true`
+
+## Version
+
+### `Check(version, constraint) bool`
+
+    Performs a semantic version check.
+
+&nbsp;&nbsp;&nbsp;&nbsp;Constraint supports operators like `=`, `!=`, `<`, `<=`, `>`, `>=`, ranges (1.1.1 - 1.3.4), AND with commas (`>1`, `<3`), and ~ compatible ranges.
+
+> `Version.Check(Host.KernelVersion, ">=6.24.0")`