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:
Create
src/rules/cert_c/CATEGORY/RULE-ID/with the implementation (rule_id_c.rs) and the rule’sRULE-ID.toml. Copy a small existing rule as the template:src/rules/cert_c/MSC/MSC33-C/implements theCertRuletrait (src/rules/mod.rs) in one short file. The build merges eachRULE-ID.tomlintorules_templates/rules-all.toml, so do not edit that file by hand.Register the rule in
src/rules/cert_c/mod.rs.Add test cases as
.cfiles intests/fail/andtests/pass/(andtests/expected_fail/for a known miss) beside the rule. The build generates a test from each file; do not add inline tests.Add a block for the rule to every
conf/realworld/*-rules.toml. Thecheck-realworld-manifestshook refuses a commit without one.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:
Check that the covering rule already reports the construct (Decision 5): run it on the removed rule’s
failfixtures and CERT’s noncompliant examples. If it doesn’t, the removal waits for that coverage to land.Delete the rule directory
src/rules/cert_c/CATEGORY/RULE-ID/(the implementation, its.tomland itstests/fixtures) and its registration insrc/rules/cert_c/mod.rs.Delete its block from every
conf/realworld/*-rules.toml. The build regeneratesrules_templates/rules-all.tomlwithout it.Add a
[[removed]]entry torules_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_inis the release the removal ships in, set up front;disposition,covered_byand (for a check moved to the CWE ruleset)moved_tomust agree with the rule’s disposition row, and everycovered_byrule must still ship (a test checks it against the registry).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 thecheck-project-factshook reports as stale (README.md and docs/ claim the shipped and enabled totals).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; thecheck-removed-ruleshook requires it to start with that label (and to name everycovered_byrule, and themoved_toCWE). Also update any design doc or ADR that cites the rule as live (for exampledocs/design/cross-rule-overlap.md).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).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:
There is no covering rule to check: the moved rule reports the construct itself.
Move the rule directory with
git mvtosrc/rules/cwe/CWE-<n>/(flat: no category level), renaming the.rsfile and the.tomlto 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]typetoweakness, and change each fixture’sRule:header. Move the registration fromsrc/rules/cert_c/mod.rstosrc/rules/cwe/mod.rsand theregistercall beside the other CWE rules. Keep[references] cweas it was: it names the Juliet directories the check is scored on, which the move does not change.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.tomlis regenerated by the build.The
[[removed]]entry takesdisposition = "moved-to-cwe"andmoved_to = "CWE-<n>", which must be a rule the tool ships, and nocovered_by.A suppression comment or
--rulesnaming the old id still parses, with a warning, but no longer matches. The release note says so: it is aremovednote for the CERT id and anaddednote for the CWE id.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.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-versionin Cargo.toml)C toolchain: a C compiler and linker for dependencies with native code (e.g.
libgit2-sys);build-essentialon Debian/UbuntuPlatform: Linux, macOS, Windows (cross-platform via crossterm)
Dependencies: See
Cargo.tomlfor the full listNo unsafe code: the library and the binary deny it (
#![deny(unsafe_code)]). The one exception isast_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:
Confirm
https://brandon-arrendondo.github.io/aurora-lint/<tag>/index.htmlis live and listed onversions.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.Never re-run a docs job from a run made before per-tag publishing existed, and never push to the
gh-pagesbranch by hand. Either one publishes a site without the release directories. If that happens, restore them from an earliergh-pagescommit.
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.