Jarian Cottingham 89b7074268 base ground

2026-04-02 17:23:23 -05:00

12 KiB

Raw Blame History

Installation Guide for Fedora Kinoite SAW

Overview

This guide provides step-by-step instructions for building and installing a Secure Air-Gapped Workstation (SAW) using Fedora Kinoite with custom CA trust, WireGuard VPN, and strict security controls.

Prerequisites:

8GB+ USB drive
Computer to build ISO (can be different from target machine)
VPN gateway access information
CA certificate and signing keys
Custom packages (if any)

Part 1: Building the Custom ISO

Step 1: Install Build Tools

On the machine where you'll build the ISO (can be different from target):

# Install required tools
sudo dnf install -y lorax anaconda-tools createrepo_c

Step 2: Prepare Repository Structure

# Create directory structure
mkdir -p ~/saw-build/{iso,packages,config}

# Download base Fedora Kinoite ISO
# Visit: https://kinoite.fedoraproject.org/
# Download latest ISO

Step 3: Customize Kickstart File

Edit kickstart/kinoite-saw.ks:

Required Customizations:

CA Certificate Path:

# Change this line with your CA cert path
%include /tmp/kickstart-ca-certificate.ks

Package List:

# Add your custom packages
# Remove unnecessary packages

VPN Gateway:

# Update VPN configuration
# Add your WireGuard config

User Configuration:

# Set up your user account
user --name=saw-user --password=changeme

Step 4: Add CA Certificate

Place your CA certificate in package-verification/ca/ca.crt:

# Your CA certificate should be in PEM format
# This will be installed to /etc/pki/ca-trust/source/anchors/

Step 5: Build ISO

cd ~/saw-build

# Copy kickstart
cp /path/to/kickstart/kinoite-saw.ks .

# Build ISO using lorax
sudo lorax -s file:///path/to/kinoite-iso -p Fedora-Kinoite-SAW -v "SAW 1.0" \
  --repo Fedora-Kinoite=file:///path/to/kinoite-iso \
  --arch x86_64 \
  --no-compress \
  --variant Server \
  kinoite-saw.ks

# Output will be in ~/saw-build/output/

Alternative: Using Pungi (Fedora Build System)

# Install pungi
sudo dnf install -y pungi

# Create compose configuration
cat > compose-config.toml << EOF
[compose]
release = "SAW 1.0"
version = "1.0"
distro = "Fedora-Kinoite-43"
base_arches = ["x86_64"]

[packages]
# Add your custom packages here
EOF

# Build
sudo pungi-gather --compose-dir compose
sudo pungi-make-iso --compose-dir compose

Step 6: Test ISO

# Test in VM first
qemu-system-x86_64 -m 4096 -cdrom output/Fedora-Kinoite-SAW.iso

# Or use VirtualBox/Virtual Machine Manager

Part 2: Installation to Target Machine

Step 1: Prepare Installation Media

# Identify USB device
lsblk

# Write ISO to USB (replace /dev/sdX with your device)
sudo dd if=output/Fedora-Kinoite-SAW.iso of=/dev/sdX bs=4M status=progress
sync

# Verify
lsblk /dev/sdX

Step 2: Boot Installation Media

# Insert USB into target machine
# Boot and select USB as boot device
# Press 'e' to edit boot options if needed
# Add 'inst.ks=file:///run/media/user/kickstart.ks' for automated install

Step 3: Installation Wizard

Select Installation Destination:
- Choose disk to install to
- Select "I will configure partitioning"
- Create partitions:
  - / - 15GB minimum (20GB recommended)
  - swap - 2-4GB
  - /home - remaining space
  - /boot/efi - 512MB (for UEFI)
Configure Network:
- Enable network interface
- Configure VPN if needed for package installation
Set Root Password:
- Use strong password
- Store securely
Create User:
- Username: saw-user (or your preferred name)
- Set strong password
- Enable sudo access temporarily for post-install setup
Begin Installation:
- Wait for installation to complete
- Remove USB when prompted

Step 4: First Boot

# Complete initial setup
# Configure timezone, language, etc.
# Log in with your user account

Part 3: Post-Installation Lockdown

Step 1: Initial System Update

# Check for updates
sudo rpm-ostree status

# Apply updates
sudo rpm-ostree upgrade

# Reboot if needed
sudo reboot

Step 2: Run Lockdown Script

# Copy lockdown script to system
sudo cp post-install/lockdown.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/lockdown.sh

# Run lockdown
sudo /usr/local/bin/lockdown.sh

What the lockdown script does:

