WAF++ WAF++
Back to WAF++ Homepage

Governance & Contribution

WAF++ is an open community project. This page describes how decisions are made and how you can contribute concretely – whether as a control author, reviewer, or pillar maintainer.

Governance Model

WAF++ follows established open-source governance models (inspired by CNCF and OpenSSF).

Role Responsibility

Technical Steering Committee (TSC)

Technical direction, breaking changes, pillar structure, schema changes. Decisions by consensus, majority vote in case of disagreement.

Pillar Maintainer

Responsible for all controls and narrative pages of a pillar. Review and merge of control PRs. At least one maintainer per active pillar.

Contributor

Submits controls, corrections, narrative pages, or best practices via pull request. No formal onboarding process required.

User Advisory Group

Brings practical perspective from projects, operations, and audits. No merge rights, but veto option for controls with direct compliance implications.

All decisions are discussed and documented publicly on GitHub. There are no private decision channels.

Contributing – Quick Start

Prerequisites

  • Git and a GitHub account

  • Basic AsciiDoc knowledge (for narrative pages)

  • YAML knowledge (for controls)

  • Locally: Python 3.10+ and wafpass for control testing

First Steps

  1. Fork the repository on GitHub

  2. Create a branch – naming convention: feat/WAF-COST-110, fix/WAF-SOV-020-typo, docs/pillar-cost-glossary

  3. Make changes (see sections below)

  4. Test locally (for controls: wafpass check)

  5. Open a pull request with the issue as reference

Contributing a New Control

Controls are the core of the framework. A good control is:

  • Normative – says "MUST", not "should"

  • Testable – has at least one automated check (automated: true)

  • Justified – rationale explains the risk, not just the rule

  • Practical – example.compliant and example.non_compliant are real Terraform

Workflow

  1. Check on GitHub whether a similar control already exists or is being discussed (Issues / Discussions).

  2. Assign a control ID: next free number in the pillar (e.g. WAF-COST-110). Numbers are not reused.

  3. Create the YAML file according to Control Schema:

    # Storage location
modules/controls/controls/WAF-COST-110.yml

  4. Test checks locally against fixture Terraform:

    wafpass check ./tests/fixtures/ --controls WAF-COST-110 --verbose

  5. Create narrative page (English):

    # For Cost controls:
modules/pillar-cost/pages/controls/WAF-COST-110.adoc

# For Sovereign controls:
modules/pillar-sovereign/pages/controls/WAF-SOV-NNN.adoc

  6. Open pull request – title: feat: add WAF-COST-110 – [short title]

Checklist for Control PRs

  • YAML file created in modules/controls/controls/

  • All required fields filled (id, title, pillar, status, severity, category, description, rationale, checks)

  • At least one check with automated: true

  • example.compliant and example.non_compliant present

  • regulatory_mapping filled where applicable

  • Narrative page created and linked in references.narrative

  • wafpass check against fixture runs without errors

  • Maturity levels (all 5) filled

Contributing Narrative Pages

Narrative pages are the human-readable explanation behind the controls. They are written in English (AsciiDoc).

Storage Locations

Page type Path

Control detail page

modules/pillar-{NAME}/pages/controls/WAF-{PILLAR}-{NNN}.adoc

Best practice

modules/pillar-{NAME}/pages/best-practices/bp-{slug}.adoc

Case study

modules/pillar-{NAME}/pages/case-studies/case-{slug}.adoc

Pillar main pages (definition, scope, etc.)

modules/pillar-{NAME}/pages/{name}.adoc

Conventions

  • Language: English

  • Page attributes: always set = Title and :description:

  • Cross-references: always as Antora xrefs (xref:module:page.adoc[Text]), no relative paths

  • Code examples: always with [source,lang] and ---- blocks

  • Tables: [cols=…​, options="header"] for consistent rendering

Issues and Discussions

Channel Usage

GitHub Issues

Concrete bugs, incorrect controls, broken links, wrong assertions. Please include the control ID in the title.

GitHub Discussions

Conceptual discussions, new pillar ideas, feedback on maturity levels, questions about usage

Pull Requests

All code and documentation changes. Every PR should reference an issue.

Issue Template for New Controls

## Control Proposal: WAF-\{PILLAR}-\{NNN}

**Pillar:** Cost / Sovereign / Security / ...
**Severity:** critical / high / medium / low
**Category:** (e.g. tagging, egress, encryption)

### Problem / Risk
[Which risk is currently not covered by existing controls?]

### Proposed Requirement
[What should the control require? Normative formulation: "All resources MUST ..."]

### Automated Check Possible?
[ ] Yes – via Terraform assertions
[ ] No – manual review required

### Regulatory Relevance
[GDPR / BSI C5 / ISO 27001 / FinOps / none]

RFC Process (Schema Changes)

Changes to the control schema or pillar structures that constitute breaking changes go through an RFC process:

  1. Open an RFC issue with label rfc – description of the change and justification

  2. Comment period – open for at least 14 days for community feedback

  3. TSC decision – documented in the issue comment

  4. Implementation – in branch rfc/NNN-description, then PR against main

Breaking changes always receive a migration note in the changelog page.

Versioning and Releases

WAF++ uses semantic versioning (MAJOR.MINOR.PATCH):

Version type Trigger

MAJOR

Incompatible schema changes, pillar restructuring, control IDs retired

MINOR

New controls, new narrative pages, new best practices

PATCH

Corrections to assertions, typos, and wording fixes, link fixes

Releases are published as GitHub Releases with changelog. Control IDs are stable across minor versions – an assigned ID is never reused.

Further Reading