295 lines
12 KiB
Markdown
295 lines
12 KiB
Markdown
# Implementation Plan 0002: Install and Configure Audita
|
|
|
|
Status: ready
|
|
|
|
Target executor: GPT-5.6-Terra
|
|
|
|
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`
|
|
|
|
## 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`
|
|
|
|
## 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.
|