Removes user from wheel group (no sudo access)
Disables root SSH login
Configures PAM for MFA (if enabled)
Enables SELinux enforcing mode
Enables auditd
Configures firewall
Sets up VPN
Configures DNS lockdown

Step 3: Verify Installation

# Check sudo access (should be denied)
sudo -l

# Check user groups (should not include wheel)
id

# Check firewall
sudo firewall-cmd --list-all

# Check SELinux
sestatus

# Check auditd
sudo systemctl status auditd

# Check VPN
wg show

Step 4: Configure VPN

# Copy VPN configuration
sudo cp package-verification/ca/ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

# Copy WireGuard config
sudo cp config/wireguard/wg0.conf /etc/wireguard/
sudo chmod 600 /etc/wireguard/wg0.conf

# Start WireGuard
sudo wg-quick up wg0

# Check VPN connection
wg show
ping -c 3 <vpn-gateway-ip>

Step 5: Test DNS

# Test DNS resolution (should use VPN gateway)
nslookup google.com

# Check /etc/resolv.conf
cat /etc/resolv.conf

# Test that non-VPN DNS fails
# (should timeout or fail)

Step 6: Test Firewall

# Check firewall status
sudo firewall-cmd --list-all

# Test outbound connection (should go through VPN)
curl -v https://check.torproject.org

# Test direct connection (should fail)
curl -v https://8.8.8.8

Step 7: Verify Package Trust

# Check CA certificate is installed
ls /etc/pki/rpm-gpg/

# Verify DNF configuration
cat /etc/dnf/dnf.conf

# Test package verification
sudo dnf makecache

Part 4: Verify Security Controls

Step 1: Verify Sudo is Disabled

# As regular user, try sudo
sudo whoami
# Expected: "user is not in the sudoers file."

# Check user groups
id
# Expected: Should not show 'wheel' group

Step 2: Verify SELinux

# Check SELinux status
sestatus

# Expected: "Current mode: enforcing"
# Expected: "SELinux enforcement: Enabled"

# Check for denials
sudo ausearch -m avc -ts recent

Step 3: Verify Audit Logging

# Check auditd status
sudo systemctl status auditd

# Test audit logging
sudo auditctl -l

Step 4: Verify Firewall

# Check firewall rules
sudo firewall-cmd --list-all

# Check active zones
sudo firewall-cmd --list-zones

# Verify WireGuard is allowed
sudo firewall-cmd --list-services --zone=wg0

Step 5: Verify DNS

# Check DNS configuration
cat /etc/resolv.conf

# Test DNS resolution
nslookup example.com

# Verify DNS goes through VPN
sudo tcpdump -i any port 53

Step 6: Verify VPN

# Check WireGuard interface
wg show

# Check routing
ip route show

# Verify all traffic goes through VPN
ip route show table 51820

Part 5: Install Custom Packages

Step 1: Prepare Package Repository

