Skip to content

Security: jmrplens/phonometry

SECURITY.md

Security policy

What this project is

phonometry is a scientific Python library. It computes acoustic, vibration and psychoacoustic quantities from arrays and files you hand it, inside your own process. It runs no service, holds no credentials, and never executes code derived from what you pass it: it calls its own code and its declared dependencies, nothing else. It opens no socket of its own, and it starts another program only when you ask for what needs one: a simulation you send to a remote node runs your own ssh client against a host your hosts file names, and writing a video runs ffmpeg, each by its full path and with every argument checked before it starts. That shapes what a vulnerability can be here, so this policy is written for this library rather than copied from a generic template.

Supported versions

Fixes ship forward. There are no backports: a security fix is released as a new version from main, and the remedy for any older version is to upgrade.

Version Supported
Latest 4.x release Yes
Earlier 4.x releases, and the 4.0.0rc1 pre-release Upgrade to the latest 4.x
3.x No: upgrade to the latest 4.x
2.x and earlier, including PyOctaveBand No

3.x stops receiving security updates the day 4.0.0 is published. Bug and conformance fixes follow the same rule: they reach the latest release through the next one, and no other release receives them.

Staying on the latest 4.x is cheap by design. After 4.0.0, a name that a release renames keeps working, with a DeprecationWarning that names its replacement, and goes only in the next major release (rule A16 of the contributor guide). The step from 3.x to 4.x is the one that breaks, on purpose: Upgrading from 3.3 to 4.0 maps every 3.x name to its new home, and it also lists what changed after 4.0.0rc1.

The PyOctaveBand package on PyPI is a stub that installs phonometry 3.x and receives no fixes. Install phonometry itself for a supported version.

Supported interpreters and platforms are whatever the test matrix in .github/workflows/python-app.yml exercises, at the time of writing Python 3.12, 3.13 and 3.14 on Ubuntu, macOS and Windows. That workflow is the authority, not this paragraph. A report that reproduces only outside the matrix is handled as an ordinary bug.

Reporting a vulnerability

Report privately through GitHub, with Security > Report a vulnerability, or directly at github.com/jmrplens/phonometry/security/advisories/new. That opens a private advisory visible only to you and the maintainers, and keeps the report, the fix and any CVE in one place.

If private reporting is not available to you, write to mail@jmrp.io, the maintainer address already published in CITATION.cff and CODE_OF_CONDUCT.md, with phonometry security in the subject. Please do not use a public issue, a discussion or a pull request for a suspected vulnerability.

A useful report states the version and interpreter, a minimal reproduction, the input that triggers the behaviour, and what an attacker gains. If a standard is involved, cite the clause or table by number rather than pasting the text. Standards are copyrighted.

What to expect

This library is maintained by one person alongside research work, so these are commitments I can keep rather than an enterprise service level:

Step Target
Acknowledgement that the report arrived 5 working days
First assessment: accepted, more information needed, or out of scope 15 working days
Release containing the fix, once accepted with the next release, sooner if the impact warrants it

If the acknowledgement window passes in silence, add a comment on the advisory. It means the notification was missed, not that the report was dismissed.

Coordinated disclosure

I work to coordinated disclosure. Please give me a chance to publish a fixed release before going public. In return I keep the advisory updated while it is open, credit you unless you would rather stay anonymous, and publish the advisory (with a CVE where GitHub assigns one) once the fixed version is on PyPI.

Ninety days from acknowledgement is a reasonable ceiling. If a fix is going to take longer than that I will say so on the advisory instead of letting it go quiet.

Scope

Treated as a vulnerability

  • Untrusted input reaching a computation. Measurement arrays, samples decoded elsewhere and passed in, and above all the file readers: the aircraft noise module reads ANP CSV exports from a directory you point it at. If a crafted file causes anything worse than a clean exception, for example unbounded memory growth, a path that escapes the directory it was given, or an attempt to execute what was read, that is a vulnerability.
  • Deserialisation. The library deliberately never unpickles or evaluates anything derived from input, and imports no module that input names except its own: a warning a remote node relays names its class, which is imported only from phonometry's own modules and otherwise looked up only among the modules your process has already imported. A code path that goes further is a defect worth reporting even without a working exploit.
  • Supply chain. Anything that can place code into a published artefact: the release workflow, the contents of the built wheel or sdist, package data reaching outside the package, or a dependency declaration that resolves somewhere unexpected.
  • Repository automation. A workflow in this repository that can be made to run attacker-controlled code, leak a secret, or escalate its token permissions.

