diff --git a/README.md b/README.md index b620a4a..90ed7e2 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,121 @@ -# KNELConfigMgmt-Ansible +# KNELConfigMgmt-Ansible (KNELIAC) -KNEL Configuration Management Collection Ansible \ No newline at end of file +Ansible configuration-management collection for the Known Element Enterprises +fleet. This is the Ansible port of the legacy bash provisioning system that +lives in `PFVCluster/provisioning/`, and is the project that **AWX** +(`tsys-awx.knel.net`) syncs and executes. + +**Target hosts:** Debian-family only (Debian, Ubuntu Server, Kali, Raspberry Pi OS). + +--- + +## Repository layout + +``` +KNELIAC/ +├── ansible.cfg # ansible settings (roles_path, inventory, become) +├── requirements.yml # external collections (currently none) +├── inventory/ +│ ├── hosts.yml # host inventory (physical_hosts / virtual_guests / raspberry_pi) +│ └── group_vars/all.yml # all tunable variables (mirrors hard-coded bash values) +├── playbooks/ +│ ├── hello_world.yml # AWX smoke-test playbook +│ └── setup_new_system.yml # full host build (port of SetupNewSystem.sh) +└── roles/ + ├── preflight # host-class detection (physical/raspi/virt/ubuntu/kali) + ├── oam # LibreNMS / check_mk agent + ├── packages # up2date, install fleet toolset, remove unwanted pkgs + ├── system_config # postfix, resolv, snmp, ntp, dhcp, lldpd, cockpit, zsh, shells + ├── security_ssh # sshd_config, authorized_keys, ssh-audit hardening + ├── security_wazuh # wazuh-agent install + hold + ├── security_scap_stig # GRUB perms, modprobe blacklist, banners, cron/at perms + ├── security_2fa # TOTP 2FA for SSH / Cockpit / Webmin + └── security_audit # auditd, journald, logrotate +``` + +## Legacy → Ansible mapping + +| Legacy bash | KNELIAC role | +|------------------------------------------------------|-------------------------| +| `SetupNewSystem.sh` (runner) | `playbooks/setup_new_system.yml` | +| `Project-Includes/PreflightCheck.sh` + `pi-detect.sh`| `roles/preflight` | +| `Modules/OAM/oam-librenms.sh` | `roles/oam` | +| `global-installPackages` + `scripts/up2date.sh` | `roles/packages` | +| `global-systemServiceConfigurationFiles` + `global-postPackageConfiguration` | `roles/system_config` | +| `Modules/Security/secharden-ssh.sh` | `roles/security_ssh` | +| `Modules/Security/secharden-wazuh.sh` | `roles/security_wazuh` | +| `Modules/Security/secharden-scap-stig.sh` | `roles/security_scap_stig` | +| `Modules/Security/secharden-2fa.sh` | `roles/security_2fa` | +| `Modules/Security/secharden-audit-agents.sh` | `roles/security_audit` | + +## Getting started with AWX + +1. **Create a Project** in AWX pointing at this git repo. +2. **Create an Inventory** (either maintain hosts in AWX directly, or sync from + `inventory/hosts.yml`). +3. **Create a Job Template**: + - Playbook: `playbooks/hello_world.yml` + - Run it against any host to confirm AWX can reach, become root, and gather + facts. A green run = the pipeline works. +4. For the full build, create a second Job Template with playbook + `playbooks/setup_new_system.yml`. Each phase is gated by a `run_*` toggle + (see `inventory/group_vars/all.yml`), so you can enable phases incrementally. + +## Configuration + +All knobs live in [`inventory/group_vars/all.yml`](inventory/group_vars/all.yml) +and can be overridden per-host (`inventory/host_vars/.yml`), per-group +(`inventory/group_vars/.yml`), or directly in AWX as **extra vars** on a +Job Template. Key variables: + +| Variable | Purpose | +|-------------------------|------------------------------------------------------| +| `dns_servers` | Authoritative recursive DNS servers | +| `ntp_servers` | Upstream NTP sources | +| `postfix_relayhost` | SMTP smarthost | +| `wazuh_manager` | Wazuh server FQDN | +| `packages_install` | Fleet toolset package list | +| `packages_remove` | Packages purged on every host | +| `run_*` | Feature toggles to enable/skip each hardening phase | + +## Host-class conditionals + +The `preflight` role detects host class at runtime and sets facts that +downstream roles branch on. Inventory groups provide additional static +classification. + +| Fact | Source | Controls | +|------|--------|----------| +| `is_physical_host` | dmidecode Dell + NOT Proxmox + NOT Pi | physical snmpd.conf, CPU governor, physical packages | +| `is_proxmox_host` | dpkg proxmox-ve | physical packages + CPU governor; skips cockpit/tuned | +| `is_virt_guest` | virt-what (hyperv/kvm) | VM snmpd.conf, qemu-guest-agent, tuned virtual-guest | +| `is_raspi` | /sys/firmware/devicetree/base/model | Pi snmpd.conf, skip GRUB perms | +| `is_kali` | ansible_distribution==Kali | skip unavailable packages | +| `is_ubuntu` | ansible_distribution==Ubuntu | skip ssh-audit hardening drop-in | +| `is_ntp_server` | `ntp_servers` inventory group | skip NTP client config | +| `is_dhcp_server` | `dhcp_servers` inventory group | skip dhclient.conf deploy | +| `is_librenms_server` | `librenms_server` inventory group | skip rsyslog forward config | +| `is_wazuh_server` | `wazuh_server` inventory group | skip wazuh-agent install | +| `is_dev_workstation` | `dev_workstations` inventory group | skip hardened sshd_config | + +## Roadmap + +This is the foundation for a comprehensive DISA STIG / CMMC / FedRAMP / ITAR +compliance library. The `security_scap_stig` role is the seed for that work — +additional STIG control roles will be added alongside it. + +## AWX setup + +AWX resources have been created at `http://tsys-awx.knel.net`: + +| Resource | ID | Name | +|----------|----|------| +| Credential | 3 | KNELIAC Git Credential (Source Control) | +| Credential | 4 | KNELIAC Host SSH Key (Machine) | +| Project | 10 | KNELIAC (git, auto-syncs on launch) | +| Inventory | 2 | KNELIAC Fleet (SCM-backed, syncs from hosts.yml) | + +Job templates will be created after the code is pushed to git. Run: +```bash +python3 scripts/awx_create_job_templates.py +```