Add dual_use category to audit catalog

Author: pjwerneck

packages/syft-restrict/src/syft_restrict/audit.py

@@ -11,18 +11,21 @@
 
 - ``"unsafe"`` — matches a catalog entry for known disk/network/host-callback surface, OR is a glob
   (``jax.*``) that grants a whole namespace. Remove it or tighten the allow.
-- ``"safe"`` — matches a curated entry for a vetted pure-compute path. The explanation also flags any
-  *residual output-channel risk to review in combination*, kept deliberately vague (not a how-to).
-- ``"review"`` — neither unsafe nor in the safe catalog. The audit makes **no** guess about it: it is
-  reported as uncatalogued and deferred to human review. Unknowns are never assumed safe.
+- ``"dual_use"`` — a useful, mostly-safe op that can still be abused in combination (e.g. ``einsum``,
+  ``softmax``, ``where``). Allowed, but flagged: the *category itself* carries the "handle with care"
+  signal, so entry notes stay terse and vague — never an abuse how-to.
+- ``"safe"`` — matches a curated entry for a genuinely inert path (constants, masks, module refs) with
+  no residual output channel of its own.
+- ``"review"`` — none of the above. The audit makes **no** guess about it: it is reported as
+  uncatalogued and deferred to human review. Unknowns are never assumed safe.
 
 Limits (state them plainly to whoever reads a report):
 
 - Classification is **only** catalog matching — no source inspection, no inference. A path the catalog
   does not know is deferred to a human; the tool does not try to guess whether it does I/O.
 - The catalog is curated per library version; the report records the versions it saw.
 
-Anything not matched as unsafe or safe defaults to ``"review"``, never silently to ``"safe"``.
+Anything not matched as unsafe, dual_use, or safe defaults to ``"review"``, never silently to safe.
 """
 
 from __future__ import annotations
@@ -44,7 +47,11 @@
 _COMMON_LIB = "_common"
 _COMMON_VERSION = "default"
 
-Verdict = Literal["safe", "unsafe", "review"]
+# Catalog buckets, in the order they are matched (first hit wins): the strictest verdict a path
+# qualifies for is assigned, so unsafe beats dual_use beats safe.
+_BUCKETS: tuple[str, ...] = ("unsafe", "dual_use", "safe")
+
+Verdict = Literal["safe", "dual_use", "unsafe", "review"]
 
 
 class PathAudit(BaseModel):
@@ -57,33 +64,47 @@ class AuditReport(BaseModel):
     entries: list[PathAudit] = Field(default_factory=list)
     versions: dict[str, str] = Field(default_factory=dict)  # top-level package -> version seen
 
+    def _by_verdict(self, verdict: Verdict) -> list[PathAudit]:
+        return [e for e in self.entries if e.verdict == verdict]
+
     @property
     def unsafe(self) -> list[PathAudit]:
-        return [e for e in self.entries if e.verdict == "unsafe"]
+        return self._by_verdict("unsafe")
+
+    @property
+    def dual_use(self) -> list[PathAudit]:
+        return self._by_verdict("dual_use")
 
     @property
     def review(self) -> list[PathAudit]:
-        return [e for e in self.entries if e.verdict == "review"]
+        return self._by_verdict("review")
 
     @property
     def safe(self) -> list[PathAudit]:
-        return [e for e in self.entries if e.verdict == "safe"]
+        return self._by_verdict("safe")
 
     @property
     def ok(self) -> bool:
-        """True if nothing is unsafe. ``review`` entries do not fail it -- they need a human."""
+        """True if nothing is unsafe. ``dual_use`` and ``review`` entries do not fail it -- they are
+        allowed-but-flagged and need a human's eye, not a hard block."""
         return not self.unsafe
 
     def format(self) -> str:
         vers = ", ".join(f"{k} {v}" for k, v in sorted(self.versions.items())) or "no versions detected"
         lines = [f"allow-list audit ({vers})"]
-        for label, group in (("UNSAFE", self.unsafe), ("REVIEW", self.review), ("SAFE", self.safe)):
+        groups = (
+            ("UNSAFE", self.unsafe),
+            ("DUAL-USE", self.dual_use),
+            ("REVIEW", self.review),
+            ("SAFE", self.safe),
+        )
+        for label, group in groups:
             if not group:
                 continue
             lines.append(f"  {label} ({len(group)}):")
             for e in group:
                 lines.append(f"    - {e.path}{' — ' + e.reason if e.reason else ''}")
