Merge pull request #703 from yzhao062/development

v3.6.2: security release (CVE-2026-15529)

Author: yzhao062

CHANGES.txt

@@ -230,3 +230,4 @@ v<3.5.3>, <05/19/2026> -- KB-tools API for agent-driven and LLM-API-driven routi
 v<3.5.4>, <06/03/2026> -- Claims-honesty and framing-consistency remediation of the v3 agentic layer from an internal audit (no detector behavior change). Determinism: `ADEngine.random_state` docstring upgraded from the vague "deterministic-up-to-numpy-module-state" hedge to the audited guarantee (a run-to-run audit of the shipped shallow detectors found every one either honors the seed or is deterministic by construction; deep detectors additionally depend on framework seeding). Counts: every public surface now reports 60 buildable detectors instead of 60+/61/50+; `scripts/regen_skill.py` and `pyod/cli.py` exclude `status == "planned"` so the non-buildable `LLMAD` no longer inflates the od-expert skill's counts/lists or `pyod info` (now `60 total (43 tabular, 7 time-series, 8 graph, 2 text, 2 image, 1 multimodal)`); `LLMAD` stays in the raw KB as a roadmap entry. Expert-level: `docs/index.rst`, `od_expert/SKILL.md`, `docs/skill_maintenance.rst`, and `docs/examples/agentic.rst` reword "expert-level/expert-quality results" to a complete-workflow/accessibility claim. Trust verdict: `docs/examples/adengine.rst` demotes the quality verdict to descriptive diagnostics with a "heuristic, not a guarantee" note and corrects the stale "Jaccard" stability description to the cutoff-gap formula; `_quality_metrics.compute_quality` docstring documents `separation` as circular (computed from the run's own predicted labels, near-always high, and not independent of the majority-vote consensus labels); the od-expert skill's Trigger 4 is reframed to cutoff-instability on `stability` only, and its result-interpretation, per-modality confidence lines, and examples route confidence through low `agreement` plus label-free caveats instead of `separation`/`overall`/`verdict`. Consensus: skill guidance softened from "never report from a single detector" to "prefer consensus for robustness; about as accurate as the best single pick." Framing consistency: ADEngine is described as a "lifecycle orchestration" engine rather than "intelligent orchestration" across README, docs, the API reference, and the module docstring, matching the finding that the layer's value is the drivable, reproducible workflow rather than selection intelligence. Tests: 2 new count-locking regression tests (`test_cli.py::test_pyod_info_excludes_planned_detectors`, `test_skill_kb_consistency.py::test_skill_count_prose_matches_kb`) compute expected buildable counts from the KB and fail on regression. Reviewed via /implement-review (Codex, 4 rounds): R1 raised 3 High + 2 Medium + 1 Low, R2 verified 5/6 and flagged trust-gate residue, R3 cleared it, R4 confirmed commit-ready. No breaking API changes.
 v<3.6.0>, <06/04/2026> -- Add audio as a first-class anomaly detection modality. New AudioFeatureEncoder reduces each clip to a 74-dimensional handcrafted acoustic vector (20 MFCC, 12 chroma, and 5 spectral descriptors: centroid, bandwidth, rolloff, zero-crossing rate, and RMS, each as its mean and standard deviation over frames, via librosa), registered as the 'audio-mfcc' encoder and exposed through EmbeddingOD.for_audio() so any classical detector runs on audio. New AudioAE detector is a DCASE-style log-mel reconstruction autoencoder that reuses the PyOD AutoEncoder with clip-level error aggregation. ADEngine now profiles audio file paths and routes audio, with EmbeddingOD.for_audio as the default and AudioAE as the deep alternative; the knowledge base gains an AudioAE entry and audio support on EmbeddingOD and MultiModalOD. New optional extra pyod[audio] (librosa, soundfile). Buildable detector count rises from 60 to 61. References are the public methods (the DCASE 2020 Task 2 log-mel autoencoder baseline, and MFCC, chroma, and spectral features via librosa). Reviewed via /implement-review (Codex, no High findings; one Medium and two Low fixed). No breaking API changes.
 v<3.6.1>, <06/16/2026> -- Maintenance and contributor PRs since v3.6.0 (no breaking API changes). PyThresh v1 support (#684, Daniel Kulik): the pyod.models.thresholds wrappers and the BaseDetector threshold path use the pythresh v1 API (.fit()/.labels_/.predict() instead of .eval()), and the dependency pin moves to pythresh>=1.0.0. EmbeddingOD air-gapped and pre-instantiated encoder support (#696, Sunny Guntuka): a pre-loaded SentenceTransformer instance can be passed directly as the encoder, and a local filesystem path is loaded with local_files_only=True (no Hub call) for offline use; this also fixes a resolver-order bug where a SentenceTransformer instance was wrapped as a CallableEncoder (calling model(X) instead of model.encode(X)). DataFrame feature-name warning fix (#692, eferhire ugbotu; closes #540): GMM, IForest, LOF, and OCSVM run check_array in decision_function, so scoring a pandas DataFrame after fitting no longer emits the scikit-learn feature-name UserWarning; the predict/predict_proba/predict_confidence paths route through decision_function, so the single-point fix covers them. Audio docs: AudioAE and the audio modality are now in the README and docs algorithm tables with a new pyod.models.audio API page (v3.6.0 shipped AudioAE without a table row). Tests: regression tests for the DataFrame-warning fix (GMM/OCSVM/LOF) and a no-download EmbeddingOD resolver test using SentenceTransformer(modules=[]). Docs: PyPI download figure refreshed to 46M+. Reviewed via /implement-review (Codex gatekeeper): #696 and #692 merged after dual review, with the gatekeeper-flagged test gaps closed in a follow-up. Buildable detector count unchanged at 61.
+v<3.6.2>, <07/20/2026> -- Security hardening for model persistence (CVE-2026-15529): both `pyod.utils.persistence.load()` and `pyod.utils.persistence.compat_load()` now refuse to deserialize pickle/joblib artifacts unless callers pass `trusted=True`, making the trust boundary explicit before `joblib.load()` can execute pickle reducers. This is a breaking change: existing `save()` then `load()` round trips, and any direct `compat_load()` calls, must add `trusted=True`, because both functions now refuse even artifacts you saved yourself until the caller acknowledges the source is trusted. The internal `load()` fall-through to `compat_load()` forwards the acknowledgement automatically, so `load(path, trusted=True)` still recovers legacy dtype-mismatched artifacts in a single call. `strict=True` remains a dependency-version policy and is documented as not making untrusted pickle files safe. Adds regression tests verifying that both the default `load()` path and a direct `compat_load()` call reject before any unpickling side effects occur. Updates the model persistence guide, decision tree, troubleshooting table, and save/load example to pass `trusted=True` for trusted artifacts. Closes #697.

docs/model_persistence.rst

@@ -20,11 +20,14 @@ Quick Start
     # Save with a versioned envelope.
     save(clf, "clf.pyod.joblib", metadata={"dataset": "demo"})
 
-    # Later, in a possibly different environment:
-    clf = load("clf.pyod.joblib")
+    # Later, in a possibly different environment. ``trusted=True`` is
+    # required because joblib/pickle artifacts can execute code while
+    # they are being deserialized.
+    clf = load("clf.pyod.joblib", trusted=True)
 
     # Or get the envelope back alongside the model:
-    clf, env = load("clf.pyod.joblib", return_metadata=True)
+    clf, env = load(
+        "clf.pyod.joblib", return_metadata=True, trusted=True)
     print(env["sklearn_version"], env["saved_at"])
 
 The complete example in
@@ -38,8 +41,16 @@ Trust Boundary
 ``pickle`` and ``joblib`` deserialize arbitrary Python code. Load only
 from sources you trust. This applies equally to raw ``joblib.load``,
 raw ``pickle.load``, :func:`~pyod.utils.persistence.load`, and
-:func:`~pyod.utils.persistence.compat_load`. The new wrapper does not
-change this security model; it does not sandbox the unpickling step.
+:func:`~pyod.utils.persistence.compat_load`. The wrapper does not
+sandbox the unpickling step, and ``strict=True`` is only a dependency
+version policy.
+
+For that reason, both :func:`~pyod.utils.persistence.load` and
+:func:`~pyod.utils.persistence.compat_load` refuse to deserialize
+unless callers pass ``trusted=True``. This flag is an explicit
+acknowledgement that the artifact came from a trusted training
+pipeline, model registry, or other trusted source. It is not a
+security scan of the file.
 
 Why a Versioned Wrapper
 -----------------------
@@ -77,7 +88,7 @@ running sklearn's dtype before sklearn's own ``__setstate__`` raises.
 
     from pyod.utils.persistence import compat_load
 
-    clf = compat_load("legacy.joblib")
+    clf = compat_load("legacy.joblib", trusted=True)
     # Re-save under the new envelope to avoid repeating the dance:
     from pyod.utils.persistence import save
     save(clf, "legacy_resaved.pyod.joblib")
@@ -92,7 +103,7 @@ legacy handler:
 
     from pyod.utils.persistence import load
 
-    clf = load("legacy.joblib")   # transparently recovers from dtype drift
+    clf = load("legacy.joblib", trusted=True)  # recovers from dtype drift
 
 The fall-through emits a ``UserWarning`` so the recovery does not
 go unnoticed. Re-save with :func:`~pyod.utils.persistence.save` (or
@@ -107,16 +118,17 @@ Decision Tree
     Saving a new model?
         -> use save(clf, path)
 
-    Loading a model and load(path) works without warnings?
+    Loading a trusted model and load(path, trusted=True) works without warnings?
         -> done
 
-    Loading a model and load(path) succeeds with a "recovered" warning?
+    Loading a trusted model and load(path, trusted=True) succeeds with a "recovered" warning?
         -> the artifact was repaired via compat_load; re-save with save()
 
-    Loading a model and load(path) raises?
-        -> if the error is about Tree-node dtype, try compat_load directly
-           and check whether the warning recommends re-fit. If it cannot
-           recover, re-fit on the current sklearn.
+    Loading a trusted model and load(path, trusted=True) raises?
+        -> if the error is about Tree-node dtype, try
+           compat_load(path, trusted=True) directly and check whether the
+           warning recommends re-fit. If it cannot recover, re-fit on the
+           current sklearn.
 
 Cross-Sklearn-Version Compatibility
 -----------------------------------
@@ -157,7 +169,7 @@ Troubleshooting
 ==================================================================  ==================================================================
 Error text starts with                                              Recommended action
 ==================================================================  ==================================================================
-``node array from the pickle has an incompatible dtype``            Try :func:`~pyod.utils.persistence.compat_load`. If it succeeds, re-save with :func:`~pyod.utils.persistence.save`. If it raises, re-fit.
+``node array from the pickle has an incompatible dtype``            Try :func:`~pyod.utils.persistence.compat_load` with ``trusted=True``. If it succeeds, re-save with :func:`~pyod.utils.persistence.save`. If it raises, re-fit.
 ``InconsistentVersionWarning`` (only a warning, not an error)       Safe to ignore; sklearn is reminding you the save and run versions differ. Re-save or re-fit when convenient.
 Other sklearn unpickling errors                                     The artifact is incompatible beyond what ``compat_load`` repairs. Re-fit on the current sklearn.
 ==================================================================  ==================================================================
@@ -172,38 +184,38 @@ For version-pinned production environments, pass ``strict=True`` to
 
     from pyod.utils.persistence import load
 
-    clf = load("prod.pyod.joblib", strict=True)
+    clf = load("prod.pyod.joblib", strict=True, trusted=True)
 
 Under strict mode, any drift in sklearn, joblib, numpy, or scipy
 raises ``ValueError`` rather than emitting a warning. Drift in the
 Python version does not raise because it is informational only.
 Strict mode also rejects raw legacy artifacts (no envelope to
 compare against) and refuses to return a model that required a
 ``compat_load`` repair: strict callers must either re-save under the
-current environment or re-fit.
+current environment or re-fit. Strict mode does not make untrusted
+pickle/joblib files safe to load; ``trusted=True`` is still required.
 
 Reading Envelope Metadata
 -------------------------
 
-``load(path, return_metadata=True)`` returns a ``(model, envelope)``
-tuple where ``envelope`` is the full envelope dict minus the
-``model`` field:
+``load(path, return_metadata=True, trusted=True)`` returns a
+``(model, envelope)`` tuple where ``envelope`` is the full envelope
+dict minus the ``model`` field:
 
 .. code-block:: python
 
     from pyod.utils.persistence import load
 
-    clf, env = load("clf.pyod.joblib", return_metadata=True)
+    clf, env = load(
+        "clf.pyod.joblib", return_metadata=True, trusted=True)
     print(env["pyod_version"], env["sklearn_version"])
     print(env["saved_at"], env["model_class"])
     print(env["metadata"])   # whatever you passed to save(... metadata=...)
 
-A future PyOD release plans a true header-only ``inspect_artifact``
-(reading metadata without unpickling the model), paired with a
-``.pyod`` zip container that separates metadata from the model
-payload. Until that ships, ``load(..., return_metadata=True)`` is
-the supported way to introspect a saved artifact, and it does
-unpickle the model.
+``load(..., return_metadata=True, trusted=True)`` still unpickles the
+model. It should only be used for trusted artifacts. A future PyOD
+release may add a true header-only ``inspect_artifact`` API for reading
+metadata without unpickling the model payload.
 
 Neural Network Models
 ---------------------

examples/save_load_model_example.py

@@ -61,11 +61,13 @@
     save(clf, artifact_path, metadata={'dataset': 'demo', 'note': 'LOF baseline'})
 
     # The matching load() reads the envelope and warns on dependency
-    # drift; pass strict=True for version-pinned production deployments.
-    clf = load(artifact_path)
+    # drift. joblib/pickle artifacts can execute code while loading, so
+    # load() requires trusted=True to acknowledge the artifact source.
+    # Pass strict=True as well for version-pinned production deployments.
+    clf = load(artifact_path, trusted=True)
 
     # To inspect the envelope without separately re-reading the file:
-    clf, env = load(artifact_path, return_metadata=True)
+    clf, env = load(artifact_path, return_metadata=True, trusted=True)
     print(
         f"Loaded {env['model_class']} "
         f"(pyod={env['pyod_version']}, sklearn={env['sklearn_version']}, "

pyod/test/fixtures/README.md

@@ -33,7 +33,8 @@ automatically on the same error.
 - raw `joblib.load(path)` raises a `ValueError` whose message starts with
   the documented dtype-mismatch prefix (so the fall-through trigger is
   observed end-to-end, not just hypothetical),
-- `compat_load(path)` returns an `IsolationForest`,
+- the trusted compat path (equivalent to `compat_load(path, trusted=True)`)
+  returns an `IsolationForest`,
 - the loaded model's `estimators_[0].tree_.__getstate__()['nodes'].dtype`
   equals the running sklearn's `NODE_DTYPE` (the dtype was actually repaired,
   not just silently accepted),

pyod/test/test_persistence.py

@@ -48,15 +48,31 @@
     _CURRENT_PERSISTENCE_VERSION,
     _DTYPE_MISMATCH_PREFIX,
     _TREE_NODE_FIELD_DEFAULTS,
-    compat_load,
-    load,
+    compat_load as _compat_load,
+    load as _load,
     save,
 )
 
 
 FIXTURES_DIR = Path(__file__).resolve().parent / 'fixtures'
 
 
+def load(*args, **kwargs):
+    """Test helper for the trusted artifact path exercised historically."""
+    kwargs.setdefault('trusted', True)
+    return _load(*args, **kwargs)
+
+
+def compat_load(*args, **kwargs):
+    """Test helper for the trusted compat path exercised historically."""
+    kwargs.setdefault('trusted', True)
+    return _compat_load(*args, **kwargs)
+
+
+def _write_marker(path, text):
+    Path(path).write_text(text)
+
+
 # ---------------------------------------------------------------------
 # Helpers: build pickles whose Tree-node dtype mimics an older sklearn
 # ---------------------------------------------------------------------
@@ -254,6 +270,22 @@ def setUp(self):
     def _tmp(self, name='artifact.joblib'):
         return os.path.join(self._tmpdir.name, name)
 
+    # ------------------------------------------------------------
+    # Trust boundary (fail-closed, mirrors load())
+    # ------------------------------------------------------------
+
+    def test_compat_load_requires_explicit_trust(self):
+        # compat_load() must fail closed like load(): the trust guard
+        # runs before the file is opened, so even a missing path raises
+        # the trust ValueError rather than FileNotFoundError. Calls the
+        # real _compat_load (not the trusted test wrapper) on purpose.
+        missing = self._tmp('missing.joblib')
+        with self.assertRaises(ValueError) as cm:
+            _compat_load(missing)
+        self.assertIn('trusted', str(cm.exception).lower())
+        self.assertFalse(os.path.exists(missing),
+                         'guard must reject before the file is touched')
+
     # ------------------------------------------------------------
     # Realignment on synthetic aged pickles
     # ------------------------------------------------------------
@@ -554,6 +586,38 @@ def test_save_load_with_user_metadata(self):
         self.assertEqual(env['metadata'], meta)
 
 
+class TestLoadTrustBoundary(unittest.TestCase):
+
+    def setUp(self):
+        self._tmpdir = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmpdir.cleanup)
+
+    def _tmp(self, name='artifact.joblib'):
+        return os.path.join(self._tmpdir.name, name)
+
+    def test_load_rejects_untrusted_artifact_before_unpickling(self):
+        marker = self._tmp('marker.txt')
+
+        class Payload:
+            def __reduce__(self):
+                return (_write_marker, (marker, 'executed'))
+
+        path = self._tmp()
+        joblib.dump({
+            '_pyod_persistence_version': _CURRENT_PERSISTENCE_VERSION,
+            'model': Payload(),
+        }, path)
+        self.assertFalse(os.path.exists(marker))
+
+        with self.assertRaises(ValueError) as cm:
+            _load(path)
+
+        self.assertIn('trusted', str(cm.exception).lower())
+        self.assertFalse(
+            os.path.exists(marker),
+            'untrusted load must fail before pickle reducers execute')
+
+
 class TestLoadLegacy(unittest.TestCase):
 
     def setUp(self):
@@ -877,9 +941,11 @@ def test_load_auto_fallthrough_trigger_is_exact_prefix(self):
         Path(path).write_bytes(b'')
 
         compat_calls = []
+        compat_trusted = []
 
-        def fake_compat_load(p, mmap_mode=None):
+        def fake_compat_load(p, mmap_mode=None, *, trusted=False):
             compat_calls.append(str(p))
+            compat_trusted.append(trusted)
             raise RuntimeError(
                 'fake_compat_load should not run for this branch')
 
@@ -926,6 +992,10 @@ def fake_load_prefix(*args, **kwargs):
         self.assertEqual(len(compat_calls), 1,
                          'prefix ValueError MUST trigger compat_load exactly '
                          'once')
+        self.assertEqual(
+            compat_trusted, [True],
+            'load() must forward trusted=True to the internal '
+            'compat_load fall-through')
 
 
 if __name__ == '__main__':