# KNELConfigMgmt-Ansible (KNELIAC)

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/<host>.yml`), per-group
(`inventory/group_vars/<group>.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
```