Align docs with profiles and add Mermaid flow diagrams.

Document lab/prod overlays, anti-lockout SSH and MFA rollout visually,
and point chapters at matching Ansible tags where useful.

Author: HecFranco

CONTRIBUTING.md

@@ -9,6 +9,7 @@ Thanks for improving **Linux Server Hardening**.
 3. **Prefer drop-in files** (`sshd_config.d`, `sysctl.d`, `cron.d`) over rewriting entire vendor configs.
 4. **Debian 12/13 first.** Note if a change is Ubuntu-specific.
 5. **No lock-out recipes.** SSH and firewall changes must document console recovery.
+6. **Diagrams sparingly.** Prefer Mermaid only for multi-step flows (bootstrap/harden, SSH cutover, MFA rollout). Single-control chapters stay Threat/Do/Why text.
 
 ## Pull requests
 

README.md

@@ -25,46 +25,55 @@ It is **not** a compliance product, a CIS auditor replacement, or a substitute f
 
 ## Mental model: six defense layers
 
-```text
-┌─────────────────────────────────────────────────────────┐
-│ 6. Operations      monitoring, mail alerts, re-audit    │
-├─────────────────────────────────────────────────────────┤
-│ 5. Detection       auditd, scanners, integrity checks   │
-├─────────────────────────────────────────────────────────┤
-│ 4. Host baseline   packages, passwords, auto-updates    │
-├─────────────────────────────────────────────────────────┤
-│ 3. Network edge    firewall, rate limits, IDS hooks     │
-├─────────────────────────────────────────────────────────┤
-│ 2. Access control  SSH keys, groups, sudo/su policy     │
-├─────────────────────────────────────────────────────────┤
-│ 1. Foundations     threat model, OS choice, lab safety  │
-└─────────────────────────────────────────────────────────┘
+Work **bottom-up**. Changing SSH before you have a firewall recovery path is a common lock-out pattern.
+
+```mermaid
+flowchart TB
+  L1["1. Foundations<br/>threat model · OS · lab safety"]
+  L2["2. Access control<br/>users · SSH keys · sudo/su"]
+  L3["3. Network edge<br/>UFW · Fail2Ban · PSAD"]
+  L4["4. Host baseline<br/>NTP · updates · passwords · sysctl"]
+  L5["5. Detection<br/>auditd · AIDE · scanners"]
+  L6["6. Operations<br/>mail · logwatch · re-audit"]
+  L1 --> L2 --> L3 --> L4 --> L5 --> L6
 ```
 
-Work bottom-up. Changing SSH before you have a firewall recovery path is a common lock-out pattern; the guide orders steps to reduce that risk.
+## Automation flow
+
+Always pick a profile: **lab** (disposable) or **prod** (real `ignoreip`, strict ops).
+
+```mermaid
+flowchart LR
+  A["01-bootstrap.yml<br/>inventory: root"] --> B["Verify key login"]
+  B --> C["02-harden.yml<br/>inventory: admin + new port"]
+  C --> D["03-audit.yml<br/>Lynis report"]
+  C -.-> P1["-e @profiles/lab.yml"]
+  C -.-> P2["-e @profiles/prod.yml"]
+```
 
 ## Repository layout
 
 ```text
 docs/                 Didactic guide (read in order)
