# threathunters-io/laurel architecture

> Architecture diagram of the GitHub repository threathunters-io/laurel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/threathunters-io/laurel
- Repository: https://github.com/threathunters-io/laurel

## Overview

##### Project type and purpose
- This is a Rust-based event-post-processing plugin/agent for Linux’s auditd service (“LAUREL”).
- Its goal is to consume raw auditd events, enrich them (e.g., process arguments, parent-process info, syscalls), and emit structured JSON logs for downstream security monitoring.

##### File structure
- Top-level Cargo.toml, src/ and src/bin/: a multi-binary Rust crate.
- src/bin/laurel: the main auditd plugin/daemon entry point.
- src/bin/laurel2audit: a companion utility for reverse-conversion or replay.
- src/lib.rs and modules (config.rs, json.rs, procfs.rs, userdb.rs, label_matcher.rs, logger.rs, rotate.rs, quote.rs): the core enrichment pipeline.
- etc/ and contrib/: deployment artifacts (SELinux/AppArmor policies, default config.toml).
- man/, INSTALL.md, performance.md: documentation and usage.
- benches/ and src/testdata/: performance benchmarks and comprehensive test vectors.

##### README for additional insights
- Describes how LAUREL hooks into auditd, enriches EXECVE, PPID, AVC, network events.
- Points to manual pages for config and log format, highlights performance rationale.

