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/draios/sysdig 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 4w ago
• 7 active contributors
• Other licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 92% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{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 draios/sysdig repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/draios/sysdig.

What it runs against: a local clone of draios/sysdig — 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 draios/sysdig | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 56 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of draios/sysdig. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/draios/sysdig.git
#   cd sysdig
#
# 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 draios/sysdig and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
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 "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "coding_conventions.md" \\
  && ok "coding_conventions.md" \\
  || miss "missing critical file: coding_conventions.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 56 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~26d)"
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/draios/sysdig"
  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).

Sysdig is a system visibility and troubleshooting tool that instruments the Linux kernel to capture system calls and OS events, providing deep container inspection without container modification. It unifies traditional Linux tools (strace, tcpdump, htop, lsof) into a single interface with native container support, and includes csysdig—a curses-based interactive UI for real-time exploration. Monolithic C++ codebase with modular cmake build: core system call capture logic in src/ (inferred), Lua scripting support for filters/outputs, separate curses UI for csysdig, kernel driver code in separate driver-repo submodule, and driverkit Python tooling for cross-kernel binary distribution. Falcosecurity-libs provides the foundational event capture library.

DevOps engineers, SREs, and system administrators who need to troubleshoot containerized Linux workloads and diagnose system-level performance issues without SSH-ing into machines or instrumenting containers themselves.

Production-ready and actively developed. The project has official GitHub CI/CD pipelines (build-drivers.yaml, ci.yaml, release workflows), Docker distributions, and deb/rpm packaging. The codebase is substantial (506K lines of C++, 348K of Lua) with documented coding conventions and security policy, indicating mature maintenance.

Moderate risk: the project depends on kernel driver compilation (scap-driver-toolchains, driver.cmake, driverkit/) which can break across kernel versions, and relies heavily on falcosecurity-libs as a submodule. Single source of truth for container inspection means bugs here impact visibility tools across the ecosystem. Last activity visible in CI workflows suggests active maintenance, but kernel-level code requires deep expertise to modify safely.

Active CI/CD maintenance visible in workflows (build-drivers.yaml, ci-check.yaml, release-draft.yaml). The repo actively builds and releases deb/rpm packages, maintains driverkit Python tooling for driver compilation, and has Docker image distribution. GitHub Actions workflows indicate ongoing testing and release automation.

git clone https://github.com/draios/sysdig.git
cd sysdig
mkdir build && cd build
cmake ..
make
sudo ./sysdig  # Requires elevated privileges for kernel access

Or run via pre-built container: sudo docker run --rm -i -t --privileged --net=host -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro docker.io/sysdig/sysdig

Daily commands: After cmake .. && make in build/ directory: sudo ./sysdig for CLI capture, or sudo ./csysdig for interactive UI. Use -w flag to write capture files, -r to read them. Run with -h for filter/output options. Requires Linux with CAP_SYS_RESOURCE or root.

• CMakeLists.txt — Root build configuration that orchestrates the entire sysdig compilation, dependency resolution, and driver integration—essential for understanding the build system and project structure.
• cmake/modules/falcosecurity-libs.cmake — Integrates the falcosecurity-libs dependency which provides core system event capture and filtering infrastructure that sysdig depends on.
• cmake/modules/driver.cmake — Manages kernel driver compilation and integration, critical for sysdig's low-level system event capture capability.
• README.md — Defines the project's vision, primary use cases (system visibility, container support), and installation patterns that guide feature development.
• coding_conventions.md — Establishes code style and contribution standards that all contributors must follow to maintain consistency.
• SECURITY.md — Documents the vulnerability reporting process and security policies that all maintainers and contributors must follow.
• .github/workflows/ci.yaml — Defines the continuous integration pipeline covering builds, tests, and validations that gate all contributions.

Add Support for a New Kernel Version/Architecture

1. Create a new driver configuration YAML file under scripts/driverkit/config/7.3.0+driver/{arch}/ following the naming convention kernel_version_arch_1.yaml (scripts/driverkit/config/7.3.0+driver/aarch64/alinux_4.19.67-16.al7.aarch64_1.yaml)
2. Add build parameters specific to the target kernel (probe URL, kmod target, eBPF flags) in the YAML configuration (scripts/driverkit/config/7.3.0+driver/aarch64/alinux_4.19.67-16.al7.aarch64_1.yaml)
3. Run driverkit build process which references the configuration: python scripts/driverkit/build/build.py (scripts/driverkit/build/build.py)
4. Verify the CI workflow picks up the new configuration in .github/workflows/build-drivers.yaml to auto-compile on next release (.github/workflows/build-drivers.yaml)

Add a New Linux Distribution Package Target

