bmc-sensor-audit 0.1.0__tar.gz

bmc_sensor_audit-0.1.0/.githooks/commit-msg

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Check the commit message before it becomes permanent.
+#
+# Activated by the same setting as the pre-commit hook:
+#     git config core.hooksPath .githooks
+#
+# A message is the one published surface that can never be corrected. The hygiene
+# check guards files and cannot see the message; this runs the same rules over it.
+#
+# To commit past it knowingly:   git commit --no-verify
+# Note that --no-verify also disables the pre-commit hygiene sweep. That is why
+# this hook refuses only on objective problems and merely notes the heuristic one.
+exec python3 "$(git rev-parse --show-toplevel)/tools/commit_msg_check.py" "$1"

bmc_sensor_audit-0.1.0/.githooks/pre-commit

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Refuse a commit carrying something that should not be published, and one whose
+# README no longer describes the suite.
+#
+# Activate once per clone:   git config core.hooksPath .githooks
+#
+# Versioned deliberately. A hook that lives only in .git/hooks exists on one
+# machine, is invisible in review, and is absent from every fresh clone -- which
+# for a repository authored in public means the safety check is missing exactly
+# when a new contributor needs it most.
+#
+# To commit past it knowingly:   git commit --no-verify
+# That is a real escape hatch and it should be rare enough to notice.
+set -e
+ROOT="$(git rev-parse --show-toplevel)"
+
+python3 "$ROOT/tools/hygiene_check.py"
+
+# The README's test count, checked where the drift is created rather than where it
+# is discovered. Dependency-free and about 0.2s.
+#
+# The count it checks is taken from what git TRACKS, not from what the directory
+# holds, and that is the whole reason it can run here at all. The published 289 was
+# measured on a working tree carrying a test file that was never committed: true of
+# that disk, false of this repository. A disk-derived count would make this hook
+# red on any tree with an untracked test in it -- red every run, for a reason that
+# is not a defect, which is how a check teaches people to pass --no-verify. That
+# flag also switches off the hygiene sweep above, so a check nobody can satisfy
+# costs more than the one it was added to provide.
+#
+# A missing pytest fails rather than skips. A gate that converts its own red into a
+# skip removes the failure and the evidence together.
+if ! python3 -c "import pytest" 2>/dev/null; then
+    echo "pre-commit: pytest is not installed, so the README count check cannot run." >&2
+    echo "            python3 -m pip install pytest    (or commit with --no-verify)" >&2
+    exit 1
+fi
+
+exec python3 -m pytest \
+    "$ROOT/tests/test_readme_commands.py::TestTheReadmeTestCount" \
+    -q -p no:cacheprovider

bmc_sensor_audit-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: A gate that said clean over something it did not audit is the report this project wants most
+---
+
+## What happened
+<!-- one sentence -->
+
+## What you expected
+
+## The configuration
+<!-- the smallest config that shows it, or the name of the vendored one -->
+
+## The walk
+<!-- the capture file, or how the target was reached -->
+
+## The report and the exit code
+<!-- full text, and `echo $?` immediately after -->
+
+## Environment
+<!-- Python; and if [detect] is involved: `pip show arbiter-engine` — presence
+     and correctness are different checks -->
+
+## Where you stopped looking
+<!-- Optional, and genuinely useful. "I did not audit X" is read here as a lead,
+     not a disclaimer -- the largest finding in this repository so far came from
+     the half of a report its author left open. -->

bmc_sensor_audit-0.1.0/.github/workflows/canary.yml

