Skip to content
Bugb Docs

cxgGuides

Contribute a template

You have a check that works, and it would have been useful to someone else. This is the route from that to a merged template in cert-x-gen-templates, and what the repository will ask of it on the way.

If you do not have the check yet, write your first template builds one from nothing. If you are not sure yours is new, the template catalog is where it would land: browse it by category, or by the weakness class you are aiming at.

What the repository is looking for

Section titled “What the repository is looking for”

The opening line of the contribution guide is the whole standard: a template is a program that decides, not a pattern that matches. It runs against a target, observes something specific, and returns a verdict it can defend.

Four properties carry most of that, and they are where review spends its time.

A specific oracle. The check fires on a structural conjunction, an observed secret, or a marker it planted itself. It does not fire on a string, a status code, or a banner that turns up in ordinary responses. The question review asks is not “does this find the issue” but “what else does this find”.

An honest skip. A check that cannot say “the surface I audit is not present here” is asserting that surface rather than establishing it. Without that branch, a target the template never managed to examine is reported exactly like a target it examined and cleared. A match is not a finding works through why that distinction is the load-bearing one.

Proof in both directions. A detection that has only been run against a vulnerable target has not been tested. The repository wants a synthetic fixture whose flawed and fixed twins are built from one source, and every verdict the template can emit needs a fixture that produces it, the skip included.

No collateral traffic. A scan touches the target and nothing else. No callback hosts, no public resolvers, no third-party services. Nothing that disrupts the service being audited.

The full list, including what gets a template rejected, is under What makes a good template.

The path

Section titled “The path”

  1. Propose it before you polish it.

    Open a template proposal. It asks for the weakness class, the target, the oracle, and the conditions under which the check confirms, refutes, or skips.

    You do not need working code to open one. Those four answers are what the template’s own header and its proof harness will have to satisfy anyway, and agreeing them first is considerably cheaper than rewriting a finished template after review.

  2. Fork, clone, and branch.

    Terminal window
    git clone https://github.com/YOUR_USERNAME/cert-x-gen-templates.git
    cd cert-x-gen-templates
    git remote add upstream https://github.com/Bugb-Technologies/cert-x-gen-templates.git
    git checkout -b template/your-check-id

  3. Put the file where it belongs.

    templates/<category>/<subject>/, one self-contained file, named for its template id. The id is lowercase and hyphenated, shaped subject-weakness, and it has to be unique across the whole repository: a duplicate id is not a warning, because the engine keeps one template per id and silently drops the rest, which stops both of them running.

    A template is one file. Where an oracle is genuinely shared between checks it is duplicated rather than imported, and a test pins the copies together.

  4. Build the fixture and prove it both ways.

    The fixture goes in fixtures/<template-id>/ with a prove.sh that asserts the flawed twin confirms and the fixed twin refutes. Prefer independent switches over a single flawed-or-fixed axis, so one source can reach every branch including the skip.

    The behavioural harnesses take minutes and are deliberately not part of CI. Run yours by hand before you push, because nothing downstream will.

  5. Write the playbook.

    A differentiated check ships a human-facing document at docs/playbooks/<template-id>.md: the case for the check, a mermaid diagram of the probe flow ending at the verdict, and why observing the behaviour beats reading the configuration. Describe and link the template rather than pasting it.

    That file is published here as well: Playbooks is every one of them, and reading two or three is the fastest way to see what the document is expected to argue.

    No CI check covers that directory, so validate the mermaid before pushing. GitHub renders it natively and a parse error simply shows the source.

  6. Run the checks locally.

    Your own template first:

    Terminal window
    cxg template validate session-token-predictable.py
    ════════════════════════════════════════════════════════════════════════════════
    CERT-X-GEN Template Validator
    ════════════════════════════════════════════════════════════════════════════════
    

    Found 1 template(s) to validate
    

    ✓ session-token-predictable.py
    

    ════════════════════════════════════════════════════════════════════════════════
    Validation Summary
    ════════════════════════════════════════════════════════════════════════════════
    

      Total Templates: 1
      ✓ Passed: 1
      ✗ Failed: 0
      Success Rate: 100%

    Then the repository’s own checks, which are the ones CI runs: the engine loader, the registry generator, its guard tests, and hygiene. The five CI checks gives each command and what it rejects.

  7. Open the pull request.

    .github/PULL_REQUEST_TEMPLATE.md fills in a checklist mirroring what CI enforces. Work through it rather than deleting it.

    One thing catches nearly everybody: do not commit TEMPLATE_REGISTRY.json or templates/TEMPLATE_REGISTRY.md. The JSON registry is regenerated on main after every merge, and CI fails a pull request that edits either file. Running the generator locally is a check, not something to commit.

What happens then

Section titled “What happens then”

Automated checks run first and all of them have to be green. Then a maintainer reviews the things a machine cannot: how precise the oracle is, what the false-positive surface looks like, whether the fixture really produces every verdict, and whether the check duplicates one that already exists. Other contributors may comment as well.

Contributors are listed in CONTRIBUTORS.md and named in release notes.

Where other things go

Section titled “Where other things go”
You have Send it to
A bug in a template A bug report naming the template, the target, and the verdict you expected
A bug in the engine: crashes, flags, output formats The engine repository
An idea for repository tooling, CI, or docs A feature request
A security vulnerability security@bugb.io, never the issue tracker. See SECURITY.md
A question GitHub Discussions

Documentation fixes are held to the same review bar as templates and are just as welcome.

Section titled “Related”