⚡ Flux Framework

Modern Linux System Administration & Hardening Toolkit

Enterprise-grade server provisioning written in Rust 🦀

Features • Quick Start • Modules • Documentation • Contributing

🌟 What is Flux?

Flux is a powerful, type-safe system administration framework that automates Linux server configuration, security hardening, and ongoing maintenance. Think of it as Infrastructure-as-Code meets Security-by-Default, all in a single blazingly fast binary.

💎 Why Flux?

🚀 Fast         → Native Rust performance, not shell scripts
🔒 Secure       → Security-first design with sensible defaults
🎯 Focused      → One tool for system provisioning & hardening
📦 Portable     → Single binary, no dependencies
🔧 Flexible     → 11 modules, 5 workflows, fully composable
✅ Reliable     → Idempotent operations, automatic backups

✨ Features

🎛️ System Management ✅ Package updates & security patches ✅ Network configuration (static IP, VLANs) ✅ User & group management ✅ Hostname & FQDN setup ✅ Certificate management	🔐 Security Hardening ✅ SSH hardening & fail2ban ✅ Firewall (UFW/firewalld) ✅ Kernel parameter tuning ✅ Key-based authentication ✅ Security compliance presets
🎨 Developer Experience ✅ ZSH + Oh-My-Zsh setup ✅ Custom MOTD banners ✅ Interactive & scriptable modes ✅ Comprehensive logging ✅ Detailed help system	📊 Monitoring ✅ Netdata integration ✅ System health checks ✅ Resource usage tracking ✅ Service status monitoring ✅ Custom dashboards

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Flux CLI                             │
│                    (Clap + Interactive)                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                             │
┌───────▼────────┐          ┌─────────▼────────┐
│   Workflows    │          │     Modules      │
│                │          │                  │
│ • Essential    │◄─────────┤ • Network        │
│ • Security     │          │ • Hostname       │
│ • Complete     │          │ • Update         │
│ • Development  │          │ • User           │
│ • Monitoring   │          │ • SSH            │
│                │          │ • Firewall       │
│                │          │ • Sysctl         │
│                │          │ • Certs          │
│                │          │ • ZSH            │
│                │          │ • MOTD           │
│                │          │ • Netdata        │
└────────────────┘          └──────────────────┘
         │                           │
         └───────────┬───────────────┘
                     │
         ┌───────────▼────────────┐
         │   Helper Functions     │
         │                        │
         │ • Logging              │
         │ • Validation           │
         │ • System Detection     │
         │ • File Operations      │
         │ • User Input           │
         └────────────────────────┘

🚀 Quick Start

📦 Installation

Option 1: Build from Source (Recommended)

Prerequisites

Before building, ensure you have the required dependencies installed:

Quick Check (Automated):

# Clone the repository
git clone https://github.com/ethanbissbort/flux-framework-rust.git
cd flux-framework-rust

# Check and install all dependencies automatically
sudo ./scripts/check_dependencies.sh --install

Manual Installation:

Ubuntu/Debian

# Install build tools and dependencies
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev pkg-config git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

RHEL/CentOS/Rocky/AlmaLinux/Fedora

# Install build tools and dependencies
sudo dnf install -y gcc gcc-c++ make openssl-devel pkg-config git
# OR for older systems: sudo yum install -y gcc gcc-c++ make openssl-devel pkg-config git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Arch/Manjaro

# Install build tools and dependencies
sudo pacman -S --noconfirm base-devel openssl pkg-config git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Alpine

# Install build tools and dependencies
sudo apk add build-base openssl-dev pkgconfig git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Building Flux

# Clone the repository (if not already done)
git clone https://github.com/ethanbissbort/flux-framework-rust.git
cd flux-framework-rust

# Build in release mode
cargo build --release

# Install system-wide
sudo install -m755 target/release/flux /usr/local/bin/flux

# Verify installation
flux --version

Troubleshooting Build Issues

Error: linker 'cc' not found or error occurred: Command "cc" ... failed

Cause: C compiler/linker not installed
Solution: Install build tools using the automated script:
```
sudo ./scripts/check_dependencies.sh --install
```
Or install manually for your distribution (see Manual Installation above)

Error: could not find native static library 'ssl'

Cause: OpenSSL development headers not installed
Solution:
- Ubuntu/Debian: sudo apt-get install libssl-dev
- RHEL/CentOS/Fedora: sudo dnf install openssl-devel
- Arch: sudo pacman -S openssl
- Alpine: sudo apk add openssl-dev