@@ -0,0 +1,155 @@
+# Does the engine still behave the way Stage 2 assumes?
+#
+# `pyproject.toml` declares `arbiter-engine>=0.1.6,<0.2`. That is a RANGE, and upstream
+# shipped five releases in forty-eight hours. Everything Stage 2 depends on -- four
+# behavioural pillars and two payload locations -- can therefore change without this
+# repository changing at all, and without anybody choosing it.
+#
+# So this installs the range rather than a pin, deliberately: the job exists to find out
+# when a permitted release moves something. It resolves and prints the version first, so
+# a red run names the release that caused it instead of leaving that to be guessed.
+#
+# It is scheduled, because upstream releases do not correlate with our pushes -- but a
+# schedule-only workflow in a sibling project accumulated zero runs across fifteen
+# pushes, so it ALSO fires when the bridge or the dependency declaration changes. A
+# canary nobody has ever seen sing is not a canary.
+
+name: engine canary
+
+on:
+  schedule:
+    - cron: "23 5 * * *"
+  workflow_dispatch:
+  push:
+    paths:
+      - "tests/test_engine_bridge.py"
+      - "pyproject.toml"
+      - "docs/stage2/**"
+      - ".github/workflows/canary.yml"
+
+jobs:
+  canary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install the engine from the declared range
+        # Not a pinned version. The range is what a consumer actually gets, so the
+        # range is what gets tested.
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet "arbiter-engine>=0.1.6,<0.2" pytest
+          echo "resolved:"
+          python3 -m pip show arbiter-engine | sed -n 's/^Version: /  arbiter-engine /p'
+
+      - name: Four pillars and two payload locations
+        run: PYTHONPATH=src python3 -m pytest tests/test_engine_bridge.py -q
+
+      - name: Release test -- generator, feeder and bridge on the pinned floor
+        # The composed check: the model generator, the feeder and gate, and the
+        # end-to-end bridge, all against the engine the range resolves to. Run
+        # together because they only mean anything together -- a generator whose
+        # output the engine half-ignores passes its own golden tests.
+        run: |
+          PYTHONPATH=src python3 -m pytest \
+            tests/test_generator.py tests/test_feeder.py tests/test_engine_bridge.py -q
+
+      - name: Per-run attestation, and a check that it says something
+        # `attest` records what was checked, what was DECLINED, and the measurement
+        # behind each finding. The module has existed since it was written; nothing
+        # produced one on a schedule, so there was no artifact for anyone to read and
+        # no history to compare a later run against.
+        #
+        # Run over the vendored declaration and the vendored capture, so it needs no
+        # hardware and no network and produces the same answer for anyone who clones.
+        #
+        # The exit code is deliberately NOT the gate here: this run finds real
+        # regressions in the QEMU capture and exits 1 every time, which is the
+        # correct answer to the question `detect` was asked. What is being checked is
+        # that the ARTIFACT is worth keeping.
+        run: |
+          set -euo pipefail
+          set +e
+          PYTHONPATH=src python3 -m bmc_sensor_audit.cli detect \
+            --config tests/fixtures/upstream/meta/bletchley \
+            --walk tests/fixtures/walk_qemu_bletchley.json \
+            --attest-out attestation.json > /dev/null
+          DETECT_STATUS=$?
+          set -e
+          echo "  detect exited ${DETECT_STATUS} (1 is expected: the capture carries real findings)"
+
+          # An empty or shapeless artifact uploads exactly as well as a good one, and
+          # nobody opens it until the day they need it. So it is inspected here --
+          # by the SHIPPED validator, not by a copy of the rules living in this file.
+          # A rule that exists only inside a `run:` block cannot be called by the
+          # person who receives the artifact, which is the one person who needs it.
+          PYTHONPATH=src python3 -m bmc_sensor_audit.cli validate-attestation attestation.json
+
+          # Separate on purpose. The validator checks the FORMAT, and a genuinely
+          # clean board legitimately produces an artifact with no findings -- so
+          # `findings is non-empty` must never be a format rule or a clean run would
+          # fail validation. What follows is an expectation about THIS FIXTURE: the
+          # vendored capture has always carried real findings and real declines, and
+          # if it stops, the pipeline broke rather than the board healed.
+          python3 - <<'FIXTURE'
+          import json, sys
+          a = json.load(open("attestation.json"))
+          if not a["findings"]:
+              sys.exit("the vendored capture produced no findings; it always has, so "
+                       "the pipeline stopped feeding the engine")
+          if not a["not_checked"]:
+              sys.exit("the vendored capture produced no declines; every run so far "
+                       "has warmed up on a single walk")
+          print(f"  fixture expectations hold: {len(a['findings'])} finding(s), "
+                f"{len(a['not_checked'])} declined")
+          FIXTURE
+
+      - name: Keep it, so a later run has something to compare against
+        uses: actions/upload-artifact@v4
+        with:
+          name: attestation-${{ github.run_number }}
+          path: attestation.json
+          # The schedule is daily, so this is roughly three months of drift history.
+          retention-days: 90
+
+      - name: Stage 1 stays dependency-free
+        # The engine is an optional extra. If Stage 1 ever acquires a hard dependency
+        # on it, that is a design regression and it should fail here rather than be
+        # discovered by someone on a bring-up bench with nothing provisioned.
+        #
+        # This step asserts an EXIT CODE, and the reason is worth writing down. With
+        # the engine uninstalled the bridge module skips at import, so pytest collects
+        # nothing and exits 5 -- EXIT_NOTESTSCOLLECTED. The previous version piped that
+        # into `tail` under `set -o pipefail`, which failed the step on every run this
+        # workflow has ever had, while the property it checks was true the whole time.
+        # A red for the mechanism rather than the outcome, and one that ran for weeks
+        # because nobody reads a job that has never been green.
+        #
+        # 5 is REQUIRED, not merely tolerated. Exit 0 would mean the bridge tests ran,
+        # which would mean the uninstall did not take and this step proved nothing.
+        # That vacuous pass is the failure mode worth guarding against here, because
+        # it is indistinguishable from success at a glance.
+        run: |
+          set -euo pipefail
+          python3 -m pip uninstall --quiet --yes arbiter-engine
+          PYTHONPATH=src python3 -c "import bmc_sensor_audit.cli; print('  Stage 1 imports with no engine present')"
+
+          set +e
+          OUTPUT=$(PYTHONPATH=src python3 -m pytest tests/test_engine_bridge.py -q -rs 2>&1)
+          STATUS=$?
+          set -e
+          echo "$OUTPUT" | tail -3
+
+          if [ "$STATUS" -ne 5 ]; then
+            echo "expected pytest to collect nothing (exit 5, engine absent); got $STATUS" >&2
+            exit 1
+          fi
+          echo "$OUTPUT" | grep -q "arbiter-engine is the optional" || {
+            echo "the bridge module skipped for a reason other than the missing engine" >&2
+            exit 1
+          }
+          echo "  bridge tests skipped for the right reason, and nothing ran"