-ansible/              Automation that mirrors the layers
-  playbooks/          Entry points (bootstrap → harden → audit)
-  roles/              One concern per role
-  inventories/lab/    Example inventory (replace with yours)
-  group_vars/         Non-secret defaults + vault placeholders
+ansible/
+  playbooks/          bootstrap → harden → audit
+  roles/              one concern per role
+  inventories/lab/    bootstrap vs runtime host files
+  group_vars/         non-secret defaults + vault placeholders
+  profiles/           lab.yml / prod.yml overlays
 ```
 
 | Path | Purpose |
 |------|---------|
 | [docs/00-start-here.md](docs/00-start-here.md) | How to use the kit safely |
 | [docs/01-foundations/](docs/01-foundations/) | Threat model, OS choice, lab safety |
-| [docs/02-access-control/](docs/02-access-control/) | Users, SSH (incl. crypto + MFA), privilege boundaries |
+| [docs/02-access-control/](docs/02-access-control/) | Users, SSH (crypto + MFA), privileges |
 | [docs/03-network/](docs/03-network/) | Firewall, IDS, Docker caveats, CrowdSec |
 | [docs/04-host-baseline/](docs/04-host-baseline/) | NTP, updates, passwords, kernel knobs |
 | [docs/05-detection/](docs/05-detection/) | auditd, AIDE, malware/rootkit checks |
 | [docs/06-operations/](docs/06-operations/) | Mail, logwatch, day-2 review |
-| [docs/07-advanced/](docs/07-advanced/) | GRUB, umask, hidepid, Firejail, and more |
-| [docs/CONTROL-COVERAGE.md](docs/CONTROL-COVERAGE.md) | What is documented vs automated |
+| [docs/07-advanced/](docs/07-advanced/) | AppArmor, FIDO2, GRUB, umask, more |
+| [docs/CONTROL-COVERAGE.md](docs/CONTROL-COVERAGE.md) | Documented vs automated map |
 | [ansible/README.md](ansible/README.md) | How to run the playbooks |
 
 ## Quick start (automation)
@@ -113,8 +122,6 @@ ansible-playbook -i inventories/lab/hosts.yml playbooks/02-harden.yml \
 
 ## Quick start (manual learning path)
 
-If you prefer to learn by hand before automating:
-
 1. Read [docs/00-start-here.md](docs/00-start-here.md)
 2. Complete [docs/01-foundations/](docs/01-foundations/)
 3. Follow layers 2 → 6 in order
@@ -124,12 +131,13 @@ If you prefer to learn by hand before automating:
 
 | Choice | Reason |
 |--------|--------|
-| Debian-focused examples | Validated on Debian 12/13 (asserted in plays) |
+| Debian 12/13 only (asserted) | Predictable packaging and systemd behaviour |
 | Ansible Vault for secrets | Passwords and SMTP tokens must not live in git history |
-| Safer production defaults | No NOPASSWD, no auto-reboot, no PSAD auto-block unless opted in |
-| Default-deny firewall (in and out) | Limits both inbound scanners and unexpected C2 egress |
+| Lab / prod profiles | Same roles; different lockout and strictness knobs |
+| Fail2Ban ignoreip required by default | Prevents banning your own admin IP on public hosts |
+| No NOPASSWD / auto-reboot / PSAD AUTO_IDS by default | Safer production posture |
+| Default-deny firewall (in and out) | Limits scanners and unexpected C2 egress |
 | Key-only SSH, no root login | Removes the highest-value, most-probed credentials |
-| Security-only unattended upgrades | Patches critical CVEs without surprise feature bumps |
 | Separate bootstrap vs runtime inventories | Avoids `ansible_user: root` sticking on harden plays |
 
 ## Safety contract

ansible/README.md

@@ -27,11 +27,29 @@ ansible-vault encrypt group_vars/all/vault.yml
 
 ## Plays
 
+```mermaid
+flowchart TB
+  subgraph bootstrap["Bootstrap (root inventory)"]
+    B1[admin_user + groups + key + sudo]
+  end
+  subgraph harden["Harden (admin inventory + port)"]
+    H1[packages · ntp · sysctl · ssh]
+    H2[passwords · updates · firewall/IDS]
+    H3[mail · scanners · auditd · logwatch]
+  end
+  subgraph audit["Audit"]
+    A1[Lynis force run + optional mail]
+  end
+  bootstrap --> harden --> audit
+  harden -.-> Lab["-e @profiles/lab.yml"]
+  harden -.-> Prod["-e @profiles/prod.yml"]
+```
+
 | Playbook | Inventory | Purpose |
 |----------|-----------|---------|
 | `01-bootstrap.yml` | `hosts.bootstrap.yml` (root) | Admin user, groups, key, sudo |
 | `02-harden.yml` | `hosts.yml` (admin + port) | Baseline hardening |
-| `03-audit.yml` | `hosts.yml` | Lynis report (forces audit run) |
+| `03-audit.yml` | `hosts.yml` | Lynis report (forces audit run; vault optional) |
 
 ## Safer defaults
 
@@ -47,6 +65,14 @@ ansible-playbook -i inventories/lab/hosts.yml playbooks/02-harden.yml \
   --ask-vault-pass --ask-become-pass -e @profiles/prod.yml
 ```
 