-        lines.append(f"  => ok={self.ok} (unsafe entries fail; review entries need a human)")
+        lines.append(f"  => ok={self.ok} (unsafe entries fail; dual-use and review entries need a human)")
         return "\n".join(lines)
 
     def __str__(self) -> str:
@@ -111,31 +132,29 @@ def _classify(path: str, versions: dict[str, str]) -> PathAudit:
             "list exact leaves instead",
         )
     library = path.split(".", 1)[0]
-    unsafe_rules, safe_rules = _rules_for(library, versions.get(library, ""))
-    for pattern, reason in unsafe_rules.items():
-        if fnmatch.fnmatchcase(path, pattern):
-            return PathAudit(path=path, verdict="unsafe", reason=reason)
-    for pattern, reason in safe_rules.items():
-        if fnmatch.fnmatchcase(path, pattern):
-            return PathAudit(path=path, verdict="safe", reason=reason)
+    rules = _rules_for(library, versions.get(library, ""))
+    for verdict in _BUCKETS:  # unsafe -> dual_use -> safe: strictest match wins
+        for pattern, reason in rules[verdict].items():
+            if fnmatch.fnmatchcase(path, pattern):
+                return PathAudit(path=path, verdict=verdict, reason=reason)
     return PathAudit(
         path=path,
         verdict="review",
         reason="not in the curated catalog; defer to human review (unknowns are not assumed safe)",
     )
 
 
-def _rules_for(library: str, version: str) -> tuple[dict[str, str], dict[str, str]]:
-    """Merge the library-agnostic ``_common`` rules with the version-matched library rules."""
-    unsafe: dict[str, str] = {}
-    safe: dict[str, str] = {}
+def _rules_for(library: str, version: str) -> dict[str, dict[str, str]]:
+    """Merge the library-agnostic ``_common`` rules with the version-matched library rules, per
+    bucket (``unsafe`` / ``dual_use`` / ``safe``)."""
+    merged: dict[str, dict[str, str]] = {bucket: {} for bucket in _BUCKETS}
     common = _load_ruleset(_COMMON_LIB, _COMMON_VERSION)
     version_dir = _match_version_dir(library, version)
     lib_rules = _load_ruleset(library, version_dir) if version_dir is not None else {}
     for ruleset in (common, lib_rules):
-        unsafe.update(ruleset.get("unsafe", {}))
-        safe.update(ruleset.get("safe", {}))
-    return unsafe, safe
+        for bucket in _BUCKETS:
+            merged[bucket].update(ruleset.get(bucket, {}))
+    return merged
 
 
 @lru_cache(maxsize=None)

packages/syft-restrict/src/syft_restrict/catalog/README.md

@@ -32,12 +32,17 @@ Each `catalog.json` is:
 ```json
 {
   "_about": "free-text note",
-  "unsafe": { "<dotted-path glob>": "why it is unsafe" },
-  "safe":   { "<dotted-path glob>": "why it is safe, plus a vague flag of any residual risk" }
+  "unsafe":   { "<dotted-path glob>": "why it is unsafe" },
+  "dual_use": { "<dotted-path glob>": "what the op is (terse; the category carries the caution)" },
+  "safe":     { "<dotted-path glob>": "why it is genuinely inert" }
 }
 ```
 
