Skip to content
Snigdha OSDecentralized

System Architecture Overview

Layer-by-layer architectural analysis from hardware firmware to user desktop.

15 min readUpdated: 2026-11-12

Snigdha OS Decentralized: Architecture & System Design

Current Status: Released (Official ISO Published — v2026.11.13-rc1)
Target Architecture: x86_64
Primary Engine: ArchISO (mkarchiso)
Base Lineage: Arch Linux Baseline Profile (archiso 92-1)

1. Architectural Overview

Snigdha OS Decentralized is designed as a standalone, privacy-oriented, amnesic live operating system. Rather than creating a superficial desktop re-spin of Arch Linux, Snigdha OS Decentralized establishes an independent distribution build tree starting from the minimal ArchISO baseline profile.

In Phase 0, the architecture is intentionally lean, providing only the foundational plumbing required to build, test, and boot a branded minimal image.

flowchart TD
    subgraph Repo["Repository Root"]
        A["profile/profiledef.sh\n(Distribution Identity)"]
        B["profile/packages.x86_64\n(Base Package Manifest)"]
        C["profile/pacman.conf\n(Package Repositories)"]
        D["profile/airootfs/\n(Filesystem Overlay)"]
        E["profile/grub/\n(UEFI Configuration)"]
        F["profile/syslinux/\n(BIOS Configuration)"]
    end

    subgraph BuildEngine["mkarchiso Engine"]
        G["pacstrap -N (airootfs)\nUser Namespaces"]
        H["mkfs.erofs\n(Compressed Rootfs)"]
        I["mkinitcpio-archiso\n(Live Boot Initramfs)"]
        J["grub-mkstandalone\n(UEFI Bootloader)"]
        K["xorriso\n(Hybrid ISO 9660 + El Torito)"]
    end

    subgraph Outputs["build/out/"]
        L["snigdha-decentralized-YYYY.MM.DD-x86_64.iso"]
        M[".iso.sha256 Checksum"]
        N[".meta.txt Metadata Manifest"]
    end

    Repo --> BuildEngine
    BuildEngine --> Outputs

2. ArchISO Profile Architecture

The project's build profile lives inside profile/ and adheres strictly to the ArchISO profile specification:

