Complete the Audita feature
This commit is contained in:
@@ -1,298 +1,12 @@
|
||||
# Implementation Plan 0002: Install and Configure Audita
|
||||
# Implementation Plan
|
||||
|
||||
Status: ready
|
||||
Status: pending
|
||||
|
||||
Target executor: GPT-5.6-Terra
|
||||
No implementation plan is currently active. Feature 0002 was completed in
|
||||
`ansible-role-audita` through commit `3a8c21f`; its durable scope and rationale
|
||||
remain in
|
||||
[the Feature 0002 roadmap](features/0002-audita-source-installation-and-configuration.md),
|
||||
and its review history remains in [the remediation record](remediation.md).
|
||||
|
||||
Feature roadmap:
|
||||
[Feature 0002: Audita Source Installation and Configuration](features/0002-audita-source-installation-and-configuration.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the small, independently usable `rakestraw.audita` role defined by
|
||||
Feature 0002. Install Audita from its pinned source release, build its
|
||||
executable on the managed host, and manage its complete versioned
|
||||
configuration mapping using the minimal module-driven Seriatim pattern.
|
||||
|
||||
## Execution Rules
|
||||
|
||||
- Execute Stage 1 and Stage 2 in numeric order.
|
||||
- Before each stage, confirm its preconditions and the owning repository's
|
||||
working-tree state.
|
||||
- Modify only `ansible-role-audita`. Treat this workspace, `../audita`,
|
||||
`rakestraw-ansible`, and every other repository as read-only.
|
||||
- Preserve unrelated changes. Stop if the role repository is unexpectedly
|
||||
dirty at a stage boundary.
|
||||
- Follow `docs/conventions.md` and the Feature 0002 task flow. Trust the
|
||||
idempotence and change detection of APT, Snap, `file`, `git`, and `copy`.
|
||||
- Put the two rebuild conditions directly on the build task. Do not add an
|
||||
intermediate fact, handler, or handler flush.
|
||||
- Do not execute Audita from production role tasks. Executable and
|
||||
configuration validation belong only in integration tests.
|
||||
- Do not add fingerprints, checksums, sidecar state, manual Git cleanup,
|
||||
staged replacement, compiler inspection, configuration preflight, or
|
||||
out-of-band drift detection.
|
||||
- Use fully qualified collection names and `argv` for command execution.
|
||||
- Run each stage's validation before committing. Do not begin Stage 2 if Stage
|
||||
1 fails.
|
||||
- Commit each completed stage with its specified plain-English message. Do not
|
||||
push.
|
||||
- Treat `/usr/local/src/audita`, `/usr/local/bin/audita`, and
|
||||
`/usr/local/etc/audita/config.yml` as disposable role-managed test state.
|
||||
|
||||
## Starting State and Preconditions
|
||||
|
||||
- `ansible-role-audita` is clean on `main` at initial commit `793e6d3`, tracking
|
||||
`origin/main` without divergence.
|
||||
- This plan and the approved Feature 0002 roadmap are committed before
|
||||
out-of-band execution begins.
|
||||
- The local controller and managed host are Ubuntu 26.04 `amd64`, with
|
||||
passwordless privilege escalation available.
|
||||
- Workspace tooling is available in `../.venv/bin` from the role repository:
|
||||
Ansible Core 2.21.3 and ansible-lint 26.8.0.
|
||||
- `community.general` 13.3.0 and Go Snap channel `1.26/stable` are available.
|
||||
- Upstream tag `v0.9.1` resolves to
|
||||
`a84941d68168a1ed9ea7423b6477ae8218be73f9` and uses Go 1.24.0.
|
||||
- The release build uses package
|
||||
`gitea.maximumdirect.net/eric/audita/cmd/audita`, `CGO_ENABLED=0`,
|
||||
`GOWORK=off`, `GOTOOLCHAIN=local`, `-trimpath`, and linker flags `-s -w -X
|
||||
gitea.maximumdirect.net/eric/audita/internal/buildinfo.Version=<version>`.
|
||||
- Configuration schema version 1 accepts `{"version": 1}`. The command
|
||||
`audita config validate --config <path>` emits `config is valid` for it.
|
||||
- Buildable commit `46b7356a3b54a2771ce9a617e4fa3e8d13728cac` is available for the
|
||||
checkout-change test. Do not use `v0.9.0` for that test because it resolves
|
||||
to the same commit as `v0.9.1`.
|
||||
|
||||
## Repository Scope
|
||||
|
||||
- `ansible-role-audita` owns all implementation, interface, README,
|
||||
dependency, and repository-local test changes.
|
||||
- `ansible-workspace-dnd` owns the roadmap, plan, and aggregate status but
|
||||
remains unchanged during out-of-band implementation.
|
||||
- `../audita` is the authoritative read-only application contract.
|
||||
- `rakestraw-ansible` is a read-only style and configuration-policy reference.
|
||||
- Every other repository in `workspace.yml` remains unchanged.
|
||||
|
||||
## Fixed Public Interface
|
||||
|
||||
Implement exactly these defaults and matching argument specifications:
|
||||
|
||||
| Variable | Default |
|
||||
| --- | --- |
|
||||
| `audita_version` | `v0.9.1` |
|
||||
| `audita_repository_url` | `https://gitea.maximumdirect.net/eric/audita.git` |
|
||||
| `audita_source_dir` | `/usr/local/src/audita` |
|
||||
| `audita_binary_path` | `/usr/local/bin/audita` |
|
||||
| `audita_manage_build_dependencies` | `true` |
|
||||
| `audita_go_snap_channel` | `1.26/stable` |
|
||||
| `audita_go_binary` | `/snap/bin/go` |
|
||||
| `audita_config_path` | `/usr/local/etc/audita/config.yml` |
|
||||
| `audita_config` | `{"version": 1}` |
|
||||
|
||||
The build details, ownership, and modes are fixed implementation details.
|
||||
`audita_config` is the complete document, not an overlay onto hidden defaults.
|
||||
|
||||
## Stage 1: Implement the Complete Minimal Role
|
||||
|
||||
### Objective
|
||||
|
||||
Create the role contract, concise production task flow, documentation, and
|
||||
baseline test harness that install and configure Audita idempotently.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- The starting revisions and upstream contracts remain unchanged.
|
||||
- `ansible-role-audita` has no uncommitted changes.
|
||||
- The default managed paths contain no data that must be preserved.
|
||||
|
||||
### Owning Repository
|
||||
|
||||
`ansible-role-audita`
|
||||
|
||||
### Required Changes
|
||||
|
||||
1. Add conventional role structure: defaults, metadata, argument
|
||||
specifications, one task file, collection requirements, and focused local
|
||||
tests. Retain the existing license and declare Ubuntu 26.04 support and
|
||||
Ansible Core 2.18 or newer in Galaxy metadata.
|
||||
2. Define exactly the nine variables above. Mirror their names and appropriate
|
||||
scalar, boolean, and dictionary types in the argument specification; do not
|
||||
duplicate Audita's configuration schema there.
|
||||
3. Implement one readable `tasks/main.yml` with approximately this flow:
|
||||
1. assert Ubuntu 26.04 and architecture `x86_64` or `aarch64`;
|
||||
2. install Git with `ansible.builtin.apt`, including
|
||||
`cache_valid_time: 3600`, when dependency management is enabled;
|
||||
3. install the classic Go Snap from `audita_go_snap_channel` with
|
||||
`community.general.snap` when dependency management is enabled;
|
||||
4. create source, binary, and configuration parent directories as
|
||||
`root:root` mode `0755` with one `ansible.builtin.file` loop;
|
||||
5. check out `audita_version` with `ansible.builtin.git`, `force: true`, and
|
||||
register its result;
|
||||
6. inspect `audita_binary_path` with `ansible.builtin.stat`;
|
||||
7. build directly to `audita_binary_path` when the checkout changed or the
|
||||
binary is absent;
|
||||
8. converge recursive `root:root` source ownership and binary `root:root`
|
||||
mode `0755` with one item-driven `ansible.builtin.file` loop;
|
||||
9. serialize `audita_config` as YAML at `audita_config_path` with
|
||||
`ansible.builtin.copy`, `root:root` ownership, and mode `0644`.
|
||||
4. Put the rebuild expression directly on the build command. Register only the
|
||||
Git and binary results it needs. Invoke `audita_go_binary` with `argv`, the
|
||||
fixed upstream build contract, output path, and source working directory.
|
||||
5. Use task-level `become: true` for dependency installation and tasks that
|
||||
manage root-owned state. Do not require play-level privilege escalation.
|
||||
6. Pin `community.general` 13.3.0. Do not add handlers or abstractions for the
|
||||
linear task flow.
|
||||
7. Write a concise README covering the nine-variable interface, supported
|
||||
platform, privilege and fact requirements, dependency opt-out, build and
|
||||
configuration behavior, metadata, rebuild triggers, and test commands.
|
||||
8. Add a baseline integration driver that installs the pinned collection into
|
||||
a private temporary location, runs syntax checking and production-profile
|
||||
ansible-lint, converges without play-level `become`, and verifies the
|
||||
selected commit, recursive source ownership, binary metadata and execution,
|
||||
configuration metadata, and exact native validation output
|
||||
`config is valid`.
|
||||
9. Require an immediate repeat role application to report `changed=0` and
|
||||
`failed=0`. Keep paths repository-relative and temporary test artifacts out
|
||||
of the repository.
|
||||
|
||||
### Validation
|
||||
|
||||
From `ansible-role-audita`, run:
|
||||
|
||||
```sh
|
||||
tests/integration
|
||||
git diff --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
Expected result: syntax and lint pass; source resolves to
|
||||
`a84941d68168a1ed9ea7423b6477ae8218be73f9`; the executable runs and is
|
||||
`root:root` mode `0755`; configuration is schema version 1 and `root:root`
|
||||
mode `0644`; native validation reports `config is valid`; the immediate repeat
|
||||
reports `changed=0` and `failed=0`; only intended Stage 1 changes remain.
|
||||
|
||||
### Completion Criteria
|
||||
|
||||
- Exactly nine defaults and matching argument specifications exist.
|
||||
- Production flow matches the roadmap without unrequested probes, persisted
|
||||
private state, or production validation commands.
|
||||
- README, metadata, dependencies, tasks, and baseline tests agree.
|
||||
- Baseline integration passes and proves default idempotence.
|
||||
- No repository outside `ansible-role-audita` changed.
|
||||
|
||||
### Commit
|
||||
|
||||
Commit message: `Install and configure Audita`
|
||||
|
||||
**Completion:** Complete (`ansible-role-audita` commit `47f1852`).
|
||||
|
||||
## Stage 2: Add Focused Behavioral Coverage
|
||||
|
||||
### Objective
|
||||
|
||||
Prove the selected rebuild triggers, independent configuration convergence,
|
||||
dependency opt-out, metadata repair, platform guard, and restored default
|
||||
state without expanding production behavior.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Stage 1 is committed and the role repository is otherwise clean.
|
||||
- Stage 1 integration passes.
|
||||
- The default release and alternate buildable commit remain available.
|
||||
|
||||
### Owning Repository
|
||||
|
||||
`ansible-role-audita`
|
||||
|
||||
### Required Changes
|
||||
|
||||
1. Extend `tests/integration` using strict shell options, repository-relative
|
||||
paths, a private temporary directory, and cleanup that restores `v0.9.1`.
|
||||
2. Retain baseline convergence, verification, and clean repeat, then test:
|
||||
- an absent binary causes one rebuild followed by an unchanged run;
|
||||
- dependency opt-out with a caller-supplied Go executable causes one build
|
||||
followed by an unchanged run;
|
||||
- binary metadata drift is repaired by `file` without running the build,
|
||||
followed by an unchanged run;
|
||||
- changing `audita_config` updates only configuration state, passes native
|
||||
validation, and reaches an unchanged repeat;
|
||||
- selecting `46b7356a3b54a2771ce9a617e4fa3e8d13728cac` causes one checkout
|
||||
rebuild followed by an unchanged run;
|
||||
- restoring `v0.9.1` confirms its commit, causes one rebuild, and reaches a
|
||||
final unchanged repeat;
|
||||
- unsupported distribution, Ubuntu release, and architecture facts fail
|
||||
before creating application state at isolated temporary paths.
|
||||
3. Inspect captured task output only where needed to distinguish a build from
|
||||
metadata or configuration convergence. Fail on hidden task failures or
|
||||
unexpected changes in idempotence runs.
|
||||
4. Limit test mutation to the three declared managed paths and the driver's
|
||||
private temporary directory.
|
||||
5. Add no tests for version interrogation, fingerprints, checksums, compiler
|
||||
changes, source dirt, staged failures, malformed host state, production
|
||||
configuration preflight, or other non-goals.
|
||||
6. Update the README test section to describe the focused suite and its host
|
||||
effects.
|
||||
|
||||
### Validation
|
||||
|
||||
From `ansible-role-audita`, run:
|
||||
|
||||
```sh
|
||||
tests/integration
|
||||
git diff --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
Then confirm the restored installation:
|
||||
|
||||
```sh
|
||||
sudo git -C /usr/local/src/audita rev-parse HEAD
|
||||
sudo stat -c '%U:%G %a' /usr/local/bin/audita
|
||||
sudo stat -c '%U:%G %a' /usr/local/etc/audita/config.yml
|
||||
/usr/local/bin/audita config validate --config /usr/local/etc/audita/config.yml
|
||||
```
|
||||
|
||||
Expected result: the focused suite and negative cases pass; the final repeat
|
||||
reports `changed=0` and `failed=0`; source is restored to
|
||||
`a84941d68168a1ed9ea7423b6477ae8218be73f9`; metadata is `root:root 755` for
|
||||
the binary and `root:root 644` for configuration; validation reports
|
||||
`config is valid`.
|
||||
|
||||
### Completion Criteria
|
||||
|
||||
- Every Feature 0002 acceptance criterion has direct static or test evidence.
|
||||
- Coverage remains limited to the selected operational contract.
|
||||
- Configuration-only convergence demonstrably does not rebuild Audita.
|
||||
- README, interface, tasks, and tests agree.
|
||||
- Default local state is restored and idempotent.
|
||||
- No repository outside `ansible-role-audita` changed.
|
||||
|
||||
### Commit
|
||||
|
||||
Commit message: `Add focused Audita integration coverage`
|
||||
|
||||
**Completion:** Complete (`ansible-role-audita` commit `d37f590`).
|
||||
|
||||
## Final Validation and Handoff
|
||||
|
||||
After Stage 2, run:
|
||||
|
||||
```sh
|
||||
tests/integration
|
||||
git log --oneline -2
|
||||
git status --short --branch
|
||||
cd ..
|
||||
./scripts/status
|
||||
```
|
||||
|
||||
Report the two commit hashes, final integration and repeat results, restored
|
||||
source commit, file metadata, native configuration-validation result, any
|
||||
deviation or remaining concern, and any complexity beyond this task flow with
|
||||
the acceptance criterion that required it.
|
||||
|
||||
Do not edit workspace planning files, mark Feature 0002 `done`, or push during
|
||||
out-of-band execution. Completion requires subsequent review.
|
||||
|
||||
## Progress Notes
|
||||
|
||||
- Plan approved and ready for out-of-band execution on 2026-09-08.
|
||||
Select and approve the next feature roadmap before replacing this notice with
|
||||
a new staged implementation plan.
|
||||
|
||||
Reference in New Issue
Block a user