bmc_sensor_audit-0.1.0/.github/workflows/checks.yml

@@ -0,0 +1,137 @@
+# The gate that does not depend on anybody's local configuration.
+#
+# The pre-commit hook cannot enable itself. Git refuses to let a repository set
+# its own `core.hooksPath`, and that refusal is correct -- a repo that could
+# would be arbitrary code execution on clone. So the hook is opt-in per clone by
+# design, and it was unset in the authoring clone for the first three commits:
+# the only check this repository had never ran on any of them.
+#
+# This workflow is the answer to that. It runs on the server, on every push and
+# every pull request, and no local setting can switch it off.
+#
+# Deliberately NOT schedule-only. A sibling project has a scheduled workflow that
+# accumulated zero runs across fifteen pushes -- a gate nobody disabled and
+# nobody exercised. On push is what makes a check real.
+
+name: checks
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history: the commit-message step needs the commits in this push,
+          # and the default depth of 1 would leave it checking only the tip.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Hygiene sweep
+        # The same check the hook runs, over the whole tree rather than the
+        # staged diff. This is the backstop for every commit made from a clone
+        # where the hook was never enabled.
+        run: python3 tools/hygiene_check.py --all
+
+      - name: Commit messages
+        # The second hook's backstop. `commit-msg` can be forgotten exactly as
+        # `pre-commit` was -- both hang off one `core.hooksPath` that was unset
+        # here for three commits -- and a message is the one surface no later
+        # commit can correct. So the same check runs on the server.
+        run: |
+          set -euo pipefail
+          BASE="${{ github.event.pull_request.base.sha || github.event.before || '' }}"
+          if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ] \
+             || ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
+            echo "no usable base ref; checking HEAD only"
+            LIST=$(git rev-parse HEAD)
+          else
+            LIST=$(git rev-list "$BASE..${{ github.sha }}")
+            echo "checking $(echo "$LIST" | grep -c . ) commit message(s) in $BASE..${{ github.sha }}"
+          fi
+          FAILED=0
+          for SHA in $LIST; do
+            git log -1 --format=%B "$SHA" > /tmp/msg.txt
+            echo "--- $SHA"
+            python3 tools/commit_msg_check.py /tmp/msg.txt || FAILED=1
+          done
+          exit $FAILED
+
+      - name: Tests
+        # The PACKAGE is not pip-installed first, deliberately. One test asserts that
+        # a bare `python3 -m bmc_sensor_audit.cli` FAILS without PYTHONPATH, and an
+        # install would put the package on the path and make that test pass for the
+        # wrong reason -- turning a real negative into a vacuous one.
+        #
+        # PyYAML is a different question, and it is installed. The generated-output
+        # hygiene pair scans the SERIALISED model, so it needs the serialiser, and on
+        # a bare interpreter those two tests failed here from the commit that added
+        # them. Gating them and stopping there would have turned that red into a
+        # skip -- a leak check that no longer runs anywhere it matters. Installing
+        # PyYAML does not put bmc_sensor_audit on the path, so the negative above is
+        # untouched.
+        #
+        # pytest is installed for the same reason, and its absence was worse than a
+        # missing dependency: `setup-python` provides a clean interpreter that does
+        # not carry pytest, so `python3 -m pytest` exited with `No module named
+        # pytest` on every push since this workflow was written. The step failed
+        # instantly, no test ever ran on the server, and the two steps below it --
+        # the ones that run what the README prints -- never executed at all. A
+        # workflow can be red for its whole life without ever having run the thing
+        # it exists to run.
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet pyyaml pytest
+          python3 -m pytest tests/ -q
+
+      - name: The documented console-script path, from a clean checkout
+        # The second path the README prints, which the suite can only check
+        # structurally because it must not run pip. Here a clean runner is free,
+        # so run it for real: install, leave the checkout, and execute the
+        # command a reader would type.
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet -e .
+          mkdir -p "$RUNNER_TEMP/board" && cd "$RUNNER_TEMP/board"
+          printf '%s' '{"Name":"Board","Exposes":[{"Name":"Inlet Temp","Type":"TMP75"}]}' > board.json
+          bmc-sensor-audit declare --config board.json | tee out.txt
+          grep -q "sensors declared" out.txt
+
+      - name: A real wheel, from a directory with no checkout
+        # The editable install above cannot see this class of defect. `pip install
+        # -e .` resolves the package back to the source tree, so a data file the
+        # wheel fails to include still loads from the checkout and every check
+        # passes -- while the artifact a user actually installs raises on first
+        # use. The package now ships `redfish_properties.json`, which is the
+        # standard property set `--strict-fields` judges against and the first
+        # non-Python file this project depends on at runtime.
+        #
+        # So: build the wheel, install THAT into a fresh environment, and run the
+        # command that needs the data file, from outside the tree.
+        run: |
+          set -euo pipefail
+          python3 -m pip install --quiet build
+          python3 -m build --wheel --outdir "$RUNNER_TEMP/dist"
+          python3 -m venv "$RUNNER_TEMP/consumer"
+          "$RUNNER_TEMP/consumer/bin/pip" install --quiet "$RUNNER_TEMP"/dist/*.whl
+          mkdir -p "$RUNNER_TEMP/wheeltest" && cd "$RUNNER_TEMP/wheeltest"
+          printf '%s' '{"format":"bmc-sensor-audit/walk/1","fields_observed":true,"sensors":[{"name":"Inlet","path":"/redfish/v1/Chassis/1/Sensors/s0","reading":21.0,"units":"Cel","resource":"Sensor","undeclared":["ThermalZone"],"thresholds":{}}]}' > walk.json
+          printf '%s' '{"Name":"Board","Exposes":[{"Name":"Inlet","Type":"TMP75"}]}' > board.json
+          "$RUNNER_TEMP/consumer/bin/bmc-sensor-audit" coverage --config board.json --walk walk.json --strict-fields | tee out.txt
+          grep -q "ThermalZone" out.txt
+
+      - name: The documented module path, from a directory with no checkout
+        # The first path the README prints. Run from outside the tree so a stray
+        # working-directory import cannot make it pass by accident.
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/mod" && cd "$RUNNER_TEMP/mod"
+          printf '%s' '{"Name":"Board","Exposes":[{"Name":"Inlet Temp","Type":"TMP75"}]}' > board.json
+          PYTHONPATH="$GITHUB_WORKSPACE/src" python3 -m bmc_sensor_audit.cli declare --config board.json

bmc_sensor_audit-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+
+# Recorded walks captured from real hardware. A Redfish walk carries serial
+# numbers, asset tags, MAC addresses and BMC hostnames, so a capture is a fleet
+# inventory disclosure. Redact and rename deliberately before committing one;
+# nothing named `*.capture.json` should ever reach a remote by accident.
+*.capture.json
+
+# Site-specific hygiene vocabulary. Untracked on purpose: a rule that forbids a
+# private name must spell that name out, so committing it here would publish
+# exactly what it exists to protect. See tools/hygiene_check.py.
+.hygiene-local.json

bmc_sensor_audit-0.1.0/CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: 1.2.0
+message: "If you reference bmc-sensor-audit in academic or technical work, please cite as follows."
+title: "bmc-sensor-audit: find the sensors that should be reporting and are not"
+abstract: "Diffs an OpenBMC entity-manager declaration against what a BMC actually
+  reports over Redfish, so sensors that went absent, were disabled at the factory,
+  or froze at a plausible value are named instead of silently missing. Presence is
+  three-valued — reading, disabled, absent — and liveness is judged over
+  observation history by the arbiter-engine invariant checker. A run that cannot
+  be completed exits distinctly from one that found regressions, so 'could not
+  verify' never reads as 'clean'. Parser behaviour is derived by measurement of
+  the full upstream configuration corpus, an approach that has so far surfaced
+  two defects in the upstream declarations themselves. Released under Apache 2.0."
+type: software
+authors:
+  - family-names: "Sheen"
+    given-names: "James"
+    alias: "james-sheen"
+# Quoted deliberately. CFF 1.2.0 types both of these as strings, and an unquoted
+# date deserialises to a date object in most YAML parsers -- which validates
+# locally and fails the schema.
+version: "0.1.0"
+date-released: "2026-08-21"
+license: Apache-2.0
+repository-code: "https://github.com/james-sheen/bmc-sensor-audit"
+url: "https://github.com/james-sheen/bmc-sensor-audit"
+keywords:
+  - openbmc
+  - redfish
+  - bmc
+  - entity-manager
+  - sensors
+  - hardware-monitoring
+  - liveness

bmc_sensor_audit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Code of Conduct
+
+bmc-sensor-audit follows the
+[Contributor Covenant Code of Conduct v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+All participants in this project's issue tracker, discussions, and any
+community forum are expected to abide by these standards. Violations may be
+reported to the maintainers via the private channel described in
+[SECURITY.md](SECURITY.md) — GitHub Private Vulnerability Reporting routes
+confidentially to maintainers and is the appropriate intake for conduct
+reports as well as security disclosures.
+
+## Summary
+
+- Be kind. Assume good faith.
+- Critique ideas, not people.
+- Adversarial-finding reports describe a gate that passed over something it did
+  not audit; they do not describe testers as adversaries.
+- Harassment, abuse, and deliberate dissemination of harmful content are out of
+  scope.

bmc_sensor_audit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+The most useful thing you can send is a machine or a configuration where the
+gate said clean over something it did not audit. That is the failure this tool
+exists to prevent, and it is the report this project wants most. The
+second-most useful is a real entity-manager declaration the reader mis-parses
+silently — the upstream corpus has already taught this parser five lessons the
+format documentation does not mention, and there is no reason to believe it is
+done teaching.
+
+## What is open right now
+
+**Issues: open.** Bug reports, adversarial findings, and questions about
+running the tool against your hardware are all welcome. A report that can be
+acted on here carries four things: the configuration (or the name of the
+vendored one that shows it), the walk or capture it ran against, the full
+report text with the exit code, and — if the `[detect]` extra is involved —
+the installed `arbiter-engine` version, because presence and correctness are
+different checks and a stale engine fails in code-shaped ways.
+
+**Real-hardware captures: actively wanted.** Criterion 2's last line closes
+with a capture from physical hardware, and `capture` writes only the parsed
+sensor set by design — serials, asset tags and MAC addresses never reach the
+file. Run one command, attach the output, and say what machine it came from.
+
+**Documentation pull requests: open.** If the README describes behaviour the
+package does not have, a PR is the fastest route and it will be merged. Note
+that the README's commands and its test count are themselves under test, so a
+documentation change may fail the suite until the matching assertion moves —
+that is the suite doing its job.
+
+**Code pull requests: not being merged yet, and the reason is capacity.**
+This mirrors the sibling engine's policy for the same one-maintainer reason,
+and what ends it is the same: a second reviewer, not a version number.
+
+## A report does not have to be complete to be worth sending
+
+The best finding this repository has received so far was a lead rather than a
+proof, and the half of it that was left open turned out to be the half that
+mattered: a note that the parser never consulted an entry's `Labels` array, and
+that a sensor declared through `Labels` alone would therefore be invisible. Both
+halves were correct. The first was fixed and the second was recorded as an open
+question — and measuring it later showed it had been hiding most of the rails in
+the vendored corpus, every one of them a sensor whose absence could never have
+been reported.
+
+So: if you can see that something is wrong but not how far it goes, send it
+anyway and say where you stopped looking. *I did not audit X* is the most useful
+sentence in a report, and it will be read as a lead rather than as a disclaimer.
+
+## Running the suite
+
+Enable the hook first — the suite fails without it, deliberately:
+
+    git config core.hooksPath .githooks
+
+The suite has two honest populations: without the `[detect]` extra (Stage 1,
+dependency-free) and with it. Both are green at head; the exact counts live in
+the README's Tests row, which is enforced by a test rather than promised by a
+sentence.