mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-08 03:38:23 +00:00
Prageeth Panicker
87c8199012
Add single-node Wazuh stack (manager, indexer, dashboard) as a new
Ansible role, integrated with the platform's Keycloak realm via native
OIDC and secondary LDAP authorization, with three-tier RBAC.
- Pins wazuh/wazuh-{manager,indexer,dashboard}:4.14.6 and
wazuh-certs-generator:0.0.4 (one-shot cert bootstrap job)
- No external database: wazuh.indexer (OpenSearch) is self-contained
- Auth: native OIDC against Keycloak, working end-to-end after two
infra fixes (JVM cacerts trust for the indexer's outbound calls to
Keycloak, front-proxy vhost wiring)
- LDAP wired as a secondary, authentication-independent authorization
backend (group-based backend_roles enrichment only)
- RBAC: three roles (administrator, security-analyst, readonly-auditor)
via the platform's standard meta/rbac.yml + rbac_group_path pipeline
- Documents a genuine upstream Wazuh bug: wz-home as the default
landing route throws an uncaught client exception for any
non-all_access role; default route moved to OpenSearch Dashboards'
own /app/home
Addressed two full rounds of review feedback (Kevin, Alejandro):
WEB_PROTOCOL usage, service-account naming, comment cleanup, shared
Keycloak-admin-helper extraction, a real TOCTOU race in RBAC test
setup, a Mermaid auth-flow diagram, meta/services.yml placement for
the certs-generator, CA-trust-path SPOT usage, CSP tightening
(including a genuine worker-src: blob: requirement found via live
testing), and a loud (non-silent) dev-bucket fallback warning.
Rebased onto main after a 3-month gap; brought the role in line with
~30 platform-convention changes introduced in that window (swarm
compose-template rules, Tor/onion contract, Playwright timeout/goto
wrappers, file layout, task numbering, comment policy, and more).
Live-deploy verification (9 iterations) found and fixed 6 further
real bugs invisible to lint/unit tests alone:
- credentials.* / meta/schema.yml -> secrets.credentials.* /
meta/secrets.yml (another platform-drift casualty)
- notify: "compose up" -> "compose-up" (day-one handler-name typo)
- local.subnet collision with web-app-mailu's /24
- missing primary: false alongside tor.exclusive: false, which let
the onion domain shadow the clearnet vhost entirely
- a second front-proxy include for the onion domain, later reverted
(see below)
- shared sys-stk-front-proxy/sys-front-tls TLS-lookup keying bug
(app-id-keyed vs. domain-keyed), which silently applied TLS to
Wazuh's onion vhost
The last two are related: enabling genuine dual-stack (clearnet +
onion) reachability for tor.exclusive: false surfaced a real bug in
two shared platform roles. That fix was verified safe against all 103
apps currently in the repo, but is deliberately NOT included here -
shared-role changes deserve their own PR and review, not to ride in
on a single app's feature branch. Wazuh's second front-proxy include
was reverted accordingly; the resulting onion-reachability gap is
documented in the README as a known, platform-scoped limitation.
make test: 5508 passed, 3 failed (all three trace to untracked local
scratch files - Dockerfile.bak, scripts/lab-*.sh - not present in any
CI checkout).
Ansible Plugins (plugins/) 🧩
This document is the central reference for plugin types and plugin placement in Infinito.Nexus.
Not to be confused with application addons. This
plugins/directory holds Ansible plugins (action / filter / lookup) that extend the automation engine itself. Some applications also call their own extensions "plugins" (e.g. Nextcloud, WordPress). Those application-level extensions, whatever the app calls them natively, are declared through the unifiedmeta/addons/contract, documented in Unified Addons. An app "plugin" is an addon; an Ansible plugin lives here.
Current Project Layout 🗂️
plugins/
├── action/ # custom action plugins
├── filter/ # custom Jinja2 filters
└── lookup/ # custom lookup plugins
Configured plugin paths in this repository are defined in ansible.cfg:
action_plugins = ./plugins/actionfilter_plugins = ./plugins/filterlookup_plugins = ./plugins/lookup
All Common Ansible Plugin Types 📚
The table below summarizes common Ansible plugin types and their conventional directory names.
| Emoji | Plugin Type | Conventional Directory | Purpose |
|---|---|---|---|
| ⚙️ | action |
action_plugins/ or plugins/action/ |
Wrap/extend module execution behavior at task runtime. |
| 🔐 | become |
become_plugins/ |
Implement privilege escalation methods. |
| 💾 | cache |
cache_plugins/ |
Persist gathered facts and cached data between runs. |
| 📣 | callback |
callback_plugins/ |
React to play/task events (logging, reporting, notifications). |
| 🖧 | cliconf |
cliconf_plugins/ |
Define CLI command transport behavior (mainly network platforms). |
| 🔌 | connection |
connection_plugins/ |
Control how Ansible connects to targets (ssh, local, etc.). |
| 🔍 | filter |
filter_plugins/ or plugins/filter/ |
Add Jinja2 filters for data transformation. |
| 🌐 | httpapi |
httpapi_plugins/ |
API transport layer over HTTP(S), mainly for network devices. |
| 🧭 | inventory |
inventory_plugins/ |
Build dynamic inventories from APIs, services, or files. |
| 👉 | lookup |
lookup_plugins/ or plugins/lookup/ |
Resolve dynamic values during playbook processing. |
| 🛰️ | netconf |
netconf_plugins/ |
NETCONF transport integration for network automation. |
| 🐚 | shell |
shell_plugins/ |
Adjust shell command wrapping/execution behavior. |
| 🧠 | strategy |
strategy_plugins/ |
Customize task scheduling/execution strategy. |
| ✅ | test |
test_plugins/ |
Add Jinja2 tests used in conditions and templates. |
| 📦 | vars |
vars_plugins/ |
Load variables from custom sources. |
Which Plugin Type to Use 🧭
action ⚙️
Use when task execution behavior itself must be changed or wrapped.
Examples:
- centralized retry logic (
uri_retry.py), - argument normalization before module dispatch,
- pre/post task orchestration.
filter 🔍
Use for pure data transformation in Jinja2 expressions.
Examples:
- mapping/normalizing dictionaries,
- deriving computed fields for templates,
- deterministic formatting helpers.
lookup 👉
Use when a value must be dynamically resolved at runtime.
Examples:
- computing IDs from role metadata,
- resolving paths/version data,
- reading structured project data for templates/tasks.
callback 📣
Use to hook into execution events and shape output/reporting.
inventory 🧭
Use when host/group data should come from a dynamic source.
strategy 🧠
Use to alter how tasks are scheduled/executed across hosts.
vars 📦
Use to load variables from custom backends.
connection, become, shell 🔌🔐🐚
Use to customize low-level execution and privilege mechanics.
cache 💾
Use to persist facts/results across runs for performance and consistency.
cliconf, httpapi, netconf 🖧🌐🛰️
Use in network automation contexts requiring protocol-specific transport behavior.
test ✅
Use to add custom Jinja2 test operators for conditional logic.
Best Practices 🧪
- Keep plugin interfaces explicit and stable.
- Keep plugin logic focused; move shared logic to
utils/. - Add unit tests for plugin behavior and integration tests for end-to-end flows.
- Prefer deterministic outputs and avoid hidden global state.
- Document any plugin-specific task arguments in the plugin docstring and README.
References 🔗
- Ansible plugin development: docs.ansible.com
- Ansible plugin index (all types): docs.ansible.com
- Ansible
ansible-docplugin types:ansible-doc -t ...