Error: Rust version ... is too old

Cause: Rust version older than 1.77
Solution: Update Rust with rustup update

Need Help? Run the dependency checker for a detailed report:

./scripts/check_dependencies.sh

Option 2: From Crates.io (Future)

cargo install flux-framework

⚙️ First Run

# 1. Check system compatibility
flux status

# 2. List available modules
flux list modules

# 3. Run essential setup (updates, certs, hardening)
sudo flux apply essential

# 4. Harden security (firewall, SSH, kernel)
sudo flux apply security

🎯 Common Tasks

# Configure SSH hardening
sudo flux module ssh --harden

# Setup a new admin user
sudo flux module user --admin alice --github alice

# Configure firewall with web server preset
sudo flux module firewall --preset web-server

# Install ZSH with Oh-My-Zsh
sudo flux module zsh --theme powerlevel10k

# Setup monitoring
sudo flux module netdata --install

🧩 Modules

Flux provides 11 specialized modules for comprehensive system management:

Module	Status	Description	Key Features
🔄 update	✅	System updates & patches	Security updates, package management, reboot detection
🌐 network	✅	Network configuration	Static IP, VLANs, diagnostics, interface management
🏷️ hostname	✅	Hostname & FQDN setup	System naming, /etc/hosts management
👤 user	✅	User & group management	Admin users, SSH keys, GitHub integration
🔐 ssh	✅	SSH hardening	Port changes, key-only auth, fail2ban
🛡️ firewall	✅	Firewall management	UFW/firewalld, presets, rule management
⚙️ sysctl	✅	Kernel hardening	IPv4/IPv6 security, ASLR, performance tuning
📜 certs	✅	Certificate management	System trust store, CA certificates
💻 zsh	✅	ZSH shell setup	Oh-My-Zsh, themes, plugins, aliases
📋 motd	✅	Dynamic MOTD	System info, resource usage, security status
📊 netdata	✅	Monitoring agent	Real-time metrics, health checks, dashboards

💡 Tip: Run flux module <name> --help for detailed usage information

📖 Full Module Documentation →

🔗 Workflows

Workflows combine multiple modules into cohesive provisioning pipelines:

🌟 Essential

Perfect for: Fresh server setup, base configuration

sudo flux apply essential

Includes: update → certs → sysctl → ssh

What it does:

✅ Updates all packages to latest versions
✅ Installs required certificates
✅ Applies kernel hardening parameters
✅ Configures SSH security

🔒 Security

Perfect for: Hardening existing servers, security compliance

sudo flux apply security

Includes: firewall → ssh → sysctl

What it does:

✅ Configures firewall with deny-all default
✅ SSH hardening (port change, key-only auth)
✅ Kernel security parameters

🎯 Complete

Perfect for: Full server provisioning from scratch

sudo flux apply complete

Includes: All 11 modules in optimized sequence

💻 Development

Perfect for: Developer workstations, coding environments

sudo flux apply development

Includes: user → zsh → certs

📊 Monitoring

Perfect for: Setting up observability stack

sudo flux apply monitoring

Includes: netdata → certs → motd

📖 Full Workflow Guide →

🎨 Usage Examples

🔧 Setup a Web Server

# 1. Essential baseline
sudo flux apply essential

# 2. Create admin user
sudo flux module user --admin deploy --github deploybot

# 3. Configure firewall for web traffic
sudo flux module firewall --preset web-server

# 4. Harden SSH
sudo flux module ssh --port 2222 --disable-passwords

# 5. Setup monitoring
sudo flux module netdata --install

# 6. Custom MOTD
sudo flux module motd --org "MyCompany" --banner flux-large

🗄️ Database Server Hardening

# Run security workflow
sudo flux apply security

# Configure firewall for database
sudo flux module firewall --preset database-server

# Apply strict kernel parameters
sudo flux module sysctl --apply

# Setup monitoring
sudo flux module netdata --install

💻 Developer Workstation Setup

# Run development workflow
sudo flux apply development

# Install ZSH with custom theme
sudo flux module zsh --theme agnoster --plugins "git docker kubectl"

# Setup custom MOTD
sudo flux module motd --org "Dev Team" --banner simple

📖 More Examples →

📚 Documentation

📖 User Guides

Installation Guide - Detailed installation instructions
Module Reference - Complete module documentation
Workflow Guide - Workflow usage and customization
Configuration Reference - Config file documentation
Examples - Real-world usage scenarios

