# chains-project/goleash architecture

> Architecture diagram of the GitHub repository chains-project/goleash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chains-project/goleash
- Repository: https://github.com/chains-project/goleash

## Overview

##### Main Components
- Core Enforcement Engine: At the heart of the project is the main Go application (e.g., eBPFleash/main.go) that acts as the entry point to the runtime enforcement system.
- eBPF Mechanism Integration: The system leverages eBPF to trace and filter syscalls. Components such as the “backend.c” and the syscallfilter package (files like syscallfilter/syscalls.go, constants.go, and utils.go) encapsulate the low-level interaction with the Linux kernel for syscall monitoring.
- Binary and Stack Analysis: There are dedicated modules (eBPFleash/binanalyzer and eBPFleash/stackanalyzer) that analyze binaries and stack traces. These sub-components help determine what capabilities are being invoked and if they comply with the allowed list.
- Test Suites & Examples: The testPkgs directory contains a range of test applications (testCGO, testExec, testPlugin, testReflection) designed to simulate various scenarios. These are crucial for validating enforcement behavior against different types of Go code.
- Build and Configuration Files: Files like Makefiles (present in multiple directories including eBPFleash and testPkgs), go.mod, and workflow configurations under .github provide important build, dependency, and CI/CD setup details.

##### Component Relationships and Data Flows
- Enforcement Logic: Once running, the main engine interacts with auxiliary modules – triggering binary and stack analyses to determine allowed or denied capabilities, referencing the rules maintained via hash generation (as noted in the README).
- Syscall Filtering: The syscallfilter package processes syscalls based on predefined rules, utilizing constants and utility functions to filter or trace them as needed.
- External Interaction: For example, the README details tracking of CoreDNS by loading its binary and using a bpf_loader tool (which, although not directly visible in the file tree, is referenced in documentation). You could include this as an external component that interacts with the enforcement mechanism.

##### Architectural Patterns and Technologies
- Modularity: The project follows a modular design by splitting analysis (binanalyzer, stackanalyzer, syscallfilter) into separate components that are orchestrated by the main Go application.
- Mixed Language Integration: Emphasize the cross-language integration with both Go (for high-level logic) and C (for backend eBPF interactions).
- Runtime Monitoring: The enforcement mechanism is dynamically attached to running programs for syscall monitoring and capability enforcement.
- CI/CD Integration: Capture that the .github workflows (e.g., test.yml) enable continuous testing and validation, showcasing the health of each component.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Runtime Enforcement"
        EN["Main Go (eBPFleash/main.go)"]:::go
        BA["Binary Analyzer (binanalyzer)"]:::go
        SA["Stack Analyzer (stackanalyzer)"]:::go
        SF["Syscall Filter (syscallfilter)"]:::c
        EB["eBPF Backend (backend.c)"]:::c
    end

    subgraph "Testing & Simulation"
        TA["Test Applications (testPkgs)"]:::test
    end

    subgraph "Build and Configuration"
        BF["Build Files (Makefiles)"]:::build
        DM["Dependency Management (go.mod)"]:::build
        CI["CI/CD Config (.github/workflows/test.yml)"]:::build
    end

    EX["External (CoreDNS)"]:::external

    %% Data Flow Arrows
    TA -->|"simulate"| EN
    EN -->|"analyzes"| BA
    EN -->|"analyzes"| SA
    EN -->|"calls"| SF
    SF -->|"traces via"| EB
    EN -->|"monitors syscalls"| EX

    %% Click Events
    click EN "https://github.com/chains-project/goleash/blob/main/eBPFleash/main.go"
    click EB "https://github.com/chains-project/goleash/blob/main/eBPFleash/backend.c"
    click SF "https://github.com/chains-project/goleash/tree/main/eBPFleash/syscallfilter"
    click BA "https://github.com/chains-project/goleash/blob/main/eBPFleash/binanalyzer/binanalyzer.go"
    click SA "https://github.com/chains-project/goleash/blob/main/eBPFleash/stackanalyzer/stackanalyzer.go"
    click TA "https://github.com/chains-project/goleash/tree/main/testPkgs"
    click BF "https://github.com/chains-project/goleash/tree/main/eBPFleash/Makefile"
    click DM "https://github.com/chains-project/goleash/blob/main/go.mod"
    click CI "https://github.com/chains-project/goleash/blob/main/.github/workflows/test.yml"

    %% Styles
    classDef go fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef c fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef test fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef build fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef external fill:#F5DEB3,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5;
```