# Create local repository
sudo mkdir -p /opt/packages
sudo cp /path/to/custom-packages/*.rpm /opt/packages/

# Create repository metadata
sudo createrepo /opt/packages/

# Create repo file
cat > /etc/yum.repos.d/custom.repo << EOF
[custom-packages]
name=Custom Packages
baseurl=file:///opt/packages
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-your-ca
repo_gpgcheck=1
EOF

# Import CA key
sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-your-ca

Step 2: Install Custom Packages

# Make cache
sudo dnf makecache

# Install custom package
sudo dnf install your-custom-package

# Verify signature
rpm --checksig your-custom-package

Step 3: Install Flatpak Applications

# Add Flathub (if needed)
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Install applications
flatpak install --user flathub org.gnome.Firefox
flatpak install --user flathub org.libreoffice.LibreOffice
flatpak install --user flathub org.mozilla.thunderbird

# Verify installation
flatpak list

Part 6: Configure Update System

Step 1: Set Up Auto-Download

# Configure rpm-ostree to auto-download
cat > /etc/rpm-ostreed.conf << EOF
[Service]
DownloadOnly=true
EOF

# Enable auto-download service
sudo systemctl enable rpm-ostreed

Step 2: Configure Approval Workflow

# Create approval script
cat > /usr/local/bin/approve-update.sh << 'EOF'
#!/bin/bash
# Update approval script
# Shows update details and requires confirmation

sudo rpm-ostree update --check

echo "Review the update above."
echo "Type 'yes' to apply, 'no' to cancel:"
read response

if [ "$response" = "yes" ]; then
    sudo rpm-ostree upgrade
else
    echo "Update cancelled"
fi
EOF

chmod +x /usr/local/bin/approve-update.sh

Step 3: Set Up Daily CRL Update

# Copy CRL updater script
sudo cp scripts/daily-crl-update.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/daily-crl-update.sh

# Set up cron job
sudo crontab -l > mycron || echo "" > mycron
echo "0 2 * * * /usr/local/bin/daily-crl-update.sh >> /var/log/crl-update.log 2>&1" >> mycron
sudo crontab mycron
sudo rm mycron

# Verify cron job
sudo crontab -l

Part 7: Final Verification

Step 1: Run Security Audit

# Copy audit script
sudo cp scripts/security-audit.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/security-audit.sh

# Run audit
sudo /usr/local/bin/security-audit.sh

Step 2: Test Full System

# Test VPN connectivity
curl -v https://check.torproject.org

# Test DNS lockdown
nslookup google.com

# Test firewall
curl -v https://8.8.8.8

# Test sudo is disabled
sudo whoami

# Test package verification
sudo dnf check-update

Step 3: Document Configuration

# Save system status
sudo rpm-ostree status > /root/system-status.txt

# Save firewall rules
sudo firewall-cmd --list-all > /root/firewall-rules.txt

# Save VPN config
sudo wg show > /root/wireguard-status.txt

# Save audit logs
sudo ausearch -m all -ts recent > /root/audit-log.txt

Troubleshooting Installation Issues

Issue: ISO Build Fails

Symptoms: lorax fails with error

Solution:

# Check ISO path
ls -la /path/to/kinoite-iso

# Check kickstart syntax
ksvalidator kinoite-saw.ks

# Try with --no-compress flag
sudo lorax --no-compress ...

Issue: Installation Hangs

Symptoms: Installation process hangs

Solution:

# Boot with debug kernel
# Add to boot parameters: inst.debug inst.vnc inst.sshd

# Check disk space
df -h

# Check memory
free -h

Issue: Package Verification Fails

Symptoms: DNF: signature verification failed

Solution:

# Verify CA certificate
openssl x509 -in /etc/pki/rpm-gpg/RPM-GPG-KEY-your-ca -text -noout

# Re-import key
sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-your-ca

# Check package signature
rpm --checksig package.rpm

Issue: VPN Not Connecting

Symptoms: wg-quick up wg0 fails

Solution:

# Check config
cat /etc/wireguard/wg0.conf

# Check firewall
sudo firewall-cmd --list-all

# Check routing
ip route show

# Test connectivity
ping -c 3 <server-ip>

Issue: DNS Not Working

Symptoms: Cannot resolve domain names

Solution:

# Check resolv.conf
cat /etc/resolv.conf

# Check dnsmasq
sudo systemctl status dnsmasq

# Check firewall
sudo firewall-cmd --list-services

Next Steps

After successful installation:

Test all applications - Verify everything works as expected
Configure backup - Set up backup for important data
Document procedures - Write your own operational procedures
Set up monitoring - Configure log monitoring
Create recovery plan - Document recovery procedures

References

Previous: README.md
Next: Configuration Details

12 KiB Raw Blame History

Installation Guide for Fedora Kinoite SAW

Overview

Part 1: Building the Custom ISO

Step 1: Install Build Tools

Step 2: Prepare Repository Structure

Step 3: Customize Kickstart File

Step 4: Add CA Certificate

Step 5: Build ISO

Step 6: Test ISO

Part 2: Installation to Target Machine

Step 1: Prepare Installation Media

Step 2: Boot Installation Media

Step 3: Installation Wizard

Step 4: First Boot

Part 3: Post-Installation Lockdown

Step 1: Initial System Update

Step 2: Run Lockdown Script

Step 3: Verify Installation

Step 4: Configure VPN

Step 5: Test DNS

Step 6: Test Firewall

Step 7: Verify Package Trust

Part 4: Verify Security Controls

Step 1: Verify Sudo is Disabled

Step 2: Verify SELinux

Step 3: Verify Audit Logging

Step 4: Verify Firewall

Step 5: Verify DNS

Step 6: Verify VPN

Part 5: Install Custom Packages

Step 1: Prepare Package Repository

Step 2: Install Custom Packages

Step 3: Install Flatpak Applications

Part 6: Configure Update System

Step 1: Set Up Auto-Download

Step 2: Configure Approval Workflow

Step 3: Set Up Daily CRL Update

Part 7: Final Verification

Step 1: Run Security Audit

Step 2: Test Full System

Step 3: Document Configuration

Troubleshooting Installation Issues

Issue: ISO Build Fails

Issue: Installation Hangs

Issue: Package Verification Fails

Issue: VPN Not Connecting

Issue: DNS Not Working

Next Steps

References

12 KiB

Raw Blame History