Contributing

Adding a New CERT C Rule

The full checklist, and the policy a new rule must follow, are in the “Build & Test” and “Rule Implementation” sections of the technical guide. In short:

  1. Create src/rules/cert_c/CATEGORY/RULE-ID/ with the implementation (rule_id_c.rs) and the rule’s RULE-ID.toml. Copy a small existing rule as the template: src/rules/cert_c/MSC/MSC33-C/ implements the CertRule trait (src/rules/mod.rs) in one short file. The build merges each RULE-ID.toml into rules_templates/rules-all.toml, so do not edit that file by hand.

  2. Register the rule in src/rules/cert_c/mod.rs.

  3. Add test cases as .c files in tests/fail/ and tests/pass/ (and tests/expected_fail/ for a known miss) beside the rule. The build generates a test from each file; do not add inline tests.

  4. Add a block for the rule to every conf/realworld/*-rules.toml. The check-realworld-manifests hook refuses a commit without one.

  5. Build and run the rule’s tests. The filter is the rule id in lower case, with _ for - (here for MSC33-C):

    cargo build
    cargo test --lib -- msc33_c
    cargo fmt
    

Removing a Rule

A rule is removed only on its row in docs/design/rule-disposition.md (ADR-0013): a not-shipped disposition, ruled. Each removal is its own change (Decision 5), and “not shipped” means gone from the tool, not disabled (Decision 4). In that one change:

  1. Check that the covering rule already reports the construct (Decision 5): run it on the removed rule’s fail fixtures and CERT’s noncompliant examples. If it doesn’t, the removal waits for that coverage to land.

  2. Delete the rule directory src/rules/cert_c/CATEGORY/RULE-ID/ (the implementation, its .toml and its tests/ fixtures) and its registration in src/rules/cert_c/mod.rs.

  3. Delete its block from every conf/realworld/*-rules.toml. The build regenerates rules_templates/rules-all.toml without it.

  4. Add a [[removed]] entry to rules_templates/removed-rules.toml, in id order (the loader refuses an unsorted table, so parallel removals don’t all conflict at the end of the file). removed_in is the release the removal ships in, set up front; disposition, covered_by and (for a check moved to the CWE ruleset) moved_to must agree with the rule’s disposition row, and every covered_by rule must still ship (a test checks it against the registry).

  5. Regenerate what is derived from the rule set:

    python3 scripts/generate_rule_cwe_map.py   # data/rule_cwe_map.json
    python3 scripts/render_removed_rules.py    # README.md and docs/configuration.rst
    

    Delete the rule’s key from data/wiki_fixture_staleness.json (its fixtures are gone; don’t rerun that audit, which fetches CERT’s wiki), and fix every rule count the check-project-facts hook reports as stale (README.md and docs/ claim the shipped and enabled totals).

  6. Record the removal in the rule’s row in docs/design/rule-disposition.md: note it, with the release, in the Reason / notes column. Leave the Disposition column as the not-shipped disposition the removal rests on; the check-removed-rules hook requires it to start with that label (and to name every covered_by rule, and the moved_to CWE). Also update any design doc or ADR that cites the rule as live (for example docs/design/cross-rule-overlap.md).

  7. Say in the change’s description what users lose and which rules report the construct instead. The maintainer records it as the release note, under category: removed (ADR-0009).

  8. Build and run the full test suite. The pre-commit hooks check that every real-world manifest still decides every rule (check-realworld-manifests), that the not-shipped list is current and agrees with the disposition table (check-removed-rules), and that the rule counts hold (check-project-facts).

Moving a Check to the CWE Ruleset

A rule whose disposition is moved to CWE ruleset keeps its check and changes its id: it is shipped from src/rules/cwe/ as CWE-<n>, enabled by default as before, and the CERT id is recorded as removed. The removal steps above apply, with these differences:

  1. There is no covering rule to check: the moved rule reports the construct itself.

  2. Move the rule directory with git mv to src/rules/cwe/CWE-<n>/ (flat: no category level), renaming the .rs file and the .toml to match, rather than deleting it. Change the rule id, the struct name and the [rules.cert_c.<ID>] table to [rules.cwe.CWE-<n>], set the [metadata] type to weakness, and change each fixture’s Rule: header. Move the registration from src/rules/cert_c/mod.rs to src/rules/cwe/mod.rs and the register call beside the other CWE rules. Keep [references] cwe as it was: it names the Juliet directories the check is scored on, which the move does not change.

  3. In every conf/realworld/*-rules.toml, move the rule’s block to the CWE ruleset section at the end of the file as [rules.cwe.CWE-<n>], keeping that codebase’s decision and its comment. Coverage on the real-world suite must not change. rules_templates/rules-all.toml is regenerated by the build.

  4. The [[removed]] entry takes disposition = "moved-to-cwe" and moved_to = "CWE-<n>", which must be a rule the tool ships, and no covered_by.

  5. A suppression comment or --rules naming the old id still parses, with a warning, but no longer matches. The release note says so: it is a removed note for the CERT id and an added note for the CWE id.

  6. Ground-truth labels are keyed on the rule id, so the old id’s labels stop matching anything. Count them per id and re-key them through benchmark_adjudication (ADR-0007), rather than letting them drop out of the oracle silently.

  7. Check with a before/after scan of the real-world corpora: the findings must be the same in everything except the rule id.

Build Requirements

  • Rust: 1.95 or later (stable toolchain; rust-version in Cargo.toml)

  • C toolchain: a C compiler and linker for dependencies with native code (e.g. libgit2-sys); build-essential on Debian/Ubuntu

  • Platform: Linux, macOS, Windows (cross-platform via crossterm)

  • Dependencies: See Cargo.toml for the full list

  • No unsafe code: the library and the binary deny it (#![deny(unsafe_code)]). The one exception is ast_utils::tree_root, which asks tree-sitter for a node’s root in constant time; its doc comment says why.

cargo build             # Debug build
cargo build --release   # Release build (optimized)
cargo test              # Run all tests
cargo fmt               # Format code

Which Tests a Change Needs

scripts/landing_check.py reads a diff and prints the suites that change needs; --run runs them. It diffs HEAD against its merge base with main unless given --base/--head:

scripts/landing_check.py          # class, per-file reasons, commands
scripts/landing_check.py --run

A change that touches only prose needs no Rust build (Sphinx -W runs when docs/ changed). A change to Python under bench/ or scripts/ runs those unit tests. A .rs change that is comments only runs the build, doctests and clippy. A rule manifest change that touches only its text fields (title, description, wiki link) runs everything except the generated fixture tests. Anything else, including anything the script cannot classify, runs the full suite. The script’s docstring lists the exact rules, such as why a prose file that a test reads counts as code. The git hooks run on every commit regardless.

When --run passes, it prints a verified: line naming the git tree it tested (git rev-parse HEAD^{tree}), the class, the host and the rustc version. The tree hash identifies content, whichever commit carries it. Only a class full line vouches for a tree on its own: a tree with the same hash, under the same rustc, has already passed the whole suite. A lesser class ran less, so its line holds only together with a passing run on the base it was classified against. Uncommitted or untracked files (an unadded fixture changes the generated tests) mark the line as verifying nothing.

The timings the script was tuned against are for a 4-core, 7 GB machine building with -j2, and CI also runs everything again with --features tui.

CI uses the same script: on a pull request that touches only prose or Python outside the crate, the Rust jobs are skipped. The classifier that grades a pull request is the base commit’s copy, and a pull request that changes the classifier or .github/ runs everything. A push to main always runs everything. One check rides on the skipped test job: check_project_facts.py --generated, which checks the test summary that cargo test writes. A Python-only pull request therefore reaches it only on the push to main.

Invoke Tasks

tasks.py holds a few developer tasks, run with invoke (pip install invoke):

invoke check            # Run pre-commit hooks on all files
invoke build            # Build (add --release for release mode)
invoke test             # Run all tests
invoke bump-version     # Bump version across all files (reads Cargo.toml)
invoke lint-docs        # Advisory prose lint of README.md, docs/*.rst, man page

invoke lint-docs runs Vale with the Aurora house style (American spelling, settled terms such as “pre-scan”, no contractions, and a flag on patterns typical of machine-written prose). The style is a Vale package in a sibling ../style_package checkout, named in .vale.ini; the task builds its zip there when missing and reruns vale sync when .vale.ini or the zip changes. A checkout without ../style_package cannot run it, and nothing else depends on it.

By default it lints the user-facing docs: README.md, this guide (docs/*.rst) and the man page, which pandoc first converts to Markdown under target/vale/ (findings name that file). Pass --path for any other tracked .md or .rst file or directory, such as the internal design docs, and --level suggestion to see suggestion-level rules too:

invoke lint-docs --path docs/cli-usage.rst
invoke lint-docs --path docs/design

The lint is advisory: findings never fail the task, and it is not part of pre-commit or CI. Reading .rst needs docutils’ rst2html on PATH; the development venv below has it (Sphinx depends on docutils). Without it the task skips .rst files and says so. Rule changes belong in style_package, not in a local override here.

Publishing a Release’s Documentation

Pushing a v* tag runs .github/workflows/release.yml, whose docs job publishes that commit’s rendered documentation under /<tag>/ on the GitHub Pages site. The directory is never replaced: a later deploy of the same tag is refused, and every deploy from main copies each release directory forward unchanged. After tagging a release:

  1. Confirm https://brandon-arrendondo.github.io/aurora-lint/<tag>/index.html is live and listed on versions.html. The tag’s docs job waits in the same queue as main’s, and a newer push to main can cancel it while it waits. If it did, re-run that job from the tag’s release run. Main’s docs job also warns about any release whose directory is missing.

  2. Never re-run a docs job from a run made before per-tag publishing existed, and never push to the gh-pages branch by hand. Either one publishes a site without the release directories. If that happens, restore them from an earlier gh-pages commit.

Development Node Setup

To provision a fresh Ubuntu 24.04 node for working on aurora-lint (as opposed to just running benchmarks – see Benchmark Setup for that), install Ansible first (sudo apt install -y ansible or pipx install ansible-core – a playbook can’t provision the tool it runs under), then run:

ansible-playbook playbooks/setup-dev-environment.yml -i "localhost," -c local \
  --ask-become-pass

This installs the Rust toolchain (rustup, picking up the channel and components pinned in rust-toolchain.toml), the native build dependencies git2’s vendored libgit2 build needs (a C toolchain, cmake, pkg-config), and – into a venv at ~/.venvs/aurora-lint-dev by default – the Sphinx + LaTeX toolchain this guide itself is built with, invoke (for the invoke bump-version workflow), pre-commit (installed as this checkout’s git hook – see the Git Commit Rules in AGENTS.md), and clew-trace (the package behind the clew-mcp command .mcp.json points at – see CLAUDE.md’s “Code Navigation (clew)” for registering the MCP server itself with clew init, a separate, per-machine step this playbook does not run for you). Point the venv at an existing/shared one instead with -e dev_venv=<path>, e.g. -e dev_venv=~/venvs/shared.

It also installs and schedules a disk-guard cron (cargo-sweep + scripts/cargo-target-gc.sh, hourly) that caps target/ growth – skip it on a node with plenty of headroom with -e install_disk_guard=false. The script runs on macOS too (no flock there; it skips that one check), so a Mac node can take the same crontab line by hand, listing each worktree it builds in. This exists because two otherwise identically-provisioned dev nodes were found to have diverged on exactly this (2026-08-31): one had the cron, one didn’t, and the one without it had an unbounded target/ and a manually-patched Cargo.toml disabling dependency debug info as an ad hoc workaround.

It does not install comparison tools – cppcheck and clang-tidy (apt packages, see Benchmark Setup) or Infer/Frama-C (playbooks/install-static-analyzers.yml) – clone the real-world benchmark checkouts or the Juliet test suite (also Benchmark Setup – a node that only needs the benchmark code as reference, not to run benchmarks, can skip both and just copy an existing node’s $SQC_BENCH_ROOT directory over), or install editor/terminal conveniences (vim, htop, tmux). A node doing rule-development work that compares aurora-lint’s output against these tools’ still needs install-static-analyzers.yml run separately – none of that is a dependency of building or testing aurora-lint itself, which is this playbook’s only scope.

Nor does it fetch the reference shadow set (the never-labeled codebases a change can be A/B’d over; see Benchmark Setup) unless asked: it downloads third-party code that only that A/B uses. Opt in once with -e install_shadow_corpus=true (and -e shadow_tier=all for every tier), or run playbooks/setup-shadow-corpus.yml on its own.