🛠️ Development

Contributing Guide - How to contribute
Architecture - System design and internals
Roadmap - Future plans and features

📝 Reference

claude.md - Complete framework reference for AI assistants

🐧 Supported Distributions

Distribution	Support Status	Notes
🟢 Ubuntu	✅ Full	20.04+, 22.04+, 24.04+
🟢 Debian	✅ Full	11, 12
🟢 RHEL	✅ Full	8, 9
🟢 CentOS	✅ Full	Stream 8, 9
🟢 Rocky Linux	✅ Full	8, 9
🟢 AlmaLinux	✅ Full	8, 9
🟢 Fedora	✅ Full	38, 39, 40
🟡 Alpine	🔜 Planned	v0.5
🟡 Arch	🔜 Planned	v0.5

🤝 Contributing

We ❤️ contributions! Whether it's:

🐛 Bug reports - Found an issue? Open an issue
💡 Feature requests - Have an idea? Start a discussion
📝 Documentation - Improve our docs with a PR
🔧 Code contributions - See our Contributing Guide

Quick Contribution Guide

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/flux-framework-rust.git

# 2. Create a branch
git checkout -b feature/amazing-feature

# 3. Make your changes and test
cargo test
cargo clippy
cargo fmt

# 4. Commit with DCO sign-off
git commit -s -m "Add amazing feature"

# 5. Push and create PR
git push origin feature/amazing-feature

📖 Full Contributing Guide →

🗺️ Roadmap

✅ Version 3.0 (Current)

Complete Rust migration from shell scripts
All 11 modules implemented
5 workflows operational
Comprehensive error handling
Interactive & scriptable modes

🎯 Version 3.1 (Next)

Configuration file support (flux.toml)
Dry-run mode for all operations
Enhanced logging with JSON output
Module dependency resolution
Automatic rollback on failure

🚀 Version 3.2

🌟 Version 4.0

Alpine & Arch Linux support
Container-based testing
Integration with Ansible/Terraform
Cloud provider integrations
Compliance reporting (CIS, NIST)

📖 Detailed Roadmap →

📊 Project Stats

📦 Modules:     11 ✅ | 0 🔜
🔗 Workflows:   5 ✅  | 0 🔜
🧪 Tests:       Coverage in progress
📄 Lines:       ~12,000 lines of Rust
⚡ Binary Size: <5 MB (release)

🙏 Acknowledgements

Flux stands on the shoulders of giants:

🦀 Rust - The language that makes this possible
⚡ Tokio - Async runtime
🎯 Clap - CLI framework
📦 Serde - Serialization framework
🔐 CIS Benchmarks - Security guidelines
🛡️ Mozilla SSH Guidelines - SSH hardening

Special thanks to all contributors!

📜 License

Flux Framework is dual-licensed under your choice of:

Apache License 2.0 (LICENSE-APACHE)
MIT License (LICENSE-MIT)

This means you can use Flux in your projects under either license.

📬 Contact & Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: flux-framework@example.com
🌐 Website: https://flux-framework.io

⚡ Built with ❤️ and Rust 🦀

Making Linux system administration fast, safe, and enjoyable

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
certs		certs
config		config
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AUDIT_REPORT.md		AUDIT_REPORT.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
claude.md		claude.md
flux_rust_structure.txt		flux_rust_structure.txt

License

ethanbissbort/flux-framework-rust

Folders and files

Latest commit

History

Repository files navigation

⚡ Flux Framework

Modern Linux System Administration & Hardening Toolkit

🌟 What is Flux?

💎 Why Flux?

✨ Features

🎛️ System Management

🔐 Security Hardening

🎨 Developer Experience

📊 Monitoring

🏗️ Architecture

🚀 Quick Start

📦 Installation

Prerequisites

Building Flux

Troubleshooting Build Issues

⚙️ First Run

🎯 Common Tasks

🧩 Modules

🔗 Workflows

🌟 Essential

🔒 Security

🎯 Complete

💻 Development

📊 Monitoring

🎨 Usage Examples

📚 Documentation

📖 User Guides

🛠️ Development

📝 Reference

🐧 Supported Distributions

🤝 Contributing

Quick Contribution Guide

🗺️ Roadmap

✅ Version 3.0 (Current)

🎯 Version 3.1 (Next)

🚀 Version 3.2

🌟 Version 4.0

📊 Project Stats

🙏 Acknowledgements

📜 License

📬 Contact & Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages