Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
286 lines (228 loc) · 13.6 KB

CONTRIBUTING.md

File metadata and controls

286 lines (228 loc) · 13.6 KB
Raw

Contributing to SentinelML: Systems & Security Engineering Guide

Welcome and thank you for your interest in contributing to SentinelML! The official tracking repository for our project is located at github.com/Jean-Regis-M/SentinelML.

SentinelML is a near-zero overhead, real-time runtime security platform purpose-built for massive AI/ML training and inference workloads. It combines highly optimized Linux Kernel eBPF probes with an ultra-responsive, safe Rust userspace daemon, and an enterprise-grade React dashboard. By intercepting kernel-level events (syscalls, file operations, hardware GPU ioctl interfaces), SentinelML stops adversarial exfiltration, illegal model tampering, and cryptomining immediately.

Because SentinelML runs within critical system environments (kernel space and production Kubernetes nodes), we maintain high standards of code correctness, memory safety, validation, and performance optimization. This guide outlines how to configure your system, develop under these constraints, and submit high-quality contributions.

Table of Contents

  1. Developer Environment Setup (Libbpf, Rust, and k8s Testing)
  2. eBPF Core Coding Standards (C Bytecode & Verifier Constraints)
  3. Userspace Telemetry Daemon Standards (Rust Safety & Style)
  4. Enterprise Operator Dashboard Standards (React + TypeScript)
  5. Testing Guidelines (Unit, Integration, and eBPF Tracing Validation)
  6. Pull Request (PR) Submission Workflow
  7. Communication Channels & Security Disclosures
  8. Code of Conduct

1. Developer Environment Setup (Libbpf, Rust, and k8s Testing)

To compile kernel-level subsystems and communicate with userspace components, configure your workstation with Linux kernel build tools and container runtimes.

Prerequisites (Target Host Node)

  • Operating System: Modern Linux distribution (Ubuntu 22.04 LTS, Debian 12, or Fedora 39+) with a v5.8+ kernel (v5.15+ strongly recommended for complete BPF RingBuffer and CO-RE stability).
  • BTF Support: Verify that your kernel config has BPF Type Format (BTF) debugging symbols enabled: 
    zgrep CONFIG_DEBUG_INFO_BTF /proc/config.tar.gz || grep CONFIG_DEBUG_INFO_BTF /boot/config-$(uname -r)

Toolchain Dependencies

Ubuntu / Debian Systems

sudo apt-get update && sudo apt-get install -y \
    build-essential \
    clang \
    llvm \
    libbpf-dev \
    linux-headers-$(uname -r) \
    pkg-config \
    libelf-dev \
    gcc-multilib \
    nodejs \
    npm

Fedora / RHEL Systems

sudo dnf groupinstall -y "Development Tools" "Development Libraries"
sudo dnf install -y \
    clang \
    llvm \
    libbpf-devel \
    kernel-devel \
    elfutils-libelf-devel \
    pkgconf-pkg-config \
    nodejs \
    npm

Rust Toolchain Setup

SentinelML utilizes advanced user-space parsers built in Rust. Install Rustup and configure the latest stable toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable
rustup component add clippy rustfmt

Local Kubernetes Cluster Testing

We support local Kubernetes simulation using KinD (Kubernetes-in-Docker) or Minikube hosting mounts of the host /sys/kernel/debug interface:

  1. Deploy KinD with Local Cluster Nodes: Ensure the control-plane and worker nodes can read host BPF paths:

    # kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraMounts:
  - hostPath: /sys/kernel/debug
    containerPath: /sys/kernel/debug
  - hostPath: /lib/modules
    containerPath: /lib/modules
    readOnly: true
    kind create cluster --config kind-config.yaml

  2. Mock Container Execution and DaemonSet Telemetry: Deploy the local development build of the Helm chart with debug logging enabled:

    cd sentinelml/charts
helm install sentinelml ./sentinelml \
  --set daemon.debug=true \
  --set daemon.kernelPathMount=true \
  --namespace sentinel-system \
  --create-namespace

2. eBPF Core Coding Standards (C Bytecode & Verifier Constraints)