##### Detail
- Major modules from src/ (procfs.rs, userdb.rs, etc.) as sub-components of the enrichment pipeline.
- Config sources (etc/laurel/config.toml and Cargo compile-time constants).
- Test and benchmarking artifacts separately (benches/, src/testdata/) to show validation infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kernel and auditd
    Kernel["Kernel Audit Subsystem\n(Netlink)"]:::kernel
    auditd["auditd Daemon"]:::daemon

    %% LAUREL Plugin container
    subgraph "LAUREL Plugin" 
        direction TB
        main["laurel: Rust auditd plugin\n(src/bin/laurel/main.rs)"]:::daemon
        lib["Core Library\n(src/lib.rs)"]:::module
        subgraph "Configuration"
            direction TB
            cfg_code["Config Loader\n(src/config.rs)"]:::config
            cfg_file["Default config.toml\n(etc/laurel/config.toml)"]:::config
        end
        subgraph "Constants Loader"
            const_tpl["Template Constants\n(src/const.rs.in)"]:::module
            const_gen["Generated Constants\n(src/constants.rs)"]:::module
        end
        subgraph "Socket Interface"
            sockaddr_rs["Socket Bindings\n(src/sockaddr.rs)"]:::module
            sockaddr_h["C Headers\n(src/sockaddr.h)"]:::module
        end
        subgraph "Enrichment Pipeline"
            direction TB
            procfs["Process Metadata\n(src/procfs.rs)"]:::module
            coalesce["Parent/Child Coalesce\n(src/coalesce.rs)"]:::module
            label["SELinux/AppArmor Matcher\n(src/label_matcher.rs)"]:::module
            userdb["User DB Lookup\n(src/userdb.rs)"]:::module
            quote["Argument Quoting\n(src/quote.rs)"]:::module
            rotate["Log Rotation\n(src/rotate.rs)"]:::module
        end
        serializer["JSON Serializer\n(src/json.rs)"]:::module
        logger["Logger/Output\n(src/logger.rs)"]:::module
    end

    %% laurel2audit utility
    laurel2audit["laurel2audit Utility\n(src/bin/laurel2audit/main.rs)"]:::daemon

    %% Deployment artifacts & policies
    subgraph "Policies & Deployment"
        direction TB
        audit_plugin_conf["auditd Plugin Conf\n(etc/audit/plugins.d/laurel.conf)"]:::config
        selinux["SELinux Policies\n(contrib/selinux/)"]:::config
        apparmor["AppArmor Profiles\n(etc/apparmor/laurel)"]:::config
    end

    %% Documentation & Test infrastructure
    subgraph "Docs & Testing"
        direction TB
        install["INSTALL.md"]:::external
        perf["performance.md"]:::external
        man_pages["Man Pages\n(man/*.md)"]:::external
        benches["Benchmarks\n(benches/)"]:::external
        testdata["Test Data\n(src/testdata/)"]:::external
    end

    %% Downstream consumers
    subgraph "Downstream Consumers"
        direction TB
        beats["Filebeat/Auditbeat\n(or SIEM)"]:::external
    end

    %% Data flow
    Kernel -->|"netlink"| auditd
    auditd -->|"plugin call / FIFO"| main
    cfg_file --> cfg_code
    cfg_code --> main
    main --> lib
    lib --> const_tpl
    const_tpl --> const_gen
    main --> sockaddr_rs
    main --> sockaddr_h
    main --> procfs
    procfs --> coalesce
    coalesce --> label
    label --> userdb
    userdb --> quote
    quote --> rotate
    rotate --> serializer
    serializer --> logger
    logger -->|"stdout/file"| beats

    %% Optional replay flow
    logger --> laurel2audit
    laurel2audit -->|"reconstruct events"| auditd

    %% Deployment connections
    audit_plugin_conf --> main
    selinux --> main
    apparmor --> main

    %% Docs & Testing connections
    benches -.-> main
    testdata -.-> lib
    install -.-> main
    perf -.-> main
    man_pages -.-> main

    %% Click Events
    click main "https://github.com/threathunters-io/laurel/blob/master/src/bin/laurel/main.rs"
    click laurel2audit "https://github.com/threathunters-io/laurel/blob/master/src/bin/laurel2audit/main.rs"
    click cfg_code "https://github.com/threathunters-io/laurel/blob/master/src/config.rs"
    click cfg_file "https://github.com/threathunters-io/laurel/blob/master/etc/laurel/config.toml"
    click procfs "https://github.com/threathunters-io/laurel/blob/master/src/procfs.rs"
    click coalesce "https://github.com/threathunters-io/laurel/blob/master/src/coalesce.rs"
    click label "https://github.com/threathunters-io/laurel/blob/master/src/label_matcher.rs"
    click userdb "https://github.com/threathunters-io/laurel/blob/master/src/userdb.rs"
    click quote "https://github.com/threathunters-io/laurel/blob/master/src/quote.rs"
    click rotate "https://github.com/threathunters-io/laurel/blob/master/src/rotate.rs"
    click serializer "https://github.com/threathunters-io/laurel/blob/master/src/json.rs"
    click logger "https://github.com/threathunters-io/laurel/blob/master/src/logger.rs"
    click sockaddr_rs "https://github.com/threathunters-io/laurel/blob/master/src/sockaddr.rs"
    click sockaddr_h "https://github.com/threathunters-io/laurel/blob/master/src/sockaddr.h"
    click const_tpl "https://github.com/threathunters-io/laurel/blob/master/src/const.rs.in"
    click const_gen "https://github.com/threathunters-io/laurel/blob/master/src/constants.rs"
    click benches "https://github.com/threathunters-io/laurel/blob/master/benches/coalesce_execve.rs"
    click testdata "https://github.com/threathunters-io/laurel/tree/master/src/testdata/"
    click selinux "https://github.com/threathunters-io/laurel/tree/master/contrib/selinux/"
    click apparmor "https://github.com/threathunters-io/laurel/tree/master/etc/apparmor/laurel"
    click audit_plugin_conf "https://github.com/threathunters-io/laurel/blob/master/etc/audit/plugins.d/laurel.conf"

    %% Styles
    classDef kernel fill:#f88,stroke:#800
    classDef daemon fill:#8df,stroke:#08f
    classDef module fill:#fea,stroke:#fa0
    classDef config fill:#afa,stroke:#0a0
    classDef external fill:#ddd,stroke:#999
    classDef output fill:#ddd,stroke:#999
```
