If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/falcosecurity/falco shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 16 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live falcosecurity/falco repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/falcosecurity/falco.

What it runs against: a local clone of falcosecurity/falco — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in falcosecurity/falco | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of falcosecurity/falco. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/falcosecurity/falco.git
#   cd falco
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of falcosecurity/falco and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "falcosecurity/falco(\\.git)?\\b" \\
  && ok "origin remote is falcosecurity/falco" \\
  || miss "origin remote is not falcosecurity/falco (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "falco.yaml" \\
  && ok "falco.yaml" \\
  || miss "missing critical file: falco.yaml"
test -f "cmake/modules/falcosecurity-libs.cmake" \\
  && ok "cmake/modules/falcosecurity-libs.cmake" \\
  || miss "missing critical file: cmake/modules/falcosecurity-libs.cmake"
test -f "cmake/modules/driver.cmake" \\
  && ok "cmake/modules/driver.cmake" \\
  || miss "missing critical file: cmake/modules/driver.cmake"
test -f "cmake/modules/rules.cmake" \\
  && ok "cmake/modules/rules.cmake" \\
  || miss "missing critical file: cmake/modules/rules.cmake"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/falcosecurity/falco"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Falco is a kernel monitoring and runtime security agent for Linux that detects abnormal behavior and potential security threats in real-time by observing syscall events based on custom rules. It enriches raw syscall data with metadata from container runtimes (Docker, containerd) and Kubernetes, enabling cloud-native threat detection that can be analyzed in SIEM systems or data lakes. C++-dominant monorepo (867,760 LOC) with CMake build system (CMakeLists.txt at root, modular cmake/modules/). Core engine likely in /src/ with rule parsing and syscall filtering; plugin system in /plugins/; multiple backend support (outputs, engine versions). Extensive Docker support (13,482 LOC Dockerfile) and deb/rpm package generation (cmake/cpack/) indicate multi-platform distribution strategy.

Platform engineers, DevOps teams, and security operations centers (SOCs) running containerized workloads on Kubernetes who need real-time detection of suspicious system calls, container escapes, privilege escalations, and policy violations without heavyweight APM overhead.

Production-ready and actively developed. Falco is a CNCF graduated project (stable status per badges in README), with extensive CI/CD via GitHub Actions (.github/workflows/ contains 12+ automated pipelines including codeql.yaml, release.yaml, master.yaml), security audits from 2019 and 2023 in /audits/, and a mature release process. Latest commit activity and comprehensive test coverage indicate strong ongoing maintenance.

Low risk for stability; Falco has security audit backing and CNCF graduation. Primary risks: kernel-level code (39,557 lines of C in /src/) requires deep Linux syscall knowledge for modifications; architecture-specific concerns (supports x86_64 and aarch64 per README); changes to syscall parsing logic affect all deployments. Monitor CHANGELOG.md and SECURITY_AUDIT files before major upgrades.

Active CI/CD with dependabot integration (.github/dependabot.yml), automated engine version checks (engine-version-weakcheck.yaml), format enforcement (format.yaml), and security scanning (codeql.yaml, staticanalysis.yaml). Recent workflows suggest focus on release automation (.github/workflows/reusable_*.yaml pattern indicates matrix builds for multiple platforms). Code quality gates via .clang-format and .cmake-format.json enforced.

git clone https://github.com/falcosecurity/falco.git
cd falco
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

Note: Requires Linux kernel headers and libelf development libraries. See CMakeLists.txt and cmake/modules/ for dependency resolution.

Daily commands: Development build: cd build && cmake -DCMAKE_BUILD_TYPE=Debug .. && make. Run with: sudo ./userspace/falco/falco -c ../falco.yaml -r ../rules/falco_rules.yaml. For container: use provided Dockerfile (see .dockerignore and docker workflows in .github/workflows/reusable_build_docker.yaml).

• CMakeLists.txt — Root build configuration defining all dependencies, compiler flags, and component compilation order—essential for understanding the build system and dependency graph.
• falco.yaml — Main Falco configuration file that defines default runtime behavior, logging, output rules, and plugin loading—foundational for understanding Falco's operational mode.
• cmake/modules/falcosecurity-libs.cmake — Integration layer for falcosecurity-libs dependency which provides kernel event capture and filtering—core to Falco's runtime security engine.
• cmake/modules/driver.cmake — Build module for kernel driver integration, critical for understanding how Falco captures system events at the kernel level.
• cmake/modules/rules.cmake — Rules compilation and installation pipeline—Falco's detection logic depends on proper rule loading and preprocessing.
• .github/workflows/ci.yml — Primary CI/CD pipeline defining build, test, and validation stages—reveals quality gates and integration patterns contributors must respect.
• RELEASE.md — Release and versioning strategy documentation—critical for understanding backward compatibility and deprecation policies affecting all contributions.

