SAW-Kinoite/INSTALLATION_GUIDE.md

# 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):

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

### Step 2: Prepare Repository Structure

```bash
# 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:**

1. **CA Certificate Path:**
   ```bash
   # Change this line with your CA cert path
   %include /tmp/kickstart-ca-certificate.ks
   ```

2. **Package List:**
   ```bash
   # Add your custom packages
   # Remove unnecessary packages
   ```

3. **VPN Gateway:**
   ```bash
   # Update VPN configuration
   # Add your WireGuard config
   ```

4. **User Configuration:**
   ```bash
   # 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`:

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

### Step 5: Build ISO

```bash
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)**

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

1. **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)

2. **Configure Network:**
   - Enable network interface
   - Configure VPN if needed for package installation

3. **Set Root Password:**
   - Use strong password
   - Store securely

4. **Create User:**
   - Username: `saw-user` (or your preferred name)
   - Set strong password
   - Enable sudo access temporarily for post-install setup

5. **Begin Installation:**
   - Wait for installation to complete
   - Remove USB when prompted

### Step 4: First Boot

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

---

## Part 3: Post-Installation Lockdown

### Step 1: Initial System Update

```bash
# Check for updates
sudo rpm-ostree status

# Apply updates
sudo rpm-ostree upgrade

# Reboot if needed
sudo reboot
```

### Step 2: Run Lockdown Script

```bash
# 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:**

1. **Removes user from wheel group** (no sudo access)
2. **Disables root SSH login**
3. **Configures PAM for MFA** (if enabled)
4. **Enables SELinux enforcing mode**
5. **Enables auditd**
6. **Configures firewall**
7. **Sets up VPN**
8. **Configures DNS lockdown**

### Step 3: Verify Installation

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check auditd status
sudo systemctl status auditd

# Test audit logging
sudo auditctl -l
```

### Step 4: Verify Firewall

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:

1. **Test all applications** - Verify everything works as expected
2. **Configure backup** - Set up backup for important data
3. **Document procedures** - Write your own operational procedures
4. **Set up monitoring** - Configure log monitoring
5. **Create recovery plan** - Document recovery procedures

---

## References

- [Fedora Kinoite Installation Guide](https://kinoite.fedoraproject.org/)
- [rpm-ostree Documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/atomic-updates/)
- [WireGuard Documentation](https://www.wireguard.com/install/)
- [DNF Configuration](https://dnf.readthedocs.io/en/latest/conf.html)

---

**Previous:** [README.md](README.md)  
**Next:** [Configuration Details](CONFIGURATION_DETAILS.md)