1. Create packaging metadata and post-install logic in scripts/debian/postinst.in for Debian-based distros (or equivalent for RPM) (scripts/debian/postinst.in)
2. Configure CMakeCPackOptions.cmake to define package generators (DEB, RPM) and custom settings per distro (CMakeCPackOptions.cmake)
3. Update the CI workflow .github/workflows/ci.yaml to build and test packages for the new target distribution (.github/workflows/ci.yaml)
4. Document installation instructions in README.md for the newly supported distribution (README.md)

Integrate a New External Dependency (e.g., library or tool)

1. Create a new CMake module under cmake/modules/yourlib.cmake that downloads, configures, and links the dependency (cmake/modules/ncurses.cmake)
2. Reference the new module in the root CMakeLists.txt via include() and add it to target_link_libraries() for sysdig or csysdig targets (CMakeLists.txt)
3. If the dependency requires special handling for containers, update docker/sysdig/Dockerfile to pre-install it in the Docker image (docker/sysdig/Dockerfile)
4. Add the dependency to project documentation (NOTICES file) and verify license compliance with COPYING and SECURITY.md guidelines (NOTICES)

Add Shell Completion Support for a New Shell

1. Create completion script following the pattern in scripts/completions/bash/sysdig for your target shell (e.g., fish, ksh) (scripts/completions/bash/sysdig)
2. Ensure the completion script is installed via CMakeLists.txt by adding install rules referencing the scripts/completions directory (CMakeLists.txt)
3. Test the completion script in your shell and verify Debian/RPM package post-install scripts (scripts/debian/postinst.in) register it correctly (scripts/debian/postinst.in)

• CMake — Cross-platform build system allowing sysdig to compile consistently across Linux distributions, architectures (x86_64, ARM64), and kernel versions with minimal maintenance burden.
• Falcosecurity-libs — Provides the core system event capture abstraction, kernel driver integration (kmod + eBPF), container runtime metadata enrichment, and filtering engine—allowing sysdig to focus on UI/UX rather than low-level tracing.
• undefined — undefined

Kernel driver compilation is version-specific and can fail silently if kernel headers are missing (requires linux-headers package). Requires CAP_SYS_RESOURCE or root to run—development without sudo requires special setup. The falcosecurity-libs submodule must be initialized (git submodule update --init --recursive) or build will fail with cryptic CMake errors. eBPF/kmod driver selection is automatic based on kernel version but may not work on all kernel configurations (e.g., unprivileged containers without CAP_BPF). Lua script paths are hardcoded relative to install prefix; custom scripts need correct library search paths.

• Kernel system call tracing — Sysdig's entire value proposition depends on capturing syscalls at the OS level; understanding how strace, eBPF, and kprobes differ is critical for kernel-level debugging
• Extended Berkeley Packet Filter (eBPF) — Modern sysdig uses eBPF instead of kernel modules for syscall capture on newer kernels; knowledge of eBPF is essential for optimizing or modifying instrumentation
• Container namespace isolation (cgroups, namespaces) — Sysdig's container-native capability relies on inspecting container namespaces without modifying containers; understanding pid/net/ipc namespaces is needed to modify container filtering
• Lua scripting for output filtering — Lua scripts in src/lua/ define custom filters and output formats; modifying capture behavior requires understanding Lua/C++ FFI integration in sysdig
• Ring buffer event streaming — Sysdig captures events into kernel ring buffers before userspace processing; understanding buffering and overflow handling is critical for high-volume syscall scenarios
• Curses terminal UI (ncurses) — csysdig uses ncurses for interactive real-time visualization; understanding event-driven TUI patterns is needed to modify the interactive UI
• Trace file format and replay — Sysdig's ability to save captures to trace files and replay them offline (like tcpdump/Wireshark) requires understanding custom binary format and stateful event reconstruction

• falcosecurity/falco — Rule-based threat detection engine that uses sysdig's core libraries (falcosecurity-libs) for syscall capture and wraps it with security policies
• falcosecurity/libs — The falcosecurity-libs submodule that sysdig depends on; contains the actual kernel instrumentation and syscall parsing logic
• draios/csysdig-container-defaults — Container-specific UI configurations and filter presets for csysdig to simplify container troubleshooting workflows
• aquasecurity/tracee — Alternative Linux runtime security and observability tool using eBPF; solves similar kernel-level visibility problem with different architecture
• brendangregg/perf-tools — Collection of performance analysis scripts using traditional Linux tools; sysdig aims to replace many of these with a unified interface

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 unit tests for CMake modules and build configuration

The repo has complex CMake build infrastructure (cmake/modules/) for managing dependencies like falcosecurity-libs, driver-repo, luajit, ncurses, yaml-cpp, and nlohmann-json, but there are no visible CMake testing workflows. Adding unit tests for CMake modules would catch build configuration regressions across different dependency versions and platforms early.

