specs

Specifications

Implementation-focused technical specifications of Falco, enabling the workflow: modify spec → modify implementation.

Era: 0.44 (released May 26, 2026)

Component Map

┌─────────────────────────────────────────────────────────────────┐
│                        Falco Application                        │
│  ┌───────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │ Rule Engine   │  │ Output System│  │ App Lifecycle        │ │
│  │ rule-engine   │  │ output-system│  │ application-lifecycle│ │
│  └───────┬───────┘  └──────┬───────┘  └──────────────────────┘ │
│          │                 │                                    │
│  ┌───────┴─────────────────┴──────────────────────────────────┐ │
│  │ Configuration: configuration    CLI: cli-interface          │ │
│  │ Metrics: metrics-and-observability                         │ │
│  └────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                      falcosecurity/libs                         │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐  │
│  │ Filter Engine  │  │ libsinsp       │  │ libscap          │  │
│  │ filter-engine  │  │ libsinsp       │  │ libscap          │  │
│  └────────┬───────┘  └────────┬───────┘  └────────┬─────────┘  │
│           └──────────┬────────┘                    │            │
│                      │                             │            │
│  ┌───────────────────┴─────────────────────────────┘           │
│  │ Plugin System: plugin-system                                │
│  └─────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│  Kernel Driver: kernel-instrumentation                          │
├─────────────────────────────────────────────────────────────────┤
│  External Tools                                                 │
│  ┌───────────────┐  ┌──────────────┐                           │
│  │ falcoctl      │  │ Build System │                           │
│  │ falcoctl      │  │ build-system │                           │
│  └───────────────┘  └──────────────┘                           │
└─────────────────────────────────────────────────────────────────┘

Spec Files

Reading Order (recommended)

Follow the event pipeline from bottom to top, then application concerns:

#	Spec	Description
1	architecture-overview.md	System architecture, event pipeline, threading model
2	kernel-instrumentation.md	Modern eBPF, kmod, syscall capture, event model
3	libscap.md	System capture library, engine vtable, ring buffers
4	libsinsp.md	Event parsing, state tables, thread/FD tracking
5	filter-engine.md	Filter language, AST, operators, filterchecks
6	rule-engine.md	Rule YAML schema, compilation pipeline, indexing
7	configuration.md	Config system, merging, JSON schema validation
8	output-system.md	Alert channels, async queue, formatting
9	plugin-system.md	Plugin API, capabilities, lifecycle
10	metrics-and-observability.md	Internal metrics, stats, health monitoring
11	application-lifecycle.md	App actions, signal handling, hot reload
12	cli-interface.md	CLI flags, introspection, exit codes
13	falcoctl.md	Artifact/driver management, OCI distribution
14	build-system.md	CMake, dependencies, feature flags
15	kubernetes-deployment.md	Helm charts, DaemonSet/Deployment, pod architecture
16	rules-content.md	Detection rules, maturity framework, tuning
17	falcosidekick.md	Fan-out daemon, FalcoPayload, 70+ outputs
18	falco-operator.md	Kubernetes Operator, 5 CRDs, instance/artifact management
19	falco-lsp.md	Language Server, CLI tool, VS Code extension for rules
20	falco-talon.md	Response Engine, actionners, automated threat response
21	driver-distribution.md	Pre-built driver pipeline, kernel-crawler, driverkit
22	ci-cd-infrastructure.md	Prow components, AWS EKS, config, Tide, Pigeon
23	ci-cd-jobs.md	Job catalog, org management, OWNERS workflow
24	ci-cd-github-actions.md	Falco Actions, CI/CD rules, testing suite

Quick Reference