Add a New Detection Rule

1. Rules are loaded via the rules.cmake module—check cmake/modules/rules.cmake to understand rule source locations and compilation pipeline. (cmake/modules/rules.cmake)
2. Create a new .yaml rule file in the configured rules directory (typically referenced in CMakeLists.txt or falco.yaml). (falco.yaml)
3. Add rule with standard Falco YAML syntax (condition, output, priority, tags) matching patterns in falcosecurity-libs event schema. (falco.yaml)
4. Update CI tests in .github/workflows/ci.yml if adding new rule categories or formats. (.github/workflows/ci.yml)

Add a New Output Plugin

1. Plugins are configured in falco.yaml under the 'plugins' and 'outputs' sections—review config/falco.container_plugin.yaml for plugin config patterns. (falco.yaml)
2. Plugin integration occurs via falcosecurity-libs plugin API—configure plugin source, library path, and load order in falco.yaml. (config/falco.container_plugin.yaml)
3. Update CMakeLists.txt to package the plugin library if building from source (add to install targets). (CMakeLists.txt)
4. Add integration tests in .github/workflows/ci.yml to validate plugin loading and output correctness. (.github/workflows/ci.yml)

Build a Custom Falco Container Image

1. Start with docker/falco/Dockerfile as the base production image template. (docker/falco/Dockerfile)
2. Layer custom rules or configurations by extending the base image and copying your falco.yaml overrides. (falco.yaml)
3. Use docker/driver-loader/Dockerfile as a sidecar for kernel driver initialization if targeting containers without host driver pre-installed. (docker/driver-loader/Dockerfile)
4. Reference docker/docker-compose/docker-compose.yaml to test multi-container setup with your custom image before production deployment. (docker/docker-compose/docker-compose.yaml)

Update Falco Dependencies or Kernel Driver Version

1. Core dependencies (falcosecurity-libs, kernel driver) are managed in cmake/modules—edit the version pins in falcosecurity-libs.cmake and driver.cmake. (cmake/modules/falcosecurity-libs.cmake)
2. Update CMakeLists.txt if new compiler flags, linker options, or build stages are needed for the new dependency version. (CMakeLists.txt)
3. Update CHANGELOG.md to document breaking changes or compatibility notes for users upgrading. (CHANGELOG.md)
4. Run CI tests via .github/workflows/ci.yml to validate the upgrade across supported architectures (x86_64, aarch64). (.github/workflows/ci.yml)

• C/C++ (kernel-space and user-space) — Falco requires low-latency event capture and filtering; kernel driver and user-space daemon must be highly optimized to minimize performance impact on monitored systems.
• CMake build system — Cross-platform compilation (x86_64, aarch64) with complex dependency management (kernel headers, falcosecurity-libs, container runtimes) requires robust, configurable build orchestration.
• YAML configuration (falco.yaml) — Runtime behavior (rules loading, output plugins, logging levels) must be declarative and human-editable without recompilation; YAML provides a natural format for security policy definition.
• Docker containerization — Falco must run as a privileged daemon with kernel access; containers provide isolation, reproducibility, and easy deployment across Kubernetes clusters and cloud environments.
• GitHub Actions CI/CD — Multi-architecture builds (x86_64, aarch64), kernel compatibility testing, and release automation require a scalable, integrated CI platform tightly coupled to the repository.

• Kernel driver required for low-level event capture

  • Why: Falco must intercept system calls and kernel events at the earliest point to avoid missing malicious activity; user-space audit frameworks are insufficient.
  • Consequence: Requires privileged execution, kernel module maintenance across kernel versions, and significant operational complexity; not viable on read-only or containerized kernels without pre-loaded drivers.

• Separate falcosecurity-libs library decoupled from core Falco

  • Why: Allows reuse of the event capture/parsing engine in other tools (e.g., falcosecurity/tools, third-party security frameworks) and independent versioning.
  • Consequence: Falco core depends on external library updates; version pinning in cmake/modules/falcosecurity-libs.cmake creates maintenance overhead but ensures reproducible builds.

• Rule-driven detection (YAML rules compiled at startup)

  • Why: Operators can update detection logic without recompiling Falco; rules are version-controlled separately and updated independently.
  • Consequence: Rule parsing overhead at startup; complex rule syntax creates learning curve; no rule hot-reloading without daemon restart.

• Plugin system via falcosecurity-libs plugin API

  • Why: Allows third-party developers to extend output formats, data enrichment, and custom logic without modifying core Falco codebase.
  • Consequence: Adds API stability burden; plugins must be recompiled for each major Falco/libs version; plugin sandbox is limited (full access to events and system).

