You can run the whole playbook or any subset with --tags.
Project layout
The one that I write here for you is a “all-in-one” layout: it includes the inventory, group_vars and everything the playbook needs under the same “linux-hardening” directory.
This of course is not the only way to do it: for example, if you followed my Ansible AWX and Gitlab guides, you will have your inventory and your playbooks divided in different GitLab groups, and this is a way better scalable separation for a real production environment.
The same playbook, in my GitLab / AWX layout
Playbook repo: playbooks/linux-hardening (one repo per automation, everything at the repo root):
Inventory repo: inventories/prod (the hosts and the playbook’s variables live here):
inventories/prod/
└── openstack/
├── openstack.yml # hosts, with a `hardened_servers` group
└── group_vars/
└── hardened_servers.yml # the hardening variables
What moves, what’s dropped, what’s new compared to the all-in-one above:
All-in-one file
In the GitLab layout
linux-hardening.yml
✅ playbook repo (root)
templates/
✅ playbook repo (root, next to the playbook)
inventory.yml
➡️ becomes the inventory in the inventory repo
group_vars/hardened_servers.yml
➡️ moves to the inventory repo (group_vars belong to the inventory)
ansible.cfg
❌ not needed: AWX manages its own config
(none)
➕ new: collections/requirements.yml at the repo root: AWX auto-installs the collections on sync (replaces the manual ansible-galaxy collection install)
collections/requirements.yml (and roles/requirements.yml if the playbook uses external roles) must sit at the repo root: AWX installs Galaxy deps only from the root, never from subfolders.
Then for wiring everything together (read-only credential, Projects, Inventory Source, Job Template…) you can check out Connect AWX to GitLab.
How to use it
Two ways to run it: straight from the command line (CLI), or via AWX pulled from Gitlab (check out both my guides if you want to implement this “real production” approach).
Expand the one you need.
With Ansible CLI
One-time prerequisites on your control node
# Ansible itself + the collections used in the playbooksudo apt install -y ansibleansible-galaxy collection install community.generalansible-galaxy collection install ansible.posix
Reads what would change without applying. Always do this first on a new host, especially with PAM and SSH: verify the diff for /etc/pam.d/su, /etc/securetty, and the sshd drop-in before committing.
Apply the full playbook
ansible-playbook linux-hardening.yml
Apply just one section (using tags)
# Only the firewallansible-playbook linux-hardening.yml --tags firewall# Just sysctl + SSH + sudoansible-playbook linux-hardening.yml --tags "sysctl,ssh,sudo"# Everything except auditd (rules can be noisy on first apply)ansible-playbook linux-hardening.yml --skip-tags auditd
Make auditd immutable (only after the ruleset is stable)
# In group_vars/hardened_servers.yml: set auditd_immutable: trueansible-playbook linux-hardening.yml --tags auditd
After this, auditctl can no longer modify rules until the next reboot. Don’t apply this on a new host you’re still tuning.
Opt a host out of automatic security updates
# In group_vars/hardened_servers.yml (or host_vars/<host>.yml for one host):# unattended_upgrades_enabled: falseansible-playbook linux-hardening.yml --tags updates
The playbook will stop and disable the timer on the next run. Set the flag back to true to re-enable.
With Ansible AWX
The playbook lives in GitLab under a path, e.g. automation/playbooks/LinuxHardening/ and is pulled by an AWX Project: see Connect AWX to GitLab for the wiring. The CLI flags that you see in the Ansible CLI example, are mapped directly to the fields of a Job Template.
Set up the Job Template: Resources → Templates → Add → Job Template:
Inventory: one that contains the hardened_servers group (this playbook targets hosts: hardened_servers, but you could have different groups of machines of course)
Credentials: the Machine credential for the targets
Instance Groups: execution-vms (run on the execution node)
Dry-run first (always): set Job Type → Check and enable Show Changes: that’s the --check --diff above. Launch once and read the diff before a real run!
Apply the full playbook: set Job Type → Run → Launch.
Just one section (tags): use the Job Tags / Skip Tags fields (tick Prompt on launch to choose per-run):
Job Tags firewall → only the firewall
Job Tags sysctl,ssh,sudo → those three
Skip Tags auditd → everything except auditd
Toggles like auditd_immutable / unattended_upgrades_enabled: they’re variables, set them in the inventory’s group_vars for the hardened_servers group, or pass them in the Job Template’s Variables as extra vars (but I don’t recommend to do that):
auditd_immutable: true
For a nicer UI, you can consider to expose them as a Survey on the Job Template (a checkbox per option).
Same cautions as the CLI: dry-run on a new host first, keep disable_password_auth: false until key login works, and don’t set auditd_immutable: true while you’re still tuning.
---# ── SSH ────────────────────────────────────────────────────────────────────ssh_port: 22# IMPORTANT: leave true until every user has a working public key.# Switch to false once you've verified key-based login works for everyone.ssh_password_auth: true# ── Firewall (UFW) ─────────────────────────────────────────────────────────# SSH is added automatically (rate-limited) — add other ports your server serves.ufw_extra_allow: # - { port: 80, proto: tcp, rule: allow } # - { port: 443, proto: tcp, rule: allow }# Optional: restrict SSH to a management subnet (defense in depth on top of fail2ban).# Leave empty to allow SSH from anywhere.ssh_management_cidrs: [] # - 10.0.0.0/24# ── Password policy (pam_pwquality) ────────────────────────────────────────password_min_length: 14password_max_days: 365password_min_days: 1password_warn_age: 7password_history: 5password_enforce_for_root: true# ── Account lockout (pam_faillock) ─────────────────────────────────────────faillock_deny: 5faillock_unlock_time: 900 # 15 minfaillock_fail_interval: 900# ── Shell environment ──────────────────────────────────────────────────────shell_tmout_seconds: 900 # 15 min; raise to 3600 if too aggressivesystem_umask: "027"# ── Sudo ───────────────────────────────────────────────────────────────────sudo_timestamp_timeout: 5 # 0 = always prompt; CIS L1 strict# ── Auditd ─────────────────────────────────────────────────────────────────# Set true ONLY after the ruleset is stable. Once true, the rules become# immutable until reboot — you cannot change them without a reboot.auditd_immutable: false# ── Fail2ban ───────────────────────────────────────────────────────────────fail2ban_bantime: 1hfail2ban_findtime: 10mfail2ban_maxretry: 5fail2ban_ignoreip: - 127.0.0.1/8 - ::1 # - 10.0.0.0/24# ── Unattended-upgrades ────────────────────────────────────────────────────# Master switch: set to false to skip auto-updates entirely (e.g. on hosts# managed by a separate patching pipeline). When false, the playbook also# disables the existing timer if it was previously enabled.unattended_upgrades_enabled: trueunattended_auto_reboot: false # NEVER true in productionunattended_mail: "root"# ── Time sync ──────────────────────────────────────────────────────────────ntp_pool: 2.debian.pool.ntp.org# ── Banner ─────────────────────────────────────────────────────────────────login_banner: | WARNING: Authorized uses only. All activity may be monitored and reported. Unauthorized access is prohibited and will be prosecuted to the full extent of the law.
linux-hardening.yml
The main playbook.
Organised section by section, mirroring the hardening guide.
First run on a production host: open a second SSH session before applying, just in case. The sshd drop-in is validated with sshd -t before being installed (so a typo can’t lock you out), but always have an out-of-band path (console, BMC, second open shell) just in case.
IMPORTANT
ssh_password_auth defaults to true for safety. Switch it to false in group_vars/only after every user on every host has a working public key: otherwise the next run locks out everyone without keys.
INFO
The wheel group is intentionally empty after the playbook runs: su becomes unusable until you add a user. This is deliberate (forcing everyone through sudo). If you actually want one user to retain su access, add them manually with usermod -aG wheel <user> after the run.
What to do next
Apply the playbook to a fresh VM, then run lynis audit system and oscap eval to measure your CIS L1 coverage.
Add an Ansible CI job (e.g. GitHub Actions or Jenkins) that re-runs the playbook in --check mode weekly: any changed report = configuration drift on a host, investigate and re-apply.