Spec File	Primary Source Repo	Key Source Files	Digest Files
architecture-overview.md	falco, libs	app/app.cpp, app/state.h	falco/architecture.md, libs/architecture.md
kernel-instrumentation.md	libs	driver/modern_bpf/, driver/ppm_events_public.h	libs/kernel-instrumentation.md, libs/modern-bpf.md
libscap.md	libs	userspace/libscap/	libs/libscap.md
libsinsp.md	libs	userspace/libsinsp/	libs/libsinsp.md, libs/state-management.md
filter-engine.md	libs	userspace/libsinsp/filter/	libs/filtering.md
rule-engine.md	falco	userspace/engine/	falco/rule-language.md
configuration.md	falco	falco.yaml, configuration.cpp	falco/configuration.md
output-system.md	falco	falco_outputs.h	falco/outputs.md
plugin-system.md	libs, plugins	userspace/libsinsp/plugin*.cpp	libs/plugin-framework.md, plugins.md
metrics-and-observability.md	falco, libs	falco_metrics.cpp	falco/architecture.md
application-lifecycle.md	falco	app/	falco/architecture.md
cli-interface.md	falco	app/options.cpp	falco/cli-reference.md
falcoctl.md	falcoctl	cmd/, pkg/	falcoctl.md
build-system.md	falco, libs	CMakeLists.txt	falco/architecture.md
kubernetes-deployment.md	charts, deploy-kubernetes	charts/falco/values.yaml	charts.md, deploy-kubernetes.md
rules-content.md	rules	rules/falco_rules.yaml	rules.md
falcosidekick.md	falcosidekick	types/types.go, config_example.yaml	falcosidekick/README.md, falcosidekick/outputs.md
falco-operator.md	falco-operator	controllers/, api/	falco-operator.md
falco-lsp.md	falco-lsp	falco-lsp/internal/, vscode-extension/	falco-lsp.md
falco-talon.md	falco-talon	actionners/, internal/rules/	falco-talon.md
driver-distribution.md	test-infra, driverkit, dbg-go, kernel-crawler	driverkit/config/	driverkit.md, dbg-go.md, test-infra/drivers-build-grid.md, kernel-crawler.md
ci-cd-infrastructure.md	test-infra	config/config.yaml, config/plugins.yaml	test-infra/prow-infrastructure.md, test-infra/prow-config.md, pigeon.md
ci-cd-jobs.md	test-infra	config/jobs/, config/org.yaml	test-infra/prow-jobs.md, test-infra/github-org-management.md
ci-cd-github-actions.md	falco-actions, testing	start/action.yaml, action.yml	falco-actions.md, testing.md

Dependency Graph

kernel-instrumentation
         │
         ▼
      libscap ◄──── plugin-system
         │
         ▼
      libsinsp
         │
    ┌────┴────┐
    ▼         ▼
filter-engine  (state tables)
    │
    ▼
rule-engine ──────► output-system
    │                    │
    ▼                    ▼
configuration    application-lifecycle
                         │
                    ┌────┴────┐
                    ▼         ▼
            cli-interface  metrics-and-observability

falcoctl (standalone)
build-system (cross-cutting)

rules-content (detection content for rule-engine)
kubernetes-deployment (deploys Falco, uses falcoctl + configuration)
falcosidekick (ecosystem, receives from output-system via HTTP)
falco-talon (ecosystem, receives from falcosidekick or output-system)
falco-operator (ecosystem, manages Falco instances and artifacts in Kubernetes)
falco-lsp (ecosystem, validates rules against rule-engine/filter-engine grammar)
driver-distribution (builds drivers for kernel-instrumentation)

ci-cd-infrastructure ──► ci-cd-jobs ──► driver-distribution
                    └──► ci-cd-github-actions

Scope

These specifications cover:

• Core Falco: falco binary, falco_engine, output framework
• Core Libraries: libscap, libsinsp (from falcosecurity/libs)
• Drivers: Modern eBPF (default), kernel module
• Plugin System: API, capabilities, official plugins
• falcoctl: CLI management tool
• Build System: CMake structure, dependencies, feature flags
• Kubernetes Deployment: Helm charts, DaemonSet/Deployment topology, pod architecture
• Detection Rules: Rule content, maturity framework, tuning patterns
• Ecosystem: Falcosidekick (fan-out daemon), Falco Operator (Kubernetes-native management), Falco LSP (language tooling), Falco Talon (response engine), driver distribution pipeline
• CI/CD: Prow infrastructure, job catalog, GitHub Actions, organization management

Not covered in detail:

• Driverkit CLI details — driverkit build pipeline is covered in driver-distribution.md
• Deprecated features (legacy eBPF, gVisor, gRPC output) — brief mentions only

Guidelines

• All information includes source references traceable to refs/ or digests/
• Code references link to specific files with line numbers where applicable
• Each spec is self-contained with cross-references to related specs
• Designed for the workflow: read spec → understand implementation → modify code