sjat/boma

sjat f338bccd46 Expand ADR-002 into a security baseline + strategy

Add a managerial security frame on top of the host baseline: explicit threat
model (opportunistic external, lateral movement/blast radius, operator/agent
error; supply chain accepted-lower-priority), security principles, and four
governance mechanisms that ADR-002 establishes and links out to:

- docs/security/service-checklist.md — per-service security bar (referenced
  from the new-role runbook)
- docs/security/accepted-risks.md — living accepted-risk register (R1-R4)
- planned /security-review skill (TODO 8.5)
- agent guardrails in CLAUDE.md "what Claude must not do"

STATUS.md records the frame as present (manual enforcement) and /security-review
as planned-not-built.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-04 14:39:51 +02:00

2.5 KiB

Raw Blame History

Runbook — Adding a new Ansible role

When to create a new role

Create a new role when you need to manage a distinct, reusable unit of configuration — a service, a system component, or a behaviour applied to a group of hosts.

Do not create a role for a single task that logically belongs in an existing role.

Procedure

1. Scaffold the role

make new-role NAME=<rolename>

This creates the full directory structure and placeholder files under roles/<rolename>/.

2. Fill in meta/main.yml

galaxy_info:
  role_name: <rolename>
  author: <your name>
  description: <one sentence>
  min_ansible_version: "2.15"
  platforms:
    - name: Debian
      versions:
        - trixie  # Debian 13

3. Define defaults

Add all tuneable variables to defaults/main.yml with inline comments explaining each variable. Use the rolename__varname namespace convention.

4. Write tasks

Use FQCN for all modules
Every task must have a name: that reads as a sentence
Every task must have at least one tags: entry
Notify handlers by listen: topic string, not handler name

5. Configure Molecule

Edit molecule/default/molecule.yml to use the Debian 13 test image. Write a converge.yml that applies the role. Write a verify.yml that asserts the expected state.

6. Write the README

Document:

Purpose of the role (one paragraph)
All variables from defaults/main.yml with types, defaults, and descriptions
Example playbook usage
Any dependencies or prerequisites

7. Test locally

make test ROLE=<rolename>

Fix any lint or test failures before committing.

8. Add to a playbook

Add the role to the appropriate playbook in playbooks/ and add the host group to inventories/staging/hosts.yml for integration testing.

9. Clear the security checklist (services)

If the role is a service — especially one reachable beyond its own host — walk docs/security/service-checklist.md and confirm every item passes (secrets in vault, no default creds, least-privilege, declared firewall ports, behind the reverse proxy with auth if exposed). Record any conscious deviation in docs/security/accepted-risks.md. This bar is established by ADR-002; enforcement is manual in review today, with the planned /security-review to automate it.

10. Commit

git checkout -b role/<rolename>
git add roles/<rolename>
git commit -m "Add <rolename> role"
# merge to main once make test passes, then delete the branch

2.5 KiB Raw Blame History