+| Knob | Default (`vars.yml`) | Lab profile | Prod profile |
+|------|----------------------|-------------|--------------|
+| `harden_fail2ban_require_ignoreip` | `true` | `false` | `true` |
+| `harden_strict_ops` | `true` | `false` | `true` |
+| `harden_passwordless_sudo` | `false` | `true` | `false` |
+| `harden_auto_reboot` | `false` | `true` | `false` |
+| `harden_ssh_keys_exclusive` | `false` | — | `true` |
+
 ## Tags
 
 `packages`, `ntp`, `sysctl`, `ssh`, `mfa`, `passwords`, `updates`, `firewall`, `ids`, `mail`, `malware`, `integrity`, `chkrootkit`, `aide`, `auditd`, `logwatch`, `lynis`.
@@ -55,7 +81,7 @@ ansible-playbook -i inventories/lab/hosts.yml playbooks/02-harden.yml \
 
 `--check` is best-effort. Tasks that shell out (moduli trim, aideinit, lynis, psad signature update, test mail) are not fully check-safe.
 
-Optional smoke test (Docker required):
+Optional smoke test (Docker required; also runs in CI):
 
 ```bash
 cd ansible
@@ -72,4 +98,6 @@ roles/
   firewall_stack/ outbound_mail/
   malware_scan/ integrity_checks/ rootkit_extra/ file_integrity/
   audit_framework/ log_digest/ security_audit/
+profiles/
+  lab.yml   prod.yml
 ```

docs/00-start-here.md

@@ -19,41 +19,53 @@ This kit teaches **why** Linux server controls exist, then helps you apply them
 | Verify | How do I prove it worked? |
 | Rollback | How do I undo without rebuilding? |
 
-Copy that pattern when you add controls of your own.
+Where automation exists, chapters mention the matching Ansible **tags** / roles.
 
 ## Suggested order
 
-```text
-Foundations → Access → Network → Host baseline → Detection → Operations
+```mermaid
+flowchart LR
+  F[Foundations] --> A[Access]
+  A --> N[Network]
+  N --> H[Host baseline]
+  H --> D[Detection]
+  D --> O[Operations]
 ```
 
-Skipping ahead is fine for experienced operators, but **never** change the SSH port until:
+Skipping ahead is fine for experienced operators, but **never** change the SSH port until the anti-lockout path below is true.
 
-- your admin user exists,
-- your public key works,
-- the firewall already allows the **new** port,
-- a console session is open.
+```mermaid
+flowchart TD
+  A[Admin user + SSH key works] --> B[Console / VNC open]
+  B --> C[UFW allows NEW SSH port]
+  C --> D[Change sshd + reload]
+  D --> E[Second SSH session succeeds]
+  E --> F[Close first session]
+```
 
 ## Lab vs production
 
-| Topic | Lab | Production |
-|-------|-----|------------|
-| Secrets in Vault | Optional (still good practice) | Mandatory |
+| Topic | Lab (`profiles/lab.yml`) | Production (`profiles/prod.yml`) |
+|-------|--------------------------|----------------------------------|
+| Secrets in Vault | Recommended | Mandatory |
+| Fail2Ban `ignoreip` | Optional | **Required** (real CIDRs, not TEST-NET) |
+| `harden_strict_ops` | Off (soft-fail OK) | On (mail/PSAD/Lynis must work) |
+| Passwordless sudo | Allowed | Off |
+| Auto-reboot after security updates | Allowed | Off / windowed |
+| ClamAV / AIDE / chkrootkit | Often on | Opt-in by load |
 | Default-deny egress | Recommended | Required if you can list needed ports |
-| Mail alerts | Use a throwaway inbox | Use a monitored inbox / ticket route |
-| Scanners (ClamAV, rkhunter) | Nightly is fine | Schedule by load; tune false positives |
-| Reboots after security updates | Automatic OK | Windowed / approved |
 
 ## What “good enough” looks like after day one
 
 - Root cannot SSH in
 - Password SSH is off; keys only
 - Only members of an SSH allow-group can connect
 - Firewall denies unexpected inbound traffic
+- Fail2Ban has an admin/VPN allowlist (prod)
 - Security updates install without waiting for you
 - You receive at least one test alert email
 
-Then iterate: detection depth, kernel hardening, application jails, and continuous audit.
+Then iterate: detection depth, MFA enforce, kernel hardening, and continuous audit.
 
 ## Next
 

docs/01-foundations/lab-setup.md

@@ -50,6 +50,16 @@ ansible_user: admin
 ansible_port: 2222
 ```
 