-`unsafe` = known disk/network/host-callback surface. `safe` = vetted pure-compute; its note also
-flags any *residual output-channel risk to review in combination* — kept deliberately vague, not a
-how-to (don't spell out abuse mechanics). Anything matched by neither defaults to `review` — never
-silently to `safe`.
+- `unsafe` = known disk/network/host-callback surface.
+- `dual_use` = a useful op that is mostly safe but can be **abused in combination** (`einsum`,
+  `softmax`, `where`, …). Allowed but flagged. The *category* is the caution, so keep each note a
+  terse description of what the op is — do **not** spell out abuse mechanics (no how-to).
+- `safe` = genuinely inert (constants, masks, module refs) with no residual channel of its own.
+
+A path is matched strictest-first (`unsafe` → `dual_use` → `safe`). Anything matched by none defaults
+to `review` — never silently to `safe`.

packages/syft-restrict/src/syft_restrict/catalog/flax/0.12/catalog.json

@@ -1,7 +1,7 @@
 {
-  "_about": "Risk rules for flax 0.12.x. 'unsafe' = disk/network/host-callback; 'safe' = vetted surface, whose note flags any residual risk to review in combination (kept deliberately vague). Cross-library rules in _common/default are merged in on top of these. This is advisory, not a proof.",
-  "safe": {
-    "flax.linen.Module": "Flax module base class — required to define a model; not a channel itself. Residual module-state risk (not host I/O) is widened by allow_base_class_attributes=True; keep that flag False to require explicit assignment."
+  "_about": "Risk rules for flax 0.12.x. 'unsafe' = disk/network/host-callback; 'dual_use' = useful surface that is mostly safe but can be abused in combination (the category itself is the caution, so notes stay terse and vague); 'safe' = genuinely inert. Cross-library rules in _common/default are merged in on top of these. This is advisory, not a proof.",
+  "dual_use": {
+    "flax.linen.Module": "Flax module base class; required to define a model. Keep allow_base_class_attributes=False to require explicit assignment."
   },
   "unsafe": {
     "flax.serialization.*": "Serializes model state to bytes / disk.",

packages/syft-restrict/src/syft_restrict/catalog/jax/0.11/catalog.json

@@ -1,28 +1,30 @@
 {
-  "_about": "Risk rules for jax 0.11.x. 'unsafe' = disk/network/host-callback; 'safe' = vetted pure-compute, whose note flags any residual output-channel risk to review in combination (kept deliberately vague). Cross-library rules in _common/default are merged in on top of these. This is advisory, not a proof.",
+  "_about": "Risk rules for jax 0.11.x. 'unsafe' = disk/network/host-callback; 'dual_use' = useful op that is mostly safe but can be abused in combination (the category itself is the caution, so notes stay terse and vague); 'safe' = genuinely inert (constants, masks, module refs). Cross-library rules in _common/default are merged in on top of these. This is advisory, not a proof.",
+  "dual_use": {
+    "jax.lax.rsqrt": "Reciprocal square root.",
+    "jax.nn.gelu": "GELU activation.",
+    "jax.nn.softmax": "Softmax activation; required for attention.",
+    "jax.numpy.array": "Materializes input into an array.",
+    "jax.numpy.bool_": "Cast to boolean.",
+    "jax.numpy.concatenate": "Joins arrays along an axis.",
+    "jax.numpy.cos": "Element-wise cosine.",
+    "jax.numpy.einsum": "Einstein-summation contraction; required for attention and projections.",
+    "jax.numpy.float32": "Cast to float32.",
+    "jax.numpy.mean": "Reduction to a mean.",
+    "jax.numpy.repeat": "Repeats elements along an axis.",
+    "jax.numpy.sin": "Element-wise sine.",
+    "jax.numpy.sqrt": "Element-wise square root.",
+    "jax.numpy.transpose": "Reorders axes.",
+    "jax.numpy.where": "Element-wise conditional select."
+  },
   "safe": {
     "jax.lax": "Module reference, present so deep-path calls (jax.lax.rsqrt) resolve. Does NOT permit calling other jax.lax members (exact-path match, not a glob).",
-    "jax.lax.rsqrt": "Reciprocal square root. Pure; some residual output-channel risk — review in combination.",
     "jax.nn": "Module reference, present so deep-path calls (jax.nn.softmax / gelu) resolve. Does NOT permit calling other jax.nn members.",
-    "jax.nn.gelu": "GELU activation. Pure; residual output-channel risk only.",
-    "jax.nn.softmax": "Softmax activation. Pure, required for attention; residual output-channel risk — review in combination.",
-    "jax.numpy.arange": "Integer range generator. Pure; produces constants, no secret enters.",
-    "jax.numpy.array": "Materializes input into an array. Pure; low residual risk — review in context.",
-    "jax.numpy.bool_": "Cast to boolean. Pure; residual output-channel risk only.",
-    "jax.numpy.concatenate": "Joins arrays along an axis. Pure; residual output-shaping risk — review in combination.",
-    "jax.numpy.cos": "Element-wise cosine. Pure; residual output-channel risk only.",
-    "jax.numpy.einsum": "Einstein-summation contraction. Pure math, required for attention and projections; very expressive, so it carries the most residual output-channel risk — bound output entropy at the enclave and review in combination.",
-    "jax.numpy.float32": "Cast to float32. Pure; residual output-channel risk only.",
-    "jax.numpy.mean": "Reduction to a mean. Pure; residual risk via the returned value only.",
-    "jax.numpy.ones": "Constant-ones tensor. Pure; scaffolding only.",
-    "jax.numpy.repeat": "Repeats elements. Pure; residual output-shaping risk — review in combination.",
-    "jax.numpy.sin": "Element-wise sine. Pure; residual output-channel risk only.",
-    "jax.numpy.sqrt": "Element-wise square root. Pure; some residual output-channel risk — review in combination.",
-    "jax.numpy.square": "Element-wise square. Pure; no channel of its own (a statistic amplifier, e.g. in RMSNorm).",
-    "jax.numpy.transpose": "Reorders axes. Pure; residual output-shaping risk only.",
-    "jax.numpy.tril": "Lower-triangular mask. Pure; builds attention masks (compositional, low bandwidth).",
-    "jax.numpy.triu": "Upper-triangular mask. Pure; as tril.",
-    "jax.numpy.where": "Element-wise conditional select. Pure; residual output-channel risk — review in combination."
+    "jax.numpy.arange": "Integer range generator; produces constants, no secret enters.",
+    "jax.numpy.ones": "Constant-ones tensor; scaffolding only.",
+    "jax.numpy.square": "Element-wise square; no channel of its own (a statistic amplifier, e.g. in RMSNorm).",
+    "jax.numpy.tril": "Lower-triangular mask; builds attention masks.",
+    "jax.numpy.triu": "Upper-triangular mask; as tril."
   },
   "unsafe": {
     "jax.debug.*": "Debug host callbacks / stdout (jax.debug.print, jax.debug.callback) — runs host Python and writes to the process stdout.",

packages/syft-restrict/tests/test_audit.py

@@ -29,18 +29,27 @@ def test_glob_allow_is_flagged_unsafe():
     assert "glob" in _entry(report, "jax.*").reason
 
 
-def test_vetted_pure_compute_paths_are_safe_with_explanations():
-    paths = ["jax.numpy.einsum", "jax.nn.softmax", "flax.linen.Module", "jax.lax"]
+def test_genuinely_inert_paths_are_safe():
+    # constants, masks, and module refs have no residual channel of their own.
+    paths = ["jax.numpy.arange", "jax.numpy.ones", "jax.numpy.tril", "jax.lax"]
     report = audit_allow_functions(paths)
     assert all(_entry(report, p).verdict == "safe" for p in paths)
-    assert all(_entry(report, p).reason for p in paths)  # safe entries also explained
-    # the explanation must convey residual risk to review, not just "it's fine" -- but stay vague
-    # (no abuse how-to): flag the risk with words like "residual" / "review", never a recipe.
-    einsum_reason = _entry(report, "jax.numpy.einsum").reason
-    assert "residual" in einsum_reason and "review" in einsum_reason
+    assert all(_entry(report, p).reason for p in paths)  # safe entries still explained
     assert report.ok  # only-safe list passes
 
 
+def test_dual_use_paths_are_flagged_between_safe_and_unsafe():
+    # useful ops that are mostly safe but abusable in combination land in dual_use, not safe.
+    paths = ["jax.numpy.einsum", "jax.nn.softmax", "jax.numpy.where", "flax.linen.Module"]
+    report = audit_allow_functions(paths)
+    assert all(_entry(report, p).verdict == "dual_use" for p in paths)
+    assert all(_entry(report, p).reason for p in paths)  # dual_use entries carry a terse note
+    # the category carries the caution, so the note stays vague -- no abuse how-to / recipe wording.
+    einsum_reason = _entry(report, "jax.numpy.einsum").reason
+    assert "encode" not in einsum_reason and "secret" not in einsum_reason
+    assert report.ok  # dual_use does not fail the report (allowed-but-flagged)
+
+
 def test_uncatalogued_path_is_deferred_to_review_without_assumptions():
     # An unknown path is neither safe nor unsafe: the audit makes no guess, it defers to a human.
     # This holds regardless of whether the path is importable — no source inspection happens.
@@ -67,11 +76,11 @@ def test_orbax_is_flagged_unsafe_without_a_version_dir():
 
 def test_report_format_has_sections_and_ok_flag():
     report = audit_allow_functions(
-        ["jax.numpy.einsum", "jax.profiler.start_server"]
+        ["jax.profiler.start_server", "jax.numpy.einsum", "jax.numpy.ones"]
     )
     text = report.format()
-    assert "UNSAFE" in text and "SAFE" in text
-    assert "ok=False" in text
+    assert "UNSAFE" in text and "DUAL-USE" in text and "SAFE" in text
+    assert "ok=False" in text  # the unsafe profiler entry fails the report
 
 
 def test_best_version_key_matches_on_dot_boundaries_only():