To preserve kernel safety and prevent host crashes, all kernel-side probe targets (kprobes, fentries, tracepoints) must satisfy the Linux Kernel Verifier constraint policies.

Memory Safety & Reading Pointers

  • Always read safely: Direct dereferences of user or kernel pointer fields in eBPF will instantly trigger verification crashes. You MUST wrap pointer accesses with standard helpers: 
    // ❌ INCORRECT: Direct access to payload address
char *user_path = task->mm->arg_start;

// ✅ CORRECT: Safe retrieval using probe helper wrappers
char buffer[128];
long err = bpf_probe_read_user_str(&buffer, sizeof(buffer), (void *)task->mm->arg_start);
if (err < 0) {
    return 0; // Graceful rejection
}
  • Compile-Once Run-Everywhere (CO-RE): Always preserve struct layout relocations by accessing nested variables with BPF relative mapping helpers: 
    u32 flags = BPF_CORE_READ(inner_struct, field_name);

Structural Alignment & Sizing

  • Ensure telemetry event structures match on 8-byte boundaries to prevent garbage memory layout mapping across 32-bit and 64-bit systems. Wrap communication events in: 
    #define TASK_COMM_LEN 16

struct event_t {
    __u64 timestamp;
    __u32 pid;
    __u32 uid;
    char comm[TASK_COMM_LEN];
} __attribute__((packed));

Loops and Execution Size

  • Verifier Complexity Margin: The runtime instruction limit for a BPF bytecode packet is limited. In older kernels, dynamic loops are completely forbidden.
  • Static Loops: All index iterations must use #pragma unroll or static compiler directives to keep bytecode paths deterministic.

3. Userspace Telemetry Daemon Standards (Rust Safety & Style)

The userspace daemon is responsible for high-speed analysis and event distribution. It must remain crash-free and run with maximum performance.

Idiomatic Formatting, Clippy, and Lifetimes

  • Pure Idioms: Run formatting matches prior to committing: 
    cargo fmt --all --check
  • Prevent Allocation Thrashing: Avoid nested string cloning or allocating excessive memory chunks inside hot paths (e.g., inside the event subscriber loop). Use borrows/refs (&str and slices) and stack variables wherever possible.
  • Unsafe Blocks Restrictions: The use of raw pointers (unsafe {}) is strictly restricted to calling the dynamic FFI borders of Libbpf or parsing raw ring-buffer traces. When unsafe blocks are necessary, you must comment a corresponding safety rationale: 
    // Safety: Event structures mapped onto RingBuffer arrays have pre-computed 
// boundary alignments packed matching the kernel-side bytecode exactly.
let parsed_evt = unsafe { &*(raw_ptr as *const EventTrace) };

Critical Error Mitigation Principles

  • No Uncontrolled Panics: Never call unwrap(), expect(), or panic!() inside loop pipelines or daemon interfaces. Instead, implement correct Result/Option chaining with appropriate error logs: 
    // ❌ INCORRECT: Standard crash potential
let connection = parse_host_channel().unwrap();

// ✅ CORRECT: Logging propagation
let connection = match parse_host_channel() {
    Ok(channel) => channel,
    Err(e) => {
        log::error!("Failed parsing host telemetry channel: {}", e);
        return Err(DaemonError::ChannelFailure(e));
    }
};

4. Enterprise Operator Dashboard Standards (React + TypeScript)

Our visual interfaces are high-density, accessible, and high-performance. We prioritize fluid rendering, clear typography (Inter + JetBrains Mono), and elegant dark themes.

  • Responsive layouts: Utilize Tailwind responsive design flags to support dynamic viewport sizing: 
    <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4">
  • Functional States: Components such as ThreatHeatmap must support live modular filters:
    • Live Text Filters: Fast substring searches using state patterns mapped directly over row iterators.
    • Native Selector Filter: Include interactive <select> dropdown states to isolate distinct namespaces from active alerts dataset records.
  • Icon Library: Leverage and share icons imported directly from lucide-react. Do not write raw SVG curves inside TSX elements.
  • Server Safety Isolation: Ensure all interactions with API structures (e.g., Gemini Analyzer, simulator configs) are mediated through Express backend route controllers inside server.ts. Never expose secret keys to the browser client side.