• [ ] Create tests/cmake/ directory with CMake test files
• [ ] Add unit tests for cmake/modules/falcosecurity-libs.cmake to verify library discovery
• [ ] Add unit tests for cmake/modules/driver.cmake to validate driver configuration
• [ ] Create a new GitHub Actions workflow in .github/workflows/ (e.g., cmake-tests.yaml) to run CMake tests on multiple configurations
• [ ] Document CMake testing approach in coding_conventions.md

Expand driverkit build configuration coverage and add validation workflow

The scripts/driverkit/config/ directory contains many kernel-specific configurations (7.3.0+driver/) but lacks validation and test coverage. A new workflow to validate these YAML configs against a schema and test cross-architecture builds would prevent configuration drift and build failures.

• [ ] Create a JSON schema file for driverkit YAML configs (scripts/driverkit/config/schema.json)
• [ ] Add Python script in scripts/driverkit/ to validate all YAML files against the schema
• [ ] Create GitHub Actions workflow (.github/workflows/driverkit-config-check.yaml) to validate configs on every PR
• [ ] Document driverkit configuration guidelines in coding_conventions.md with examples

Add missing shell completion tests and documentation for bash/zsh completions

The repo provides bash and zsh completion scripts (scripts/completions/) but lacks automated tests to verify completion functions work correctly and CI validation. Adding completion tests would catch regressions when sysdig options change.

• [ ] Create tests/completions/ directory with bash/zsh completion test scripts
• [ ] Add bats (Bash Automated Testing System) tests for scripts/completions/bash/sysdig
• [ ] Add zsh completion tests using zsh test framework for scripts/completions/zsh/_sysdig
• [ ] Add GitHub Actions workflow (.github/workflows/completions-test.yaml) to run completion tests
• [ ] Document how to test completions locally in coding_conventions.md

• Add shell completion tests: scripts/completions/bash and scripts/completions/zsh exist but likely have no integration tests. Write pytest/bats tests to verify completion suggestions against actual sysdig filter syntax.
• Document driverkit build.py: scripts/driverkit/build/build.py has no inline documentation and poetry.lock suggests complex dependencies. Add docstrings explaining each build stage and add a README.md to scripts/driverkit/build/ for contributors.
• Expand CMake test coverage: CMakeListsGtestInclude.cmake suggests gtest integration exists but is minimal. Create unit tests for Lua filter parsing or JSON output serialization using the existing gtest framework.

Sysdig is a system visibility tool requiring elevated privileges by design. The codebase demonstrates reasonable security practices with a dedicated SECURITY.md file and active CI/CD pipelines. Primary concerns relate to the inherent trust model required when running privileged containers and the broad host filesystem access needed for system inspection. The main vulnerabilities are design-related rather than implementation issues. Security documentation could be significantly enhanced to help users understand the trust boundaries and deployment best practices. No critical code-level vulnerabilities were identified in the static analysis of the provided file structure.

• Medium · Privileged Docker Container Execution — README.md - Getting Started section. The README documentation shows running sysdig in a Docker container with --privileged flag, which grants full access to the host system. While necessary for system visibility tools, this should be clearly documented with security warnings about the risks and trust requirements. Fix: Add security warnings in the README about the implications of running privileged containers. Consider providing a non-privileged alternative with limited capabilities if possible, and recommend users only run this with trusted images from official sources.
• Medium · Host Filesystem Access in Container — README.md - Docker run command example. The Docker example mounts multiple host directories including /boot, /lib/modules, /usr, /etc, and /var/run/docker.sock into the container. This broad host access increases the attack surface if the container is compromised. Fix: Document the minimum required mounts for different use cases. Consider creating a matrix showing which mounts are optional vs. required for specific features. Add warnings about the security implications of exposing docker.sock.
• Low · Missing Security Headers Documentation — README.md, SECURITY.md. No documentation found regarding security best practices for deploying sysdig in production environments, such as RBAC, network policies, or security contexts in Kubernetes. Fix: Create comprehensive security documentation including: Kubernetes security contexts, network policies, RBAC recommendations, audit logging best practices, and container security guidelines.
• Low · Dependency Management Visibility — CMakeLists.txt, cmake/modules/. While the repository uses CMake for dependency management, there is limited visibility into specific version pinning and dependency vulnerability scanning in the provided file structure. Fix: Implement automated dependency scanning in CI/CD pipelines. Use tools like Dependabot or similar to track vulnerabilities in dependencies. Pin specific versions in dependency files and document security update procedures.
• Low · Missing Security.md Details — SECURITY.md. The SECURITY.md file only contains a contact email and lacks detailed information about vulnerability disclosure timeline, scope, and acknowledgment process. Fix: Expand SECURITY.md with: vulnerability disclosure timeline (e.g., 90-day policy), scope of security program, out-of-scope items, bug bounty information if applicable, acknowledgment practices, and PGP key for encrypted submissions.

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.