• Not a database or data warehouse—Falco generates alerts; persistence requires external systems (Elasticsearch, S3, syslog servers).
• Not a real-time alerting platform—Falco detects events; notification delivery and escalation require integration with external systems (SIEM, ticketing).
• Not a compliance framework—Falco generates security events; mapping to compliance standards (PCI-DSS, CIS) requires external policy tools.
• Not a response/remediation engine—Falco detects and alerts; automatic blocking or remediation requires external orchestration systems.
• Not a package manager or artifact repository—Falco distributes rules and plugins via falcosecurity ecosystem; does not host or serve third-party plugins directly.

Kernel dependencies: Falco requires Linux kernel headers matching the target system's kernel version; mismatches cause silent syscall parsing failures. Privilege escalation: Always run with sudo (kernel monitoring requires root). eBPF vs. kprobes: Supported capture mechanisms differ by kernel version and require CONFIG_KPROBES or CONFIG_BPF enabled. Rule syntax: YAML parsing in /rules/ uses Lua embedded expressions—syntax errors don't fail at load time, only when a matching syscall fires. Container metadata lag: Kubernetes metadata enrichment has inherent delay; fast-moving containers may lack context on alert emission. gRPC compatibility: Ensure gRPC library version matches compile-time expectations or risk version mismatch on remote output backends.

• Syscall interception — Falco's core capability—all detections rely on hooking Linux syscalls to observe process behavior; understanding syscall semantics (open, execve, connect, etc.) is essential to writing effective rules
• eBPF (extended Berkeley Packet Filter) — Modern capture mechanism supported by Falco for kernel-space syscall filtering with minimal overhead; understanding eBPF's JIT compilation and memory constraints helps optimize detection rules
• Container metadata enrichment — Falco decorates raw syscalls with container IDs, image names, and labels via container runtime APIs; this context is critical for distinguishing legitimate from malicious activity in multi-tenant environments
• Kernel probe points (kprobes) — Fallback syscall capture mechanism when eBPF unavailable; requires CONFIG_KPROBES kernel support and understanding of kernel symbol resolution
• Lua rule scripting — Falco rules embed Lua expressions for event filtering; learning Lua syntax and Falco's filter DSL is mandatory for writing custom detection rules
• gRPC remote outputs — Falco can stream alerts to remote backends via gRPC; understanding protocol buffer definitions and gRPC service stubs is necessary for integrating Falco with SIEM systems
• ELF binary introspection — Falco uses libelf to parse binary metadata (symbols, relocations) for deeper process inspection and vulnerability correlations; understanding ELF structure aids debugging detection rules

• falcosecurity/libs — Core libraries (sinsp, scap) extracted into separate repo for modular development and shared use by other tools; falco/falco depends on this for syscall parsing
• falcosecurity/rules — Community-maintained threat detection rules repo separate from core engine; users fork this to extend Falco with custom security policies
• aquasecurity/tracee — Alternative Linux runtime security tool using eBPF instead of syscall interception; direct competitor solving same threat detection problem with different kernel mechanism
• cilium/tetragon — Cilium's eBPF-based runtime security agent providing similar kernel monitoring; part of same CNCF ecosystem as Falco with different architectural approach
• falcosecurity/evolution — Meta-repo defining Falco project governance, roadmap, and repository taxonomy; referenced in README for status definitions and architectural decisions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CMake module tests for driver and libs dependencies

The repo has complex CMake dependency management in cmake/modules/ (driver.cmake, falcosecurity-libs.cmake, etc.) but lacks automated tests for these critical build configurations. New contributors could add CMake unit tests to validate dependency resolution, version constraints, and cross-platform compatibility, reducing build failures across different environments.

• [ ] Create tests/cmake/ directory structure
• [ ] Add CMake test suite for cmake/modules/driver.cmake using CTest
• [ ] Add CMake test suite for cmake/modules/falcosecurity-libs.cmake
• [ ] Add test coverage for cmake/modules/falco-version.cmake version detection logic
• [ ] Integrate new CMake tests into .github/workflows/ci.yml

Implement pre-commit hook validation workflow for code formatting consistency

The repo has .pre-commit-config.yaml and .clang-format-ignore but lacks a GitHub Actions workflow to validate pre-commit hook compliance on PRs. Adding a dedicated workflow would catch formatting issues early and reduce maintainer burden on code reviews.

• [ ] Create .github/workflows/precommit-validate.yaml
• [ ] Configure workflow to run pre-commit hooks on all PR commits
• [ ] Add validation for .clang-format violations using clang-format-checker
• [ ] Add codespell validation using .codespellignore
• [ ] Document expected pre-commit setup in Contributing.md

