first version of the knowledge base :)

40 - Guides/security/ssh-hardening.md

@@ -0,0 +1,135 @@
+---
+title: SSH Hardening
+description: Practical SSH server hardening guidance for Linux systems in homelab and self-hosted environments
+tags:
+  - security
+  - ssh
+  - linux
+category: security
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# SSH Hardening
+
+## Introduction
+
+SSH is the primary administrative entry point for many Linux systems. Hardening it reduces the likelihood of credential attacks, accidental privilege exposure, and overly broad remote access.
+
+## Purpose
+
+This guide focuses on making SSH safer by:
+
+- Disabling weak authentication paths
+- Reducing exposure to brute-force attacks
+- Limiting which users can log in
+- Preserving maintainability by relying on modern OpenSSH defaults where possible
+
+## Architecture Overview
+
+SSH hardening has three layers:
+
+- Transport and daemon configuration
+- Network exposure and firewall policy
+- Operational practices such as key handling and logging
+
+For most self-hosted systems, the best model is:
+
+```text
+Admin workstation -> VPN or trusted network -> SSH server
+```
+
+## Step-by-Step Guide
+
+### 1. Use key-based authentication
+
+Generate a key on the client and copy the public key to the server:
+
+```bash
+ssh-keygen -t ed25519 -C "admin@example.com"
+ssh-copy-id admin@server.example
+```
+
+### 2. Harden `sshd_config`
+
+Baseline example:
+
+```text
+PermitRootLogin no
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+PubkeyAuthentication yes
+MaxAuthTries 3
+LoginGraceTime 30
+X11Forwarding no
+AllowTcpForwarding no
+AllowAgentForwarding no
+AllowUsers admin
+```
+
+If you need port forwarding for a specific workflow, enable it deliberately instead of leaving it broadly available.
+
+### 3. Validate the configuration
+
+```bash
+sudo sshd -t
+```
+
+### 4. Reload safely
+
+Keep an existing SSH session open while reloading:
+
+```bash
+sudo systemctl reload sshd
+```
+
+Distribution-specific service names may be `ssh` or `sshd`.
+
+### 5. Restrict network exposure
+
+- Prefer VPN-only or management-VLAN-only access
+- Allow SSH from trusted subnets only
+- Do not expose SSH publicly unless it is necessary and monitored
+
+## Configuration Example
+
+Example host firewall intent:
+
+```text
+Allow TCP 22 from 192.168.10.0/24
+Allow TCP 22 from Tailscale tailnet range
+Deny TCP 22 from all other sources
+```
+
+## Troubleshooting Tips
+
+### Locked out after config change
+
+- Keep the original session open until a new login succeeds
+- Validate the daemon config with `sshd -t`
+- Check the service name and logs with `journalctl -u sshd` or `journalctl -u ssh`
+
+### Key authentication fails
+
+- Check file permissions on `~/.ssh` and `authorized_keys`
+- Confirm the server allows public key authentication
+- Verify the client is offering the intended key with `ssh -v`
+
+### Automation jobs break
+
+- Review whether the workload depended on password auth, port forwarding, or agent forwarding
+- Create narrowly scoped exceptions rather than reverting the whole hardening change
+
+## Best Practices
+
+- Rely on current OpenSSH defaults for ciphers and algorithms unless you have a specific compliance need
+- Disable password-based interactive logins on internet-reachable systems
+- Use individual user accounts and `sudo` instead of direct root SSH
+- Combine SSH hardening with network-level restrictions
+- Review SSH logs regularly on administrative systems
+
+## References
+
+- [OpenBSD `sshd_config` manual](https://man.openbsd.org/sshd_config)
+- [OpenSSH](https://www.openssh.com/)
+- [Mozilla OpenSSH guidelines](https://infosec.mozilla.org/guidelines/openssh)

40 - Guides/security/yubikey-usage.md

@@ -0,0 +1,113 @@
+---
+title: YubiKey Usage
+description: Guide to using a YubiKey for SSH, authentication, and key protection in self-hosted environments
+tags:
+  - security
+  - yubikey
+  - ssh
+category: security
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# YubiKey Usage
+
+## Introduction
+
+A YubiKey is a hardware token that can protect authentication and cryptographic operations. In homelab and engineering workflows, it is commonly used for MFA, SSH keys, and protection of GPG subkeys.
+
+## Purpose
+
+Use a YubiKey when you want:
+
+- Stronger authentication than password-only login
+- Private keys that require physical presence
+- Portable hardware-backed credentials for administrative access
+
+## Architecture Overview
+
+YubiKeys can be used through different interfaces:
+
+- FIDO2 or WebAuthn: MFA and modern hardware-backed authentication
+- OpenSSH security keys: SSH keys such as `ed25519-sk`
+- OpenPGP applet: card-resident GPG subkeys
+- PIV: smart-card style certificate workflows
+
+Choose the interface based on the workflow instead of trying to use one mode for everything.
+
+## Step-by-Step Guide
+
+### 1. Use the key for MFA first
+
+Register the YubiKey with identity providers and critical services before moving on to SSH or GPG workflows.
+
+### 2. Create a hardware-backed SSH key
+
+On a system with OpenSSH support for security keys:
+
+```bash
+ssh-keygen -t ed25519-sk -C "admin@example.com"
+```
+
+This creates an SSH key tied to the hardware token.
+
+### 3. Install the public key on servers
+
+```bash
+ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub admin@server.example
+```
+
+### 4. Test login
+
+```bash
+ssh admin@server.example
+```
+
+Expect a touch prompt when required by the device policy.
+
+## Configuration Example
+
+Example client SSH config for a dedicated administrative target:
+
+```text
+Host lab-admin
+  HostName server.example
+  User admin
+  IdentityFile ~/.ssh/id_ed25519_sk
+```
+
+For GPG workflows, move only subkeys onto the YubiKey and keep the primary key offline when possible.
+
+## Troubleshooting Tips
+
+### The key is not detected
+
+- Confirm USB or NFC access is available
+- Check whether another smart-card daemon has locked the device
+- Verify the client OS has support for the intended mode
+
+### SSH prompts repeatedly or fails
+
+- Make sure the correct public key is installed on the server
+- Confirm the client is offering the security-key identity
+- Check that the OpenSSH version supports the selected key type
+
+### GPG or smart-card workflows are inconsistent
+
+- Verify which YubiKey applet is in use
+- Avoid mixing PIV and OpenPGP instructions unless the workflow requires both
+- Keep backup tokens or recovery paths for administrative access
+
+## Best Practices
+
+- Use the YubiKey as part of a broader account recovery plan, not as the only path back in
+- Keep at least one spare token for high-value admin accounts
+- Prefer hardware-backed SSH keys for administrator accounts
+- Document which services rely on the token and how recovery works
+- Separate MFA usage from certificate and signing workflows unless there is a clear operational reason to combine them
+
+## References
+
+- [Yubico: SSH](https://developers.yubico.com/SSH/)
+- [Yubico: YubiKey and OpenPGP](https://developers.yubico.com/PGP/)
+- [Yubico developer documentation](https://developers.yubico.com/)