check_sofa_security

hrtfpykit.sofa.check_sofa_security(target=None, hdf5_version=None, min_safe_hdf5='1.14.4', print_report=True, paranoid_mode=False)

Run security checks for SOFA/HDF5 file handling.

Checks include:

  • HDF5 runtime version against a minimum safety baseline. The default baseline (HDF5_MIN_SAFE_VERSION) is set to the first release that addressed a large batch of HDF5 parsing CVEs. For details, consult the HDF Group security advisories and the NVD CVE database for HDF5 issues.

  • detection of external links/domains and suspicious file extensions

Modes:

  • STANDARD: parse SOFA attributes using netCDF4 (opens the SOFA file)

  • PARANOID: scan raw SOFA file bytes only (no parsing). Requires a path.

Parameters:

  • target (Optional[Union[str, pathlib.Path, netCDF4.Dataset]], optional) – SOFA file path or open netCDF4 object. In paranoid_mode, this must be a path because raw bytes are inspected without parsing the file.

  • hdf5_version (Optional[str], optional) – HDF5 version to validate against. If None, attempts to detect the linked HDF5 version from netCDF4.

  • min_safe_hdf5 (str, optional) – Minimum acceptable HDF5 version for baseline safety checks.

  • print_report (bool, optional) – Whether to print a formatted report of all checks.

  • paranoid_mode (bool, optional) – If True, reads raw bytes from the file path only and never parses the SOFA file. Raises ValueError if checks fail.

Returns:

Security report with overall status and individual check results.

Return type:

dict

Raises:

ValueError – If paranoid_mode is True and target is not a file path, or if paranoid mode checks fail.

Examples

Check a SOFA file before passing it into a loading or processing workflow. The report contains one entry per security check, and the “failed” list can be used as the error message when a file does not pass:

>>> from hrtfpykit.sofa import check_sofa_security
>>> report = check_sofa_security(
...     "hrtfs/P0001_FreeFieldComp_44kHz.sofa",
...     print_report=False,
... )
>>> report["passed"]
True
>>> report["failed"]
[]
>>> check_names = [check["name"] for check in report["checks"]]
>>> "hdf5_min_safe_version" in check_names
True