@ebowwa/hetzner 0.1.0

package/auth.js

@@ -0,0 +1,35 @@
+/**
+ * Hetzner authentication utilities
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export function getTokenFromCLI() {
+    try {
+        const configPath = join(homedir(), ".config", "hcloud", "cli.toml");
+        if (existsSync(configPath)) {
+            const config = readFileSync(configPath, "utf-8");
+            const match = config.match(/token\s*=\s*["']([^"']+)["']/);
+            if (match && match[1]) {
+                return match[1];
+            }
+        }
+    }
+    catch (e) {
+        // Ignore errors
+    }
+    return "";
+}
+export function isAuthenticated(apiToken) {
+    return apiToken.length > 0;
+}
+export function resolveApiToken(explicitToken) {
+    if (explicitToken) {
+        return explicitToken;
+    }
+    if (process.env.HETZNER_API_TOKEN) {
+        return process.env.HETZNER_API_TOKEN;
+    }
+    return getTokenFromCLI();
+}
+//# sourceMappingURL=auth.js.map

package/auth.ts

@@ -0,0 +1,37 @@
+/**
+ * Hetzner authentication utilities
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export function getTokenFromCLI(): string {
+  try {
+    const configPath = join(homedir(), ".config", "hcloud", "cli.toml");
+    if (existsSync(configPath)) {
+      const config = readFileSync(configPath, "utf-8");
+      const match = config.match(/token\s*=\s*["']([^"']+)["']/);
+      if (match && match[1]) {
+        return match[1];
+      }
+    }
+  } catch (e) {
+    // Ignore errors
+  }
+  return "";
+}
+
+export function isAuthenticated(apiToken: string): boolean {
+  return apiToken.length > 0;
+}
+
+export function resolveApiToken(explicitToken?: string): string {
+  if (explicitToken) {
+    return explicitToken;
+  }
+  if (process.env.HETZNER_API_TOKEN) {
+    return process.env.HETZNER_API_TOKEN;
+  }
+  return getTokenFromCLI();
+}

package/bootstrap/FIREWALL.md

@@ -0,0 +1,326 @@
+# UFW Firewall Module
+
+## Overview
+
+The UFW (Uncomplicated Firewall) module provides composable cloud-init blocks for securing servers with a stateful firewall. It follows the same pattern as `ssh-hardening.ts` with three main functions:
+
+- `ufwFirewallPackages()` → Returns packages for the `packages:` section
+- `ufwFirewallWriteFiles()` → Returns files for the `write_files:` section
+- `ufwFirewallRunCmd()` → Returns commands for the `runcmd:` section
+
+## Security Policy
+
+### Default Configuration
+- **Incoming**: DENY (whitelist approach)
+- **Outgoing**: ALLOW (stateful - return traffic allowed)
+- **Forwarded**: DENY
+
+### Standard Ports
+
+| Port | Service | Access | Notes |
+|------|---------|--------|-------|
+| 22 | SSH | Rate-limited | 6 connections per 30 seconds |
+| 80 | HTTP | Optional | Genesis servers only |
+| 443 | HTTPS | Optional | Genesis servers only |
+| 8911 | Node Agent | Workers only | Internal communication |
+| 41641 | Tailscale | Always | VPN functionality |
+
+### Kernel Hardening (via sysctl)
+
+The module also configures kernel network security parameters:
+
+- **IP spoofing protection**: `rp_filter=1`
+- **ICMP redirect protection**: `accept_redirects=0`
+- **SYN cookies**: `tcp_syncookies=1`
+- **Martian packet logging**: `log_martians=1`
+- **Source address verification**: `secure_redirects=1`
+
+## Files Created
+
+### 1. /etc/ufw/before.rules
+
+Stateful firewall rules applied before UFW rules:
+- Allows loopback interface
+- Drops invalid packets
+- Allows established/related connections
+- Allows ICMP messages (required for PMTU discovery)
+- Drops packets with bogus TCP flags (potential scans)
+
+### 2. /etc/ufw/sysctl.conf
+
+Kernel network security parameters for:
+- IP spoofing protection
+- ICMP redirect protection
+- SYN flood mitigation
+- Martian packet logging
+
+## Usage
+
+### Genesis Servers (Control Plane)
+
+```typescript
+import { generateUFWFirewallForGenesis } from "./firewall";
+
+const firewall = generateUFWFirewallForGenesis();
+// Returns: { packages, writeFiles, runCmd }
+```
+
+Default configuration:
+- SSH: Rate-limited from anywhere
+- HTTP: Enabled
+- HTTPS: Enabled
+- Node Agent: Disabled
+- Logging: Rate-limited
+
+### Worker/Seed Servers
+
+```typescript
+import { generateUFWFirewallForWorker } from "./firewall";
+
+const firewall = generateUFWFirewallForWorker();
+// Returns: { packages, writeFiles, runCmd }
+```
+
+Default configuration:
+- SSH: Rate-limited from anywhere
+- HTTP: Disabled
+- HTTPS: Disabled
+- Node Agent: Enabled (port 8911)
+- Logging: Rate-limited
+
+### Custom Configuration
+
+```typescript
+import { ufwFirewallPackages, ufwFirewallWriteFiles, ufwFirewallRunCmd } from "./firewall";
+
+const options = {
+  allowSSHFrom: ['192.168.1.0/24', '10.0.0.0/8'],
+  allowHTTP: true,
+  allowHTTPS: true,
+  allowNodeAgent: true,
+  additionalPorts: [
+    { port: 3000, protocol: 'tcp', comment: 'Custom app' }
+  ],
+  verboseLogging: false,
+};
+
+const packages = ufwFirewallPackages();
+const writeFiles = ufwFirewallWriteFiles(options);
+const runCmd = ufwFirewallRunCmd(options);
+```
+
+## Integration
+
+The firewall module is automatically integrated into:
+
+1. **Genesis servers** (`genesis.ts`)
+   - Imported and added to bootstrap
+   - Runs after SSH hardening (prevents lockout)
+
+2. **Worker/Seed servers** (`cloud-init.ts`)
+   - Imported and added to bootstrap
+   - Runs after SSH hardening (prevents lockout)
+
+## Testing Instructions
+
+### Local Testing
+
+1. **Build the project**:
+   ```bash
+   cd /Users/ebowwa/Desktop/codespaces/packages/com.hetzner.codespaces
+   bun run build
+   ```
+
+2. **Generate a test cloud-init**:
+   ```bash
+   # Test Genesis firewall
+   bun -e "
+   import { generateGenesisBootstrap } from './workspace/src/lib/bootstrap/genesis.js';
+   const yaml = generateGenesisBootstrap({
+     adminSSHKey: 'ssh-rsa AAAAB3... test@example.com'
+   });
+   console.log(yaml);
+   " > /tmp/genesis-firewall-test.yaml
+   ```
+
+3. **Verify the output**:
+   ```bash
+   grep -A 20 "UFW Firewall" /tmp/genesis-firewall-test.yaml
+   ```
+
+### Live Testing (Hetzner VPS)
+
+**WARNING**: Test on a disposable VPS first!
+
+1. Create a test VPS in Hetzner:
+   ```bash
+   # Using the com.hetzner.codespaces UI or API
+   Server Type: cx11 (cheapest)
+   Location: any
+   SSH Key: Your public key
+   ```
+
+2. Add user data with the generated cloud-init:
+   ```bash
+   # Paste the contents of /tmp/genesis-firewall-test.yaml
+   ```
+
+3. After creation, SSH into the server:
+   ```bash
+   ssh root@<server-ip>
+   ```
+
+4. Verify UFW status:
+   ```bash
+   sudo ufw status verbose
+   ```
+
+   Expected output:
+   ```
+   Status: active
+
+   Logging: on (low)
+   Default: deny (incoming), allow (outgoing), disabled (routed)
+   New profiles: skip
+
+   To                         Action      From
+   --                         ------      ----
+   22/tcp                     LIMIT       Anywhere
+   80/tcp                     ALLOW       Anywhere
+   443/tcp                    ALLOW       Anywhere
+   41641/udp                  ALLOW       Anywhere
+   ```
+
+5. Check firewall logs:
+   ```bash
+   sudo tail -f /var/log/ufw.log
+   # or
+   sudo journalctl -u ufw -f
+   ```
+
+6. Verify kernel parameters:
+   ```bash
+   sysctl net.ipv4.conf.all.rp_filter
+   # Should be: net.ipv4.conf.all.rp_filter = 1
+   
+   sysctl net.ipv4.tcp_syncookies
+   # Should be: net.ipv4.tcp_syncookies = 1
+   ```
+
+7. Test connectivity:
+   ```bash
+   # SSH should work (rate-limited)
+   ssh -v root@localhost
+   
+   # HTTP/HTTPS should work (on Genesis)
+   curl -I http://localhost
+   curl -I https://localhost
+   
+   # Tailscale should work
+   tailscale status
+   ```
+
+### Testing Rate Limiting
+
+Test that SSH rate limiting works:
+
+```bash
+# From another machine, try multiple SSH connections
+for i in {1..10}; do
+  ssh -o ConnectTimeout=2 root@<server-ip> echo "Connection $i" &
+done
+wait
+
+# After 6 fast connections, you should be blocked
+```
+
+## Security Considerations
+
+### Order Matters
+
+The firewall is activated **after** SSH hardening to prevent lockout:
+
+1. Install UFW package
+2. Write configuration files
+3. **SSH hardening** (reload sshd, start fail2ban)
+4. **UFW activation** (configure rules, enable)
+
+### Logging
+
+Default: Rate-limited logging (`ufw logging low`)
+- Prevents log flooding from constant scanning
+- Still logs blocked packets and policy violations
+
+Verbose: High logging (`ufw logging high`)
+- Use only for debugging
+- Can generate large logs on public IPs
+
+### Fail2ban Integration
+
+UFW works alongside fail2ban:
+- fail2ban monitors logs and bans IP addresses
+- UFW provides the firewall backend (nftables on Ubuntu 24.04)
+- Both provide defense-in-depth
+
+## Troubleshooting
+
+### Locked Out
+
+If you get locked out:
+
+1. Use the Hetzner console (VNC/keyboard)
+2. Disable UFW:
+   ```bash
+   sudo ufw disable
+   ```
+3. Check rules:
+   ```bash
+   sudo ufw status numbered
+   ```
+4. Re-enable with correct rules:
+   ```bash
+   sudo ufw --force enable
+   ```
+
+### Rule Conflicts
+
+If rules don't apply:
+
+1. Check for conflicting rules:
+   ```bash
+   sudo ufw show added
+   ```
+
+2. Reset and reapply:
+   ```bash
+   sudo ufw --force reset
+   sudo ufw allow 22/tcp
+   sudo ufw enable
+   ```
+
+### Logs Not Appearing
+
+If logs don't appear:
+
+1. Check logging is enabled:
+   ```bash
+   sudo ufw status verbose
+   ```
+
+2. Check rsyslog configuration:
+   ```bash
+   sudo tail -f /var/log/syslog | grep UFW
+   ```
+
+## References
+
+- [UFW Community Documentation](https://help.ubuntu.com/community/UFW)
+- [UFW Man Page](https://manpages.ubuntu.com/manpages/noble/man8/ufw.8.html)
+- [iptables-extensions](https://manpages.debian.org/testing/iptables-extensions/iptables-extensions.html)
+- [Kernel Sysctl Parameters](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt)
+
+## Sources
+
+- DigitalOcean - UFW Essentials Guide (Jul 31, 2025)
+- LinuxSecurity - Ubuntu server SSH firewall rules (Jan 9, 2026)
+- Ubuntu Community Wiki - Official UFW documentation

package/bootstrap/KERNEL-HARDENING.md

@@ -0,0 +1,258 @@
+# Kernel Hardening Module
+
+## Overview
+
+The kernel hardening module provides comprehensive Linux kernel security hardening for cloud-init bootstrap. It implements 2026 best practices aligned with CIS Benchmarks and NIST guidelines.
+
+## Architecture
+
+The module follows the same composable pattern as other bootstrap modules:
+
+- **`kernelHardeningPackages()`** → Returns packages array (currently empty)
+- **`kernelHardeningWriteFiles()`** → Returns write_files YAML lines
+- **`kernelHardeningRunCmd()`** → Returns runcmd YAML lines
+
+## Security Measures
+
+### 1. IP Spoofing Protection
+```conf
+net.ipv4.conf.all.rp_filter = 1              # Reverse path filtering
+net.ipv4.conf.all.log_martians = 1          # Log impossible addresses
+net.ipv4.conf.all.accept_redirects = 0      # Block ICMP redirects
+net.ipv4.conf.all.secure_redirects = 0      # Block secure redirects
+net.ipv4.conf.all.send_redirects = 0        # Don't send redirects
+```
+
+### 2. SYN Flood Protection
+```conf
+net.ipv4.tcp_syncookies = 1                 # Enable SYN cookies
+net.ipv4.tcp_tw_reuse = 1                   # Reuse TIME_WAIT sockets
+net.ipv4.tcp_max_syn_backlog = 2048         # Increase SYN backlog
+net.ipv4.tcp_synack_retries = 2             # Reduce SYNACK retries
+net.ipv4.tcp_syn_retries = 5                # Reduce SYN retries
+```
+
+### 3. Network Stack Hardening
+```conf
+net.ipv4.icmp_echo_ignore_broadcasts = 1    # Block broadcast pings
+net.ipv4.icmp_ignore_bogus_error_responses = 1 # Block bogus ICMP
+net.ipv4.tcp_timestamps = 1                 # Enable TCP timestamps
+net.ipv4.tcp_sack = 1                       # Enable selective ACK
+```
+
+### 4. Core Dump Restrictions
+```conf
+fs.suid_dumpable = 0                        # Disable setuid core dumps
+kernel.core_pattern = |/bin/false           # Disable core dumps
+```
+
+### 5. Memory Protection (ASLR)
+```conf
+kernel.randomize_va_space = 2               # Full ASLR
+```
+
+### 6. Filesystem Protection
+```conf
+fs.protected_hardlinks = 1                  # Prevent hard link attacks
+fs.protected_symlinks = 1                   # Prevent symlink attacks
+fs.protected_fifos = 2                      # Prevent FIFO attacks
+fs.protected_regular = 2                    # Prevent file overwrite
+```
+
+### 7. Security-Related Parameters
+```conf
+kernel.sysrq = 0                            # Disable magic sysrq
+kernel.kexec_load = 0                       # Disable kexec
+user.max_user_namespaces = 0                # Disable user namespaces
+kernel.unprivileged_bpf_disabled = 1        # Disable unprivileged BPF
+```
+
+### 8. Additional Hardening (2026)
+```conf
+kernel.dmesg_restrict = 1                   # Restrict dmesg
+kernel.yama.ptrace_scope = 2                # Restrict ptrace
+```
+
+## Integration
+
+### Cloud-Init Integration
+
+The module is integrated into both seed and Genesis bootstrap:
+
+```typescript
+import {
+  kernelHardeningPackages,
+  kernelHardeningWriteFiles,
+  kernelHardeningRunCmd,
+} from "./kernel-hardening";
+
+// In cloud-init.ts
+lines.push(...kernelHardeningPackages());
+lines.push(...kernelHardeningWriteFiles());
+lines.push(...kernelHardeningRunCmd());
+```
+
+### Bootstrap Order
+
+Security modules are applied in this order:
+
+1. **UFW Firewall** - Network-level defense
+2. **Kernel Hardening** - System-level hardening
+3. **SSH Hardening** - Service-level hardening
+4. **Security Audit** - Verification and reporting
+
+## File Persistence
+
+All settings are written to `/etc/sysctl.d/99-security-hardening.conf`:
+
+- **Persists across reboots** - Files in `/etc/sysctl.d/` are loaded on boot
+- **Takes precedence** - The `99-` prefix ensures it overrides `/etc/sysctl.conf`
+- **Applied immediately** - `sysctl --system` activates settings without reboot
+
+## Testing
+
+Run tests with `bun test`:
+
+```bash
+cd /Users/ebowwa/Desktop/codespaces/packages/com.hetzner.codespaces/workspace
+bun test src/lib/bootstrap/kernel-hardening.test.ts
+```
+
+### Test Coverage
+
+- ✅ Package array validation
+- ✅ Sysctl configuration completeness
+- ✅ All security categories present
+- ✅ Activation commands
+- ✅ Verification commands
+- ✅ CIS Benchmark compliance
+- ✅ 2026 best practices
+- ✅ Documentation headers
+
+## Verification
+
+### Manual Verification
+
+After bootstrap, verify settings are applied:
+
+```bash
+# Check IP spoofing protection
+sysctl net.ipv4.conf.all.rp_filter
+
+# Check SYN cookies
+sysctl net.ipv4.tcp_syncookies
+
+# Check ASLR
+sysctl kernel.randomize_va_space
+
+# Check core dumps
+sysctl fs.suid_dumpable
+
+# Check filesystem protection
+sysctl fs.protected_hardlinks
+sysctl fs.protected_symlinks
+```
+
+### Automated Verification
+
+The module includes automated verification in `runcmd`:
+
+```bash
+# View applied settings
+cat /var/log/kernel-hardening.log
+
+# Check cloud-init output
+grep "Kernel Hardening Applied" /var/log/cloud-init-output.log
+```
+
+## Compliance
+
+### CIS Benchmark for Ubuntu Linux 24.04
+
+The module implements the following CIS controls:
+
+- **1.5.1** - Restrict core dumps
+- **1.5.2** - Enable ASLR
+- **1.5.4** - Restrict core dump backtraces
+- **3.3.1** - Disable IP forwarding (optional)
+- **3.3.2** - Disable send redirects
+- **3.3.3** - Disable ICMP redirects
+- **3.3.4** - Disable secure ICMP redirects
+- **3.3.5** - Log suspicious packets
+- **3.3.6** - Ignore broadcast ICMP
+- **3.3.7** - Ignore bogus ICMP
+- **3.3.8** - Enable reverse path filtering
+- **3.3.9** - Enable TCP SYN cookies
+
+### NIST SP 800-53 Revision 5
+
+The module addresses the following NIST controls:
+
+- **SC-7** - Boundary Protection
+- **SC-8** - Transmission Confidentiality
+- **SC-39** - Process Isolation
+- **SI-3** - Malicious Code Protection
+- **SI-4** - System Monitoring
+
+## References
+
+- [CIS Benchmark for Ubuntu Linux 24.04](https://www.cisecurity.org/benchmark/ubuntu_linux)
+- [NIST SP 800-53 Revision 5](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final)
+- [Kernel sysctl documentation](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt)
+- [Ubuntu Security Guide](https://ubuntu.com/server/docs/security)
+
+## Troubleshooting
+
+### Settings Not Applied
+
+If settings don't appear active:
+
+1. Check if sysctl service is running:
+   ```bash
+   systemctl status systemd-sysctl.service
+   ```
+
+2. Manually apply settings:
+   ```bash
+   sysctl --system
+   ```
+
+3. Check for conflicting settings:
+   ```bash
+   sysctl -a | grep -E '(rp_filter|syncookies)'
+   ```
+
+### Performance Impact
+
+Some settings may impact performance:
+
+- **SYN cookies** - Slight TCP performance impact
+- **ASLR** - Minimal performance impact
+- **Protected hardlinks** - Minimal filesystem overhead
+
+Monitor performance after hardening:
+
+```bash
+# Check network performance
+iperf3 -c <server>
+
+# Check filesystem performance
+dd if=/dev/zero of=/tmp/test bs=1M count=1024
+
+# Check system load
+uptime
+```
+
+## Files Created
+
+- `/etc/sysctl.d/99-security-hardening.conf` - Sysctl configuration
+- `/var/log/kernel-hardening.log` - Applied settings log
+
+## Next Steps
+
+After kernel hardening, consider:
+
+1. **Firewall** - Use UFW for network-level filtering
+2. **SSH hardening** - Secure SSH service configuration
+3. **Security audit** - Run Lynis for compliance scanning
+4. **System hardening** - Apply user space security measures