aim-web2.1.0rc9

2026-09-22 19:23:17 +02:00
parent d095887d2e
commit 3dfc80b782
438 changed files with 31613 additions and 1510 deletions
@@ -0,0 +1,83 @@
+# Playbooks and reporting contracts
+
+**Current AIM 3.3.0rc8.** The catalog is authoritative for typed inputs, requirements and report declarations.
+
+Run options omitted by a caller remain inherited from inventory/role defaults. Core
+requires explicit compatible hosts and final scope review; group shortcuts expand to
+deduplicated explicit hosts. `aim_debug` adds only selected diagnostics, not raw API output.
+
+Normal terminal operations validate existing Vault passwords before launch and retain
+the workflow on a typo. New-encryption/create prompts stay native. Catalog connections
+use inventory/Vault credentials; automatic replay is never performed after launch.
+
+## Catalog audit
+
+| Key | Platforms | Report schema |
+|---|---|---|
+| `checkmk_install_agent` | linux, windows | `checkmk_agent_state_v1` |
+| `checkmk_update_scripts_config` | linux, windows | `checkmk_agent_config_v1` |
+| `checkmk_read_windows_config` | windows | `checkmk_user_config_v1` |
+| `checkmk_cleanup_scripts` | linux, windows | `managed_cleanup_preview_v1` |
+| `debug_test_connection` | linux, windows | None; native target outcomes/progress |
+| `debug_show_disk_usage` | linux, windows | `filesystem_usage_v1` |
+| `debug_detect_host_roles` | linux, windows | `host_capabilities_v1` |
+| `maintenance_export_event_logs` | windows | `event_log_export_v1` |
+| `maintenance_start_stopped_services` | windows | `service_start_summary_v1` |
+| `maintenance_patch_os` | linux, windows | `patch_summary_v1` |
+| `maintenance_reboot_hosts` | linux, windows | None; native target outcomes/progress |
+| `sophos_apply_baseline` | sophosxgs | None; native target outcomes/progress |
+| `sophos_apply_customer` | sophosxgs | None; native target outcomes/progress |
+| `pfsense_apply_baseline` | pfsense | None; native target outcomes/progress |
+
+Customer Sophos profiles share the catalogued customer operation; their five concrete
+playbooks remain unchanged and publish no operation payload. Firewall policies, connection
+test and reboot behavior were not redesigned for reporting.
+
+## Schema and operational details
+
+See [OPERATION_RESULTS.md](OPERATION_RESULTS.md) for field meanings and missing/partial/
+check-mode behavior. Read [CHECKMK.md](CHECKMK.md) for managed filename/section ownership.
+Role READMEs retain local default settings. `list_playbooks` exposes the current typed
+input definitions and resolved report schemas; add-ons need not keep copies of this table.
+
+## OS patch reporting
+
+The catalog exposes `os_patching_reboot`, `os_patching_reboot_delay_minutes`,
+`os_patching_reboot_message`, Windows categories, and the Windows-only
+`os_patching_rescan_after_reboot` flag. The message/delay apply only when AIM initiates a
+reboot.
+
+Windows delegates each current patch wave to one native `ansible.windows.win_updates`
+`state: installed` invocation with `reboot: false`. The module/WUA owns selection and
+sequencing inside that selected category wave; AIM does not loop individual updates or use
+`accept_list` to manufacture its own scheduler. Per-update records returned by the module
+are normalized for reporting.
+
+If the completed wave requires reboot, AIM either defers it or performs the reviewed
+message/delay/reboot. By default (`os_patching_rescan_after_reboot: false`) that reboot ends
+the run, so another wave requires a new operator-approved execution. When explicitly
+enabled, AIM may start another native wave after reboot; continuation is defensively bounded
+to 12 wave invocations. A failed wave is never automatically replayed.
+
+If a wave finishes without reboot, AIM performs one final read-only discovery for reporting
+only. Windows reports expose individual installed and failed updates, bounded HRESULT
+classifications, `continuation_required`, and whether the reported pending list is
+authoritative.
+
+Linux snapshots use dpkg-query/RPM before and after the existing operation, retaining
+architecture and parallel installed version sets. Every net difference is published;
+intermediate no-net-change transactions are not observable from snapshots. No package
+stdout scraping or guessed versions. Check mode never claims installation.
+
+## Service recovery
+
+Initial stopped/eligible/excluded states, actual attempts and post-start observations
+are all separate. `failed_to_start` gives fixed reasons and numeric codes where known.
+The default fail-on-error policy still fails the run after a report is published.
+
+## Security
+
+Catalogs, roles and inventory are trusted controller code. Report schemas are reviewed
+public data contracts, not automatic secret scanners. Operator-owned Checkmk config
+can contain credentials; its reader filters known secret/command fields and publishes
+redacted paths. No general raw-file/data export was enabled.