5. Testing Guidelines (Unit, Integration, and eBPF Tracing Validation)

SentinelML maintains comprehensive test coverages across each layer of the systems stack.

Userspace Unit & Integration Tests

  • Rust Daemon Tests: Run unit tests to check memory limits, format parsers, and connection brokers: 
    cargo test --all --verbose
  • Dashboard Compilation Tests: Verify standard code builds compile flawlessly: 
    npm run lint
npm run build

Dedicated Kernel Bytecode Tests

Writing integration tests for kernel event intercepts requires spawning testing processes and validating that tracing state maps register actions successfully:

#[tokio::test]
async fn test_ebpf_safetensors_file_isolation_block() {
    // 1. Initialize loaded probes
    let mut ring_buffer = init_test_bpf_probes().await.unwrap();

    // 2. Spawn a simulated threat process attempting to access dummy target model paths
    let dummy_file = std::fs::File::open("mock_model.safetensors");

    // 3. Inspect buffer registers that a CRITICAL audit intercept event was registered
    let event = ring_buffer.read_event_timeout(Duration::from_millis(1500)).await;
    assert_eq!(event.category, "MODEL_THEFT_ATTEMPT");
    assert!(event.blocked_status);
}

6. Pull Request (PR) Submission Workflow

We use a structured, peer-reviewed branch strategy to evaluate codebase patches safely.

 [ local branch: feat/* ] ──► [ push origin ] ──► [ GitHub Draft PR ]
                                                          │
                                                          ▼
 [ branch merge squash  ] ◄── [ approve approvals ] ◄── [ local repairs ]

PR Step-by-Step Procedure:

  1. Isolate Feature Branch: Sync your local main branch with the upstream origin repository and spin off a localized branch: 
    git checkout -b feat/kernel-gpu-telemetry
  2. Implement Changes: Ensure you write tests, run lints (cargo fmt, npm run lint), and verify builds before staging.
  3. Convention Struct Commits: Write descriptive, clean commit signatures:
    • feat(ebpf): track illegal file locks on model storage formats
    • fix(ui): mend layout flickering during active tooltips transitions
    • test(daemon): write complete safety checks for ring buffer parsing boundaries
  4. Initiate Draft PR: Push your branch to your Fork on GitHub and initiate a Pull Request to Jean-Regis-M/SentinelML.
  5. Address Review Comments: Address peer system feedback and merge conflict fixes openly and constructively.
  6. Merge Approvals: Once successfully evaluated and approved by two core maintainers, your changes will be squashed and integrated!

7. Community & Communication Channels

Coordinate design concepts, structural setups, and security discussions with other developers using authorized avenues:

  • RFC Submissions: For wide architectural additions, create a ticket directly at Jean-Regis-M/SentinelML Issues with the tag rfc-proposal and fill out our design document blueprint template.
  • Operational & Chat channels: Join our active communities on the SentinelML Discord Server or participate directly in GitHub Discussions.
  • Coordinated Vulnerability Disclosure (CVD):
    • DO NOT raise public or uncovered GitHub issues for vulnerability disclosures.
    • If you spot kernel-space escalations, memory leaks, or cluster isolation failures, report them privately via PGP encrypted systems to: security@sentinelml.io.

8. Code of Conduct

All contributors and project maintainers are bound to behave with integrity, respect, and professional courtesy, abiding fully by the Contributor Covenant Code of Conduct.

Summary Pledge

We pledge to make participation in our project and our community a harassment-free and supportive experience for everyone. We welcome developers of all levels of experience, background, and perspective. We do not tolerate offensive statements, hostile communications, trolling, personal attacks, or exclusionary behavior.

Violations or inappropriate conduct should be escalated for assessment directly to: conduct@sentinelml.io.

Thank you for dedicating your time, insight, and engineering craftsmanship to making machine learning operations secure for everyone everywhere with SentinelML!