Not treated as a vulnerability

  • A value that disagrees with a standard. This is the failure mode that matters most in this library, and it is a conformance defect, not a security issue. Once the disagreement has been established, usually in Standards & conformance, file it with the conformance defect form. It is handled with the same seriousness as a security report, in public, where the numbers can be checked.
  • A defect in the published standard itself. Misprints and worked examples that contradict their own normative text are recorded in docs/ERRATA.md with the evidence and the reading the library implements. Those entries are documentation, never security advisories.
  • Resource exhaustion you asked for, such as requesting a transform over an array that does not fit in memory. The library computes what it is told to compute.
  • Results from inputs outside the validity range of a method, for instance a temperature or a frequency beyond what the standard covers. The guides state the ranges; a missing range check is a bug report.
  • Vulnerabilities in numpy, scipy, matplotlib, reportlab or any other dependency. Report those upstream. If phonometry uses the dependency in a way that exposes users to it, that use is in scope here.
  • Scanner output with no demonstrated impact, and hardening suggestions with no exploit path. Both are welcome as ordinary issues.

What already runs

Rather than describe a process I do not have, here is the tooling that runs on every pull request and on main:

  • CodeQL default setup, weekly and on change, over the Python, JavaScript/TypeScript and GitHub Actions code.
  • bandit over src/ in the quality job. Any finding fails the build, including Low severity, so the source stays clean of assert in library code, unreviewed subprocess use and hardcoded secrets.
  • GitGuardian secret scanning on every pull request.
  • Dependabot security and version updates for pip, npm and GitHub Actions, grouped weekly, each proposed three days after it is published rather than the morning it appears.
  • zizmor over everything under .github/ in the quality job: a workflow that expands untrusted input into a shell, grants a token it does not need, leaves its token in .git or uses an action with a published advisory fails the build.
  • Snyk through the snyk target in the Makefile, for an on-demand dependency audit.

Workflows declare contents: read at the top level and widen permissions only on the individual jobs that need them; the release workflow grants nothing at the top level at all.

Verifying a release

Every release from 4.0.0 on is built, checked and published by .github/workflows/release.yml, run by a push to main on a runner GitHub hosts. It is uploaded to PyPI through trusted publishing: no token is stored anywhere, and PyPI attaches to each file a PEP 740 attestation, which the file's page on PyPI shows under Provenance. The GitHub Release carries the same wheel and sdist, a checksum file, phonometry-<version>.sha256, and a CycloneDX SBOM, phonometry-<version>.cdx.json, of what pip install phonometry resolved on the day. GitHub keeps a build provenance attestation for each of those four files and, for every release after 4.0.0, an SBOM attestation that ties the SBOM to the wheel.

4.0.0 has no SBOM attestation. Its run uploaded the wheel and the sdist to PyPI and recorded the build provenance of all four files, then stopped at the SBOM attestation, which refused an SBOM without a serial number. The tag and the GitHub Release were then made by hand, from the files that run had built and attested, so every check below holds for 4.0.0 but the SBOM attestation.

The signing is keyless, so there is no key file to fetch or to trust: each attestation is signed with a short-lived Sigstore certificate issued to the run of the workflow, and a verification checks the identity that certificate names.

  • Issuer: https://token.actions.githubusercontent.com.
  • Identity: https://github.com/jmrplens/phonometry/.github/workflows/release.yml@refs/heads/main.
  • Runner: one GitHub hosts, never a self-hosted one.
  • On PyPI, the trusted publisher of phonometry: owner jmrplens, repository phonometry, workflow release.yml, no environment.

To check that a file is one this repository's release workflow built:

# The wheel, the sdist, the checksum file or the SBOM, from PyPI or the GitHub Release.
gh attestation verify phonometry-4.0.0-py3-none-any.whl --repo jmrplens/phonometry \
    --signer-workflow jmrplens/phonometry/.github/workflows/release.yml \
    --source-ref refs/heads/main --deny-self-hosted-runners

