# willfindlay/bpfcontain-rs architecture

> Architecture diagram of the GitHub repository willfindlay/bpfcontain-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/willfindlay/bpfcontain-rs
- Repository: https://github.com/willfindlay/bpfcontain-rs

## Overview

##### Project Type & Purpose
- BPFContain is a Linux container-security daemon written in Rust that leverages eBPF.
- It compiles and loads BPF programs into the kernel to enforce user-defined policies (YAML) on running processes/containers.

##### File Structure & Key Indicators
- src/cli.rs, src/main.rs, src/subcommands/... → CLI binary with subcommands (“daemon,” “run,” “confine”).
- src/bpf/*.c + src/bpf_program.rs + build.rs → BPF programs in C + Rust loader + build script generating vmlinux.h/BTF.
- src/policy → Policy language parser & rule engine.
- config/*.yml, examples/*.yml → Policy/configuration files.
- tests/…, examples/, scripts/ → CI, integration tests, example policies.
- DOCKER.md, Vagrantfile → Deployment/quick-start helpers.

##### Readme Insights
- Daemon runs in user–space to load/attach BPF to kernel.
- Policies in YAML drive enforcement logic.
- Dependencies: clang/LLVM (to compile BPF), bpftool (generate BTF), Rust toolchain.

##### Main Architectural Components
a. User-Space CLI & Daemon
– bpfcontain binary with three modes:
- daemon: boots up, loads/attaches BPF programs, monitors state
- run: spawn confined process under current policy
- confine: helper to enter existing namespace under policy
b. Configuration & Policy Engine
– Reads YAML policy (examples/*.yml) via src/config.rs + src/policy/*.rs
c. Build & BPF Loader
– build.rs invokes clang/LLVM to compile C programs (src/bpf/*.c) into .o
– Generates vmlinux.h/BTF for kernel types
– src/bpf_program.rs + src/bindings/*.rs wrap low-level BPF syscall APIs
d. Kernel-Space BPF Programs
– eBPF probes (tracepoints, LSM hooks) that enforce I/O, networking, file operations
– BPF maps hold per-process state, policy tables
e. Kernel Interaction
– Attaches BPF programs via BPF syscall to designated LSM hooks/tracepoints
– On enforcement triggers, BPF may kill or log events
f. Logging & Audit
– src/log.rs collects audit events via perf ring buffer or tracepoints
– Writes logs/metrics to syslog or files (config/logrotate)

##### Relationships & Data Flows
- User invokes “bpfcontain daemon start” → CLI parses args → policy loader reads YAML → BPF loader compiles & loads eBPF → attaches to kernel.
- Running processes generate syscalls/events → kernel invokes eBPF programs → enforcement decision (allow/deny) → event logged in BPF map or perf buffer → user-space daemon reads buffer → writes to log.
- “bpfcontain run <policy>” forks process under configured seccomp or namespace (via src/ns.rs), then the daemon’s BPF policies apply.

##### Architectural Patterns & Design Principles
- Layered design: CLI/Config → Policy Engine → BPF Loader → Kernel
- Separation of concerns:
- Policy parsing & validation (Rust)
- BPF program compilation/attachment (build.rs + Rust bindings)
- Enforcement logic in kernel (C)
- Logging/Auditing in user-space (Rust)
- Safe systems language (Rust) used for user-space control; C only in minimal in-kernel surface area.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Tools
    subgraph "External Tools"
        clang["clang/LLVM"]:::external
        bpftool["bpftool"]:::external
    end

    %% User-Space CLI & Daemon
    subgraph "User-Space CLI & Daemon"
        main["main.rs"]:::userspace
        cli["cli.rs"]:::userspace
        sub_mod["subcommands/mod.rs"]:::userspace
        sub_daemon["subcommands/daemon.rs"]:::userspace
        sub_run["subcommands/run.rs"]:::userspace
        sub_confine["subcommands/confine.rs"]:::userspace
        ns_rs["ns.rs"]:::userspace
    end

    %% Configuration & Policy Engine
    subgraph "Config & Policy Engine"
        config_rs["config.rs"]:::userspace
        policy_mod["policy/mod.rs"]:::userspace
        rules_rs["policy/rules.rs"]:::userspace
        helpers_rs["policy/helpers.rs"]:::userspace
        default_yml["config/default.yml"]:::config
        example_policies["examples/*.yml"]:::config
    end

    %% Build Script & BPF Compiler
    subgraph "Build Script & BPF Compiler"
        build_rs["build.rs"]:::userspace
        cargo_toml["Cargo.toml"]:::userspace
        bpf_program_rs["bpf_program.rs"]:::userspace
    end

    %% BPF Loader & Rust Bindings
    subgraph "BPF Loader & Rust Bindings"
        bindings_mod["bindings/mod.rs"]:::userspace
        audit_bind["bindings/audit.rs"]:::userspace
        ioctl_bind["bindings/ioctl.rs"]:::userspace
        policy_bind["bindings/policy.rs"]:::userspace
        state_bind["bindings/state.rs"]:::userspace
    end

    %% Kernel-Space eBPF Programs
    subgraph "Kernel-Space eBPF Programs"
        bpf_c["bpf/bpfcontain.bpf.c"]:::kernel
        include_h["bpf/include/*.h"]:::kernel
        maps["BPF Maps (PID→Rules)"]:::kernel
        probes["eBPF Probes (LSM hooks/tracepoints)"]:::kernel
    end

    %% Logging & Audit Subsystem
    subgraph "Logging & Audit"
        log_rs["log.rs"]:::userspace
        perf_buf["Perf Ring Buffer"]:::kernel
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        utils_rs["utils.rs"]:::userspace
        uprobe_ext["uprobe_ext.rs"]:::userspace
    end

    %% Tests & CI
    subgraph "Tests & CI"
        test_policy["tests/policy_enforcement.rs"]:::test
        test_bpf_wrap["tests/helpers/bpf_wrapper.rs"]:::test
        test_ioctl["tests/ioctl/ioctl.c"]:::test
        ci_yaml[".github/workflows/ci.yml"]:::test
        run_ci["scripts/run-ci.sh"]:::test
    end

    %% Deployment & Examples
    subgraph "Deployment & Examples"
        docker_md["DOCKER.md"]:::docs
        vagrant["Vagrantfile"]:::docs
        examples_readme["examples/README.md"]:::docs
    end

    %% Connections - Control Flow
    clang -->|compile BPF| build_rs
    bpftool -->|generate BTF| build_rs
    build_rs -->|invokes| bpf_c
    main -->|parses args| cli
    cli -->|calls| sub_mod
    sub_mod --> sub_daemon
    sub_mod --> sub_run
    sub_mod --> sub_confine
    sub_run -->|forks via| ns_rs
    sub_confine -->|enters namespace| ns_rs
    sub_daemon -->|loads policies| config_rs
    config_rs --> policy_mod
    policy_mod --> rules_rs
    policy_mod --> helpers_rs
    default_yml --> config_rs
    example_policies --> config_rs
    bpf_program_rs --> bindings_mod
    bindings_mod --> audit_bind
    bindings_mod --> ioctl_bind
    bindings_mod --> policy_bind
    bindings_mod --> state_bind
    sub_daemon -->|calls| bpf_program_rs
    bpf_program_rs -->|loads| audit_bind
    state_bind -->|BPF syscall| probes
    probes -->|attach to| maps
    probes -->|reads/writes| maps
    probes -->|send events| perf_buf
    perf_buf -->|read by| log_rs
    log_rs -->|writes to| docker_md

    %% Data Flow - Dashed
    probes -.->|events| test_policy
    probes -.-> test_bpf_wrap
    probes -.-> test_ioctl

    %% Click Events
    click main "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/main.rs"
    click cli "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/cli.rs"
    click sub_daemon "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/subcommands/daemon.rs"
    click sub_run "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/subcommands/run.rs"
    click sub_confine "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/subcommands/confine.rs"
    click sub_mod "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/subcommands/mod.rs"
    click config_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/config.rs"
    click policy_mod "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/policy/mod.rs"
    click rules_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/policy/rules.rs"
    click helpers_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/policy/helpers.rs"
    click default_yml "https://github.com/willfindlay/bpfcontain-rs/blob/master/config/default.yml"
    click example_policies "https://github.com/willfindlay/bpfcontain-rs/blob/master/examples/*.yml"
    click build_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/build.rs"
    click cargo_toml "https://github.com/willfindlay/bpfcontain-rs/blob/master/Cargo.toml"
    click bpf_program_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bpf_program.rs"
    click bindings_mod "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bindings/mod.rs"
    click audit_bind "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bindings/audit.rs"
    click ioctl_bind "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bindings/ioctl.rs"
    click policy_bind "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bindings/policy.rs"
    click state_bind "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bindings/state.rs"
    click bpf_c "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bpf/bpfcontain.bpf.c"
    click include_h "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/bpf/include/*.h"
    click ns_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/ns.rs"
    click log_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/log.rs"
    click utils_rs "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/utils.rs"
    click uprobe_ext "https://github.com/willfindlay/bpfcontain-rs/blob/master/src/uprobe_ext.rs"
    click test_policy "https://github.com/willfindlay/bpfcontain-rs/blob/master/tests/policy_enforcement.rs"
    click test_bpf_wrap "https://github.com/willfindlay/bpfcontain-rs/blob/master/tests/helpers/bpf_wrapper.rs"
    click test_ioctl "https://github.com/willfindlay/bpfcontain-rs/blob/master/tests/ioctl/ioctl.c"
    click ci_yaml "https://github.com/willfindlay/bpfcontain-rs/blob/master/.github/workflows/ci.yml"
    click run_ci "https://github.com/willfindlay/bpfcontain-rs/blob/master/scripts/run-ci.sh"
    click docker_md "https://github.com/willfindlay/bpfcontain-rs/blob/master/DOCKER.md"
    click vagrant "https://github.com/willfindlay/bpfcontain-rs/tree/master/Vagrantfile"
    click examples_readme "https://github.com/willfindlay/bpfcontain-rs/blob/master/examples/README.md"

    %% Styles
    classDef userspace fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef kernel fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef test fill:#FFDAB9,stroke:#333,stroke-width:1px
    classDef docs fill:#E6E6FA,stroke:#333,stroke-width:1px
```