+Always pass a profile overlay when hardening:
+
+```bash
+# Disposable lab
+-e @profiles/lab.yml
+
+# Real host (edit ignoreip in profiles/prod.yml first)
+-e @profiles/prod.yml
+```
+
 ## Why
 
 Separating **control node** and **target** matches how you will operate later: automation runs from CI or an admin workstation, not from the box being locked down.
@@ -60,7 +70,8 @@ Snapshots and consoles turn irreversible mistakes into five-minute recoveries, w
 
 ```bash
 ssh -i ~/.ssh/lab_ed25519 root@SERVER_IP 'uname -a && cat /etc/os-release | head -3'
-ansible -i inventories/lab/hosts.yml lab-debian -m ping --key-file ~/.ssh/lab_ed25519
+# After copying hosts.bootstrap.yml with your IP:
+ansible -i inventories/lab/hosts.bootstrap.yml lab-debian -m ping --key-file ~/.ssh/lab_ed25519
 ```
 
 You want `pong` and a Debian version string.

docs/02-access-control/ssh-mfa.md

@@ -8,6 +8,16 @@ A stolen laptop with an unlocked SSH private key (or an exported key without a p
 
 Complete **key-only SSH** first. Never enable MFA in the same change window as a port or firewall cutover.
 
+```mermaid
+stateDiagram-v2
+  [*] --> KeyOnly: SSH keys work
+  KeyOnly --> Wired: harden_enable_mfa_role=true<br/>nullok=true (not enforced)
+  Wired --> Enrolled: each admin runs google-authenticator
+  Enrolled --> Enforced: nullok=false<br/>harden_ssh_mfa_enable=true
+  note right of Wired: MFA installed but skippable
+  note right of Enforced: key + TOTP required
+```
+
 ```bash
 apt install -y libpam-google-authenticator
 

docs/02-access-control/ssh-service.md

@@ -8,12 +8,27 @@ Default OpenSSH on port 22 with password authentication is the most scanned surf
 
 ### Order of operations (critical)
 
+```mermaid
+sequenceDiagram
+  participant You
+  participant SSH as sshd
+  participant FW as UFW
+  You->>SSH: 1. Key login works on CURRENT port
+  You->>FW: 2. Allow NEW SSH port (limit)
+  You->>SSH: 3. Write drop-in + sshd -t
+  You->>SSH: 4. Reload sshd
+  You->>SSH: 5. Open SECOND session on new port
+  Note over You: Only then close the first session
+```
+
 1. Confirm key login as `admin` works on the **current** port.
 2. Allow the **new** port in the firewall.
 3. Change `sshd` settings.
 4. Reload `sshd`.
 5. Open a **second** SSH session before closing the first.
 
+Ansible: role `ssh_hardening` (tag `ssh`) pre-allows the port in UFW and flushes handlers before reloading sshd.
+
 ### Recommended policy (modern OpenSSH)
 
 Create a drop-in file (cleaner than editing the whole `sshd_config`):

docs/03-network/firewall.md

@@ -30,6 +30,8 @@ ufw --force enable
 ufw status verbose
 ```
 
+Ansible: role `firewall_stack` (tags `firewall`, `ids`) — also wires Fail2Ban, PSAD, and dedicated iptables logs. Pair with `-e @profiles/lab.yml` or `prod.yml`.
+
 ### Rate limiting
 
 `ufw limit` uses iptables recent-match style limiting on new TCP connections. It will not stop a distributed slow scan, but it blunts simple floods against SSH.

docs/README.md

@@ -37,3 +37,5 @@ Read in order for the full learning path.
 Coverage checklist: [CONTROL-COVERAGE.md](CONTROL-COVERAGE.md)
 
 Automation: [../ansible/README.md](../ansible/README.md)
+
+Diagrams (Mermaid) appear where order matters: kit layers and playbook flow in the [root README](../README.md), anti-lockout SSH path here and in [ssh-service](02-access-control/ssh-service.md), MFA rollout in [ssh-mfa](02-access-control/ssh-mfa.md).