2.1 Profile Directory Anatomy

  • profile/profiledef.sh: The central configuration entrypoint. Defines image metadata (iso_name, iso_label, iso_publisher, iso_application, iso_version), target installation directory (install_dir="snigdha"), boot modes (bios.syslinux, uefi.grub), rootfs image compression format (erofs), and file permission maps.
  • profile/packages.x86_64: Declarative list of Arch Linux packages to install into the live squashfs/erofs root. Snigdha OS uses exclusively the linux-hardened kernel (replacing stock linux), mkinitcpio-archiso, hypervisor integration agents, and the i3wm desktop stack.
  • profile/pacman.conf: The pacman configuration file used during pacstrap execution. Controls repository sources (core, extra) and signature verification settings.
  • profile/airootfs/: Overlay filesystem copied directly onto the live system root before image sealing. Contains systemd network units, service enable symlinks, and locale configurations.
  • profile/efiboot/: Contains systemd-boot loader configuration (loader.conf and 01-archiso-linux.conf) used when UEFI systemd-boot is configured.
  • profile/grub/: Contains grub.cfg, loopback.cfg, and the themes/dedsec/ graphical bootloader theme utilized by GRUB for UEFI optical boot and loopback ISO mounting (e.g., Ventoy or GRUB loopback).
  • profile/grub/themes/dedsec/: DedSec GRUB2 theme (https://github.com/VandalByte/dedsec-grub2-theme) configured for 1080p high-resolution boot with Hack & Norwester fonts, dark hacker aesthetic wallpaper, custom icons suite, and graphical progress bar.
  • profile/syslinux/: Contains syslinux and isolinux configurations (syslinux.cfg, syslinux-linux.cfg) for legacy BIOS booting.

3. How Snigdha OS Customizes the Baseline

Upstream ArchISO baseline is customized without altering its functional or structural stability:

  1. Namespace Isolation via install_dir="snigdha":

    • Upstream stores boot artifacts and rootfs in /arch/ on the ISO.
    • Snigdha OS Decentralized routes all kernel binaries, initramfs images, rootfs images, version files, and package manifests into /snigdha/boot/x86_64/ and /snigdha/x86_64/.
    • Bootloader parameters (archisobasedir=%INSTALL_DIR%) automatically resolve to snigdha.

  2. Standard Volume Identifier (iso_label="SNIGDHA_DEC" ):

    • The volume label is constrained to 11 characters to ensure full backward compatibility with both FAT32 EFI system partitions and ISO 9660 specifications.

  3. Bootloader Identity Harmonization & DedSec GRUB Theme:

    • Menus in GRUB, systemd-boot, and Syslinux identify the operating system as Snigdha OS Decentralized (%ARCH%, [Platform]).
    • Dynamic template variables (%ARCH%, %INSTALL_DIR%, %ARCHISO_UUID%) are maintained so mkarchiso can perform runtime variable substitution during ISO assembly.
    • GRUB UEFI bootloader loads the DedSec theme (/boot/grub/themes/dedsec/theme.txt) using gfxterm, multi-resolution fallbacks (1920x1080,1366x768,1024x768,auto), Hack & Norwester PFF2 fonts, and icon mapping for Snigdha, Arch, Memtest, and UEFI utilities.

4. Image Construction Workflow

The build workflow is driven by scripts/build-iso.sh (or make build):

  1. Pre-flight Check (scripts/check-host.sh):
    • Validates kernel capabilities (unprivileged user namespaces).
    • Verifies presence of mkarchiso, pacman, pacstrap, xorriso, mksquashfs, mkfs.erofs, and other utilities.
  2. Profile Sourcing & Validation:
    • Sourced from profile/profiledef.sh. Ensures no required variables or directories are missing.
  3. Root Filesystem Creation (airootfs):
    • pacstrap -N instantiates an isolated root filesystem using user namespaces, installing declared packages into build/work/x86_64/airootfs.
    • The project profile/airootfs/ directory is copied over the target rootfs, applying custom file permissions (/etc/shadow mode 400).
  4. Initramfs Generation:
    • mkinitcpio is invoked inside the target chroot using the mkinitcpio-archiso hook hooks (archiso, archiso_loop_mnt).
  5. Root Filesystem Sealing:
    • The airootfs is compressed into an EROFS filesystem with LZMA compression (-zlzma,109 -E ztailpacking) stored at build/work/iso/snigdha/x86_64/airootfs.erofs.
  6. Bootloader Setup:
    • GRUB standalone binaries (BOOTX64.EFI) are generated with embedded discovery scripts.
    • Syslinux BIOS files and MBR boot sectors are embedded.
  7. Hybrid ISO Assembly:
    • xorriso packages the directory structure into a hybrid ISO 9660 image supporting both El Torito BIOS boot and UEFI booting via an embedded FAT EFI partition.
  8. Artifact Manifestation & Verification:
    • Checksum (.sha256) and build metadata (.meta.txt) are generated in build/out/.

5. Desktop Environment & Visual System (Phase 1 Integration)

In Phase 1, Snigdha OS Decentralized transitions from a minimal command-line baseline to a fully configured graphical tiling desktop:

  • Window Manager (i3-wm): Configured with native gaps (inner 8px, outer 4px), custom border styling, and complete keyboard navigation matching the Snigdha Obsidian design tokens.
  • Compositor (picom): Hardware-accelerated compositor providing subtle window drop-shadows, 8px rounded corners, dual-kawase background blur, and smooth fading.
  • Status Bar (polybar): Custom status bar displaying workspace indicators, active window titles, CPU/RAM/Audio metrics, generic network status (no IP/MAC leaks), and a prominent security status banner.
  • Launcher & Menus (rofi): Keyboard-driven application launcher, window switcher, and power management menu (snigdha-powermenu).
  • Notifications (dunst): Color-coded urgency levels (Obsidian dark / luminous cyan / critical red) with icon support.
  • Terminal Emulator (kitty): GPU-accelerated terminal pre-configured with JetBrains Mono Nerd Font and Snigdha Obsidian color palette.
  • File Manager (thunar): Lightweight graphical file manager configured without automatic removable-media mounting.
  • GTK Theme (Snigdha-Obsidian): Custom GTK 3 & GTK 4 stylesheets adhering to the WCAG AA compliant Obsidian color palette.
  • Icon Suite (Snigdha-Decentralized): Custom SVG overlay icon theme with inheritance fallback to Papirus-Dark, Adwaita, and hicolor.
  • Original Wallpapers: Three rendered 1920x1080 wallpapers (snigdha-obsidian-mesh, snigdha-decentralized-circuit, snigdha-minimal-dark).
  • Live Session Autostart: Controlled agetty autologin on tty1 for the unprivileged snigdha user, seamlessly transitioning to X11 via .bash_profile and .xinitrc.

6. Snigdha NetGuard Subsystem (Phase 3 Integration)

In Phase 3, Snigdha OS Decentralized integrates Snigdha NetGuard, guaranteeing kernel-level network enforcement and anonymous routing:

  • Kernel Firewall (table inet snigdha): Dual-stack nftables ruleset enforcing default drop policies for input and output chains. Transparently redirects all external application TCP to Tor TransPort (127.0.0.1:9040 / [::1]:9040) and UDP DNS to Tor DNSPort (127.0.0.1:5353 / [::1]:5353).
  • UDP & QUIC Leak Elimination: Drops all unauthorized outbound UDP packets, preventing QUIC bypass, NTP leaks, and STUN deanonymization.
  • Controlled Tor Daemon (tor 0.4.9.16-1): Client-only daemon operating in RAM-backed volatile storage (/run/tor). Boots in network-disabled state (DisableNetwork 1), requiring explicit user consent.
  • DNS Bootstrap Isolation: Restricts DHCP DNS server access strictly to Tor UID 43 via dynamic NetworkManager dispatcher allowlists.
  • NetGuard Control Daemon (snigdha-netguardd): Manages connection lifecycle states, volatile bridge configurations, and authenticated local IPC over Unix domain sockets and D-Bus.
  • Desktop Integration: Dynamic Polybar NetGuard module, Rofi control menu ($mod+Shift+n), Dunst notifications, and comprehensive diagnostic CLI (snigdha-netguard diagnose).

7. Snigdha Persistence Subsystem (Phase 4 Integration)

In Phase 4, Snigdha OS Decentralized integrates Snigdha Persistence, providing encrypted, selectively activated persistent storage compatible with the amnesic operating system baseline:

  • LUKS2 & Argon2id Cryptographic Layer: Employs LUKS2 with aes-xts-plain64 512-bit encryption and memory-hard Argon2id PBKDF (bounded to 1 GiB memory cost to ensure universal portability from 4GB laptops to high-memory workstations).
  • Physical Ancestry Device Discovery: Resolves parent block devices from /proc/mounts and sysfs to verify that persistence partitions reside exclusively on the verified USB boot medium. All internal SATA/NVMe disks, active swap partitions, and volatile root mounts are rejected unconditionally.
  • Dual Confirmation Safeguards: Destruction of partition contents during initial provisioning requires two explicit user confirmations, including typing the exact block device string.
  • Versioned Metadata & Allowlisted Feature Engine: Rejects blanket persistence of home or system directories. Encapsulates persistence in allowlisted adapters (persistent-folder -> ~/Persistent, gnupg -> ~/.gnupg, ssh -> ~/.ssh). Sockets and runtime agent states remain volatile in tmpfs.
  • Safe Late-Shutdown Sequencing: snigdha-persistence-teardown.service executes strictly before snigdha-amnesia-shutdown.service and initramfs root overlay pivot, unmounting bind-mounts, flushing filesystem buffers, and closing dm-crypt mappings.
  • Boot-Medium Watchdog Coordination: Integrates with snigdha-media-watchdog to halt writes and trigger immediate emergency shutdown if the USB medium is physically disconnected.
  • Desktop Integration: Rofi persistence control menu ($mod+Shift+p), Polybar persistence module (snigdha-polybar-persistence), and desktop notifications.

8. Snigdha Isolation Subsystem (Phase 5 Integration)

In Phase 5, Snigdha OS Decentralized integrates Snigdha Isolation, establishing multi-layer application confinement, Mandatory Access Control (MAC), and system service hardening:

  • AppArmor MAC Kernel Foundation: Enabled at boot via lsm=landlock,lockdown,yama,integrity,apparmor,bpf. Features 12 dedicated profiles enforcing strict restrictions on filesystem access, capabilities, and Unix sockets across daemons and desktop applications.
  • Bubblewrap Sandbox Runtime (snigdha-sandbox): Spawns applications inside hermetic environments utilizing unprivileged user, mount, PID, IPC, and UTS namespaces. Mounts /usr read-only, masks sensitive credentials (/etc/shadow, /etc/tor, /etc/nftables.d), and allocates ephemeral home storage under ~/.var/app/{id}.
  • Network Enforcement Integration:
    • host-enforced: Shares host network namespace so all application traffic is transparently intercepted by NetGuard nftables rules and routed through Tor.
    • offline: Isolates the application inside an unshared network namespace (--unshare-net) with loopback only.
  • Persistence Boundary Protection: When persistence is locked, ~/Persistent is masked with an empty tmpfs and block devices are excluded. When unlocked, only authorized feature folders are bound into permitted sandboxes.
  • D-Bus Proxy Filtering (xdg-dbus-proxy): Creates an ephemeral proxy socket filtering method calls and bus ownership, denying privileged access to NetGuard, Persistence, and systemd APIs.
  • Seccomp-BPF System Call Filtering: Native snigdha-seccomp-compiler attaches BPF bytecode blocking dangerous kernel operations (ptrace, module loading, reboot, keyrings) and offline sockets.
  • System Service Hardening: 9 systemd drop-ins enforce ProtectSystem=strict, PrivateTmp=yes, RestrictSUIDSGID=yes, and capability whitelisting across all distribution daemons.
  • Desktop Integration: Rofi isolation menu ($mod+Shift+s / $mod+i), Polybar isolation status indicator (snigdha-polybar-isolation), and diagnostic audit CLI (snigdha-isolation).

9. Snigdha Privacy Suite Subsystem (Phase 6 Integration)

In Phase 6, Snigdha OS Decentralized integrates the Snigdha Privacy Suite, providing an integrated collection of privacy-focused applications with security policies, controlled data access, and seamless desktop integration:

  • Tor Browser & Stream Isolation: Configured via TOR_SKIP_LAUNCH=1 and TOR_SOCKS_PORT=9050 with NetGuard's IsolateSOCKSAuth, preventing Tor-over-Tor nested routing loops and eliminating clearnet fallback. Browser profile and binaries reside exclusively in volatile RAM tmpfs.
  • OnionShare & Tor Control Broker (snigdha-tor-broker): Mediates Tor ControlSocket access on 127.0.0.1:9051, whitelisting ephemeral v3 onion service creation (ADD_ONION, DEL_ONION, NEWNYM) while rejecting administrative reconfiguration commands with 510 Command filtered. Cleans up ephemeral onion services automatically on client disconnect.
  • Thunderbird Email Security & OpenPGP Separation: Hardened with remote image/tracker blocking, update freezing, and NetGuard transparent torification. Strictly separates internal OpenPGP (RNP) key store from system GnuPG. Optional thunderbird-profile persistence adapter allows explicit opt-in encrypted retention.
  • KeePassXC Password Vault: Runs strictly offline (network: "offline" with Bubblewrap network unsharing and AppArmor network denial). Uses Argon2id KDF, 30-second clipboard clearing, and selective persistence in ~/Persistent/Passwords/.
  • MAT2 & Metadata Cleaner: Strips document/media metadata strictly offline, enforcing a non-destructive invariant where source files remain bit-for-bit untouched and separate <filename>.cleaned.<ext> copies are generated.
  • GnuPG Cryptographic Key Management: Ed25519 ECC key generation, automatic revocation certificate creation (openpgp-revocs.d/), and memory-volatile agent lifecycle.
  • Desktop Integration: Rofi privacy launcher ($mod+m / $mod+Shift+m), Polybar privacy status indicator (snigdha-polybar-privacy), Thunar context actions (mat2 -- %F), and Dunst notifications.

10. Snigdha Security Center Subsystem (Phase 7 Integration)

In Phase 7, Snigdha OS Decentralized integrates Snigdha Security Center (snigdha-security-center), a unified, native graphical and command-line management interface engineered in Rust and GTK4:

  • Unprivileged Native GUI: Operates strictly within user-space without root privileges, leveraging gtk4-rs and custom Everblush CSS.
  • D-Bus System Bus IPC: Asynchronous, non-blocking communication via zbus across five specialized daemon interfaces (Amnesia1, NetGuard1, Persistence1, Isolation1, PrivacySuite1).
  • Polkit Elevation: Privilege escalation occurs strictly at daemon API boundaries with fine-grained PolicyKit rules and session agent mediation (polkit-gnome).
  • Interactive Posture Dashboard: Real-time state aggregation, conservative security status calculations, active alert banners, and sanitized diagnostic reports (--diagnose / --json).
  • Desktop Integration: Bound to $mod+Shift+s in i3wm, Polybar module [module/security], and application menu.

See docs/SECURITY-CENTER-ARCHITECTURE.md and docs/SECURITY-CENTER-USER-GUIDE.md.

11. Snigdha Trust Subsystem (Phase 8 Integration)

In Phase 8, Snigdha OS Decentralized integrates Snigdha Trust, establishing an unbroken cryptographic chain of trust from UEFI firmware through the running operating system, and from source code through the published release artifacts:

  • UEFI Secure Boot & Unified Kernel Image (UKI):
    • Consolidates kernel (vmlinuz-linux-hardened), initramfs (initramfs-linux-hardened.img), kernel command line, OS release metadata (/etc/os-release), and SBAT policy (sbat.csv) into a single PE/COFF executable using systemd-ukify.
    • Embedded command line securely anchors immutable boot parameters and the dm-verity root hash and salt, preventing tampering via bootloader configuration files.
    • Signed via sbsign with an isolated X.509 RSA-4096 Secure Boot key (db.key / db.crt).
    • Safe user-directed enrollment tooling (snigdha-enroll-keys and snigdha-boot-status) supporting both Microsoft hybrid dual-boot retention and custom-only enrollment, strictly prohibiting silent motherboard NVRAM mutations.
  • dm-verity Immutable Root Filesystem:
    • Protects the live lower filesystem (airootfs.erofs) using a cryptographic Merkle hash tree (airootfs.verity) formatted with SHA-256, 4096-byte blocks, and a unique cryptographic salt.
    • Early-boot initcpio hook (snigdha_trust_verity) parses the authenticated root hash from /proc/cmdline, activates dm-verity via veritysetup open, and binds /dev/mapper/airootfs_verity as the read-only lower layer of the Amnesia OverlayFS.
    • Fail-closed enforcement: any runtime byte corruption or block tampering triggers kernel I/O EIO errors, halts the boot sequence, and records verity_status: FAILED to /run/snigdha/boot-integrity.json.
  • Isolated Cryptographic Key Hierarchy:
    • Maintains strict operational separation between Secure Boot keys (PK, KEK, db), ISO release signing keys (OpenPGP 4096-bit), pacman package signing keys (OpenPGP 4096-bit), and SLSA build provenance identity.
    • Private keys are excluded from git version control, protected with 0600/0700 permissions, and supported by documented rotation and revocation workflows.
  • Software Supply Chain Integrity & Release Transparency:
    • Machine-Readable SBOM (SBOM.spdx.json): Full SPDX 2.3 JSON specification documenting all 454 installed packages, suppliers, licenses, and file relationships.
    • SLSA v1.0 Build Provenance (provenance.intoto.jsonl): in-toto attestation recording builder identity, source git commit, toolchain versions, build arguments, and subject artifact digests.
    • Release Manifest (release-manifest.json): Versioned JSON manifest cataloging SHA-256 and BLAKE2b digests for all release files, boot integrity parameters, and signing fingerprints.
    • Detached OpenPGP Release Signatures: Cryptographically isolates release artifacts (.iso.sig, SHA256SUMS.sig, BLAKE2SUMS.sig, release-manifest.json.sig, SBOM.spdx.json.sig, provenance.intoto.jsonl.sig).
  • Independent Verification Utility (snigdha-verify):
    • Standalone, zero-dependency Python 3 verification utility for users and independent auditors, supporting iso, signature, checksum, manifest, sbom, provenance, uki, verity, and full release directory validation against pinned public keys.
  • Reproducible Builds Verification Harness:
    • Automated build harness (test-reproducibility.sh) conducting bit-for-bit rebuild comparisons under pinned SOURCE_DATE_EPOCH, UTC, and C.UTF-8 locales, utilizing diffoscope for granular inspection and providing truthful classification (PARTIALLY_REPRODUCIBLE due to Authenticode PKCS#7 signing timestamps).
  • Native Security Center Integration:
    • Adds a dedicated Boot Integrity card to Snigdha Security Center (Rust + GTK4), exposing firmware mode, Secure Boot state, kernel lockdown level, module signature enforcement, and dm-verity status.

See docs/SECURE-BOOT-ARCHITECTURE.md, docs/VERIFIED-ROOT-FILESYSTEM.md, docs/SIGNING-KEY-MANAGEMENT.md, docs/RELEASE-VERIFICATION.md, and docs/SOFTWARE-SUPPLY-CHAIN.md.

12. Phase 9: Penetration Center & Security Tooling Ecosystem

Phase 9 integrates Snigdha Penetration Center (snigdha-penetration-center, snigdha-penetration), establishing an original, native security research environment that reconciles the vast tooling available across Arch Linux, BlackArch, and Chaotic-AUR with the strict stability, supply-chain, and anti-forensic privacy invariants of Snigdha OS:

  • Native Multi-Tier Application:
    • Written in Rust using GTK4 (gtk4-rs) and styled with the Snigdha Obsidian Everblush design tokens.
    • Features 10 distinct management pages: Overview, Discover, Categories, Collections, Installed, Repositories, Profiles, Transactions, Diagnostics, and About.
    • Accompanied by a standalone snigdha-penetration CLI supporting both human-readable tabular output and structured --json serialization.
  • Conservative Multi-Repository Management:
    • Integrates Arch Linux (core, extra), BlackArch, and Chaotic-AUR.
    • Non-negotiable invariant: BlackArch and Chaotic-AUR are disabled by default in standard installations and live ISO media.
    • Pinned OpenPGP signing key allowlists prevent rogue key enrollment. Upstream expired signing keys (Chaotic-AUR primary signer) are audited, classified, and blocked.
  • Safe Transaction Engine & Partial Upgrade Elimination:
    • Enforces SigLevel = Required DatabaseOptional unconditionally.
    • Prevents partial Arch upgrades by automatically promoting package transactions to pacman -Syu --needed <repo>/<pkg>.
    • Rejects dangerous wildcard file overwrites (--overwrite='*').
    • Previews complete package transactions and download sizes before execution.
  • Curated Tool Catalog & Authoritative Domains:
    • Organizes tools into 15 cybersecurity domains and 10 pre-curated collections.
    • Backed by versioned TOML metadata and strict JSON schemas, with binary-embedded fallback resilience.
    • Real-time unprivileged synchronization with the ALPM local database (/var/lib/pacman/local/).
  • Encrypted Persistence Integration (Phase 4):
    • Registers the penetration-tools persistence feature adapter.
    • Stores lightweight tool selection profiles on the encrypted LUKS2 volume (/var/lib/snigdha/penetration/profiles).
    • Maintains the volatile Amnesia invariant: tools installed in RAM disappear upon reboot; profile restores require explicit user confirmation.
  • Unified Security Center Telemetry (Component P):
    • Dedicates a Security Tooling navigation tab and page in snigdha-security-center.
    • Exposes repository states, installed tool counts, hardware virtualization capability, and quick-launch actions.

See docs/PENETRATION-CENTER-ARCHITECTURE.md, docs/REPOSITORY-MANAGEMENT.md, docs/PACKAGE-SECURITY.md, docs/TOOL-CATALOG.md, docs/TOOL-PROFILES.md, docs/PENETRATION-CENTER-USER-GUIDE.md, docs/AUTHORIZED-SECURITY-TESTING.md, and docs/PENETRATION-CENTER-TESTING.md.

13. Future Extension Points (Phase 10 and Beyond)

  • Phase 10 — Update, Recovery & Lifecycle Management:
    • Cryptographically signed A/B update mechanism, atomic rollback capabilities, and emergency rescue shell.
  • Wayland Compositor Migration (Future Major Release):
    • Migration from Xorg/i3wm to a Wayland-based compositor (such as Sway or wlroots) to provide hardware-enforced per-client graphical surface isolation.