# The PEP 740 attestation PyPI serves, without downloading anything first.
python -m pip install pypi-attestations
python -m pypi_attestations verify pypi --repository https://github.com/jmrplens/phonometry \
    pypi:phonometry-4.0.0-py3-none-any.whl

# The files of the GitHub Release against the checksum file it carries.
sha256sum --check phonometry-4.0.0.sha256

The SBOM attestation of a release after 4.0.0 is checked on its wheel, with the version of that release where this shows <version>:

gh attestation verify "phonometry-<version>-py3-none-any.whl" --repo jmrplens/phonometry \
    --predicate-type https://cyclonedx.org/bom \
    --signer-workflow jmrplens/phonometry/.github/workflows/release.yml \
    --source-ref refs/heads/main --deny-self-hosted-runners

The signed source of a release is its sdist: the source the wheel was built from, attested like the wheel. The "Source code" archives GitHub offers on every release are made from the tag when they are downloaded and carry no signature, and neither does the zip Zenodo keeps, which is made from one of them.

The SBOM lists the runtime dependencies at the versions the release resolved (numpy and scipy); the optional extras are not in it, because a plain install does not bring them.

Integrity of the numbers is gated too, which matters more here than in most libraries: docs/CONFORMANCE.md is regenerated in CI from the library's own computations against reference values and the build fails if the committed report drifts, so a change that quietly moves a standards-conformant result cannot reach a release unnoticed.

Rebuilding a release

Every release from 4.0.0 on rebuilds from its tag to the bytes PyPI and the GitHub Release hold, on Linux and on macOS. The release workflow builds every release twice before it publishes and refuses one whose builds differ, and once it has published it clones the tag on macOS, rebuilds it as below and compares the files with PyPI's; a rehearsal does the same with the commit it builds and its own files, and so does every pull request. For 4.0.0 that rebuild after the release did not run, since the run stopped before it, at the SBOM attestation; Python CI had rebuilt the same commit on macOS to the bytes the release published. To rebuild one yourself, with Python 3.13, which the release builds with:

git clone --depth 1 --branch v4.0.0 --config core.autocrlf=false \
    https://github.com/jmrplens/phonometry.git
cd phonometry
python3.13 -m venv ../phonometry-build
../phonometry-build/bin/python -m pip install --upgrade pip
../phonometry-build/bin/python -m pip install -r requirements-release.txt
../phonometry-build/bin/python scripts/build_release.py --outdir ../rebuilt --check-pypi

scripts/build_release.py builds the sdist with the setuptools that requirements-release.txt pins, without build isolation, and with every time stamp set to the commit's, from the commit's files as git archive exports them rather than from the checkout, so a file the checkout holds beside them, one git ignores included, reaches neither file. It writes the sdist again without the time of the build, the builder's user or the checkout's modes, builds the wheel from that sdist under umask 022, and compares both files with the digests PyPI publishes for the version; --check phonometry-4.0.0.sha256 compares them with the release's checksum file instead. It refuses a checkout that differs from its commit, and an environment in which another package installs a setuptools plugin that could change what is packed, which is why the build gets a virtual environment of its own. core.autocrlf=false keeps the files as the commit holds them, and .gitattributes checks out every file the sdist carries with LF whatever core.autocrlf or core.eol the cloner has set.

The script refuses to build on Windows, where the operating system reaches the bytes: zipfile records the system that wrote each member of the wheel, setuptools gives the wheel's modules the mode Windows reports, and it writes the sdist's PKG-INFO and setup.cfg with CRLF. On Windows, run the commands above inside WSL, from a clone made in WSL's own filesystem (under ~, not under /mnt/c, where the files carry no Unix modes and every one of them looks executable).

The compressed bytes of both files come from the zlib that Python is linked against. The release compares a build on Linux with one on macOS; a Python linked against another implementation of it, such as zlib-ng, compresses the same files to other bytes.

Credit

Reporters are credited in the published advisory and in the changelog entry for the release that carries the fix, unless they ask not to be.

There aren't any published security advisories