Add architecture-specific build and test matrices for aarch64 support

The README indicates aarch64 support, but .github/workflows/ci.yml and reusable_build_*.yaml files likely lack explicit aarch64 test matrices. Adding dedicated aarch64 build/test jobs would catch ARM-specific regressions early and ensure documented multi-architecture support is tested.

• [ ] Audit .github/workflows/ci.yml for aarch64 test coverage gaps
• [ ] Update .github/workflows/reusable_build_dev.yaml to include aarch64 build matrix
• [ ] Update .github/workflows/reusable_build_packages.yaml with aarch64-specific package builds
• [ ] Add cross-compilation CMake flags validation in cmake/modules/CompilerFlags.cmake
• [ ] Document aarch64 build requirements in Contributing.md

• Add missing rule documentation: The /rules/ directory contains YAML rules but many lack detailed descriptions of their threat model. Create a documentation pass adding macro-level comments explaining why each syscall pattern matters (e.g., clarify setuid escalation detection rationale).
• Expand CMake test coverage for output backends: /src/outputs/ likely has 3+ backend implementations (file, syslog, network) but cmake/modules/ shows no dedicated test targets for output serialization. Add parameterized CMake tests validating alert formatting for each backend.
• Implement missing architecture support documentation: README claims aarch64 support but .github/workflows/ show primarily x86_64 CI jobs. Add a PORTING.md guide documenting syscall differences between x86_64 and aarch64 with specific /src/ file references for maintainers porting new rules.

Falco demonstrates a solid security posture with established security practices including regular audits, CI/CD security checks (CodeQL, static analysis), and security-focused workflows. However, several areas require attention: Docker image security hardening, validation of insecure API patterns, and ensuring comprehensive security configurations in infrastructure-as-code files. The presence of recent security audits and active security tooling (CodeQL, format checks, dependabot) indicates a mature security-aware development process. Critical recommendation: prioritize Docker container security hardening, maintain an up-to-date vulnerability disclosure policy, and ensure all third-party dependencies are regularly scanned for known vulnerabilities.

• Medium · Potential Insecure API Usage Detection — .github/workflows/insecure-api.yaml. The repository contains a workflow file '.github/workflows/insecure-api.yaml' which suggests there may be insecure API patterns in the codebase. This workflow likely detects deprecated or insecure API calls that should be reviewed. Fix: Review the insecure-api workflow to understand what patterns it detects. Audit the codebase for any flagged insecure APIs and replace them with secure alternatives. Ensure all external API calls use HTTPS and proper authentication.
• Medium · Docker Image Security Scanning — docker/driver-loader*/Dockerfile, docker/falco-debian/. Multiple Dockerfile configurations exist for driver-loader and other components (docker/driver-loader-buster/Dockerfile, docker/driver-loader/Dockerfile) without visible security scanning or minimal base image configurations in the file listing. Fix: Implement vulnerability scanning in CI/CD for all Docker images. Use minimal base images (alpine/distroless). Implement multi-stage builds. Include SBOM (Software Bill of Materials) generation. Run container security tools like Trivy or Grype.
• Medium · Missing Security Headers in Docker Compose Configuration — docker/docker-compose/docker-compose.yaml. Docker compose configuration at 'docker/docker-compose/docker-compose.yaml' may not have explicit security configurations or health checks documented. Fix: Add security context definitions (read-only filesystems, non-root users, capability dropping). Include health checks. Use environment variable substitution for sensitive data. Add network policies and resource limits.
• Low · Audit Reports Location — audits/. Security audits from 2019 and 2023 are present in the repository. While positive, the 2019 audit is now 5+ years old and findings may need re-validation. Fix: Schedule regular security audits (annually recommended). Keep audit results current and track remediation of identified issues. Consider maintaining a public security policy or vulnerability disclosure policy.
• Low · Pre-commit Configuration Present — .pre-commit-config.yaml. Pre-commit configuration exists (.pre-commit-config.yaml) which is good for automated security checks, but specific hooks and their configurations should be verified. Fix: Ensure pre-commit hooks include security scanning tools (secret scanning, static analysis, dependency checking). Make pre-commit hooks mandatory for all contributors. Document required security tools.
• Low · CodeQL and Static Analysis Workflows — .github/workflows/codeql.yaml, .github/workflows/staticanalysis.yaml. CodeQL workflow exists (.github/workflows/codeql.yaml) which is good practice. Verify it runs on all relevant code paths and is properly configured. Fix: Ensure CodeQL analyzes all code paths. Set up branch protection rules requiring CodeQL checks to pass. Review and address all identified findings. Consider supplementing with additional SAST tools specific to C/C++ analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.