Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Remote-code consent: CRITICAL always blocks; HIGH/MEDIUM need approval; unscannable fails closed."""
import os
from dataclasses import dataclass, field
from typing import Optional
from loggers import get_logger
from utils.account_context import is_owner_context
from utils.security.file_security import (
CRITICAL_FINDINGS,
MANAGED_REFUSED,
NOT_ON_SOURCE,
UNSCANNABLE,
)
from utils.security.remote_code_scan import (
CRITICAL,
HIGH,
MEDIUM,
RemoteCodeUnscannable,
config_declares_auto_map,
hub_config_path,
remote_code_config_paths,
remote_code_fingerprint,
repo_remote_code_files,
scan_remote_code_files,
)
logger = get_logger(__name__)
MANAGED_REMOTE_CODE_OVERRIDE = "UNSLOTH_STUDIO_ALLOW_MANAGED_REMOTE_CODE"
MANAGED_REMOTE_CODE_REFUSAL = (
"Remote code is off for managed accounts; the installation owner can enable it with "
f"{MANAGED_REMOTE_CODE_OVERRIDE}=1"
)
def managed_remote_code_refused() -> bool:
"""Remote code runs unconfined, so managed accounts need the owner's whole-install opt-in."""
if is_owner_context():
return False
return os.environ.get(MANAGED_REMOTE_CODE_OVERRIDE, "").lower() not in ("1", "true", "yes")
@dataclass
class RemoteCodeDecision:
"""Outcome of the consent gate for one (model, trust_remote_code) load."""
model_name: str
has_remote_code: bool
blocked: bool
fingerprint: Optional[str]
max_severity: Optional[str]
findings_summary: str
reason: str
findings: list = field(default_factory = list)
approvable: bool = True # False for a hard block (user cannot override)
block_cause: Optional[str] = None
def blocked_message(self, subject: str = "Model") -> str:
"""Only a scan that ran can have flagged anything; other blocks state their own cause."""
if self.max_severity:
return (
f"{subject} '{self.model_name}' ships custom code flagged as "
f"{self.max_severity} by the security scan. Review and approve it to proceed."
)
return self.findings_summary or self.reason
def response_payload(self) -> dict:
"""Machine-readable detail for the frontend. ``error_kind`` splits a user-approvable prompt (``remote_code_consent_required``) from a hard block (``remote_code_blocked``), whose ``block_cause`` says why."""
return {
"block_cause": self.block_cause,
"error_kind": (
"remote_code_consent_required" if self.approvable else "remote_code_blocked"
),
"model_name": self.model_name,
"has_remote_code": self.has_remote_code,
"approvable": self.approvable,
"fingerprint": self.fingerprint,
"max_severity": self.max_severity,
"findings": self.findings,
"findings_summary": self.findings_summary,
"reason": self.reason,
}
def _config_has_auto_map(
model_name: str,
hf_token: Optional[str] = None,
*,
load_subdirs = (),
) -> Optional[bool]:
"""A repo id ending in .gguf can still ship auto_map, so only a direct .gguf file is skipped; returns None when a config is unreadable, so the caller scans."""
if _is_direct_gguf_file_ref(model_name):
return False
configs = _load_remote_code_configs(model_name, hf_token, load_subdirs = load_subdirs)
if configs is None:
return None
# Check every nesting level: composite models declare auto_map on a sub-config.
if not any(
config_declares_auto_map(cfg or {}) or _config_declares_model_file(cfg) for cfg in configs
):
return False
return True
def _config_declares_model_file(cfg) -> bool:
"""MLX loaders exec a config's ``model_file`` like an ``auto_map`` entry."""
return isinstance(cfg, dict) and bool(cfg.get("model_file"))
def _is_direct_gguf_file_ref(model_name: str) -> bool:
"""Whether ``model_name`` names a specific ``.gguf`` FILE (llama.cpp) rather than a repo: a local ``.gguf`` path or a remote ``org/repo/.../file.gguf`` (>= 2 slashes). A bare ``org/name.gguf`` is a repo id that can still ship safetensors + auto_map, so it falls through to the scan."""
name = model_name or ""
if not name.lower().endswith(".gguf"):
return False
try:
from utils.paths import is_local_path
if is_local_path(name):
return True
except Exception:
pass
# Remote: a file reference is repo_id ("org/name") + filename => >= 2 slashes.
return name.count("/") >= 2
def _load_remote_code_configs(
model_name: str,
hf_token: Optional[str] = None,
*,
load_subdirs = (),
) -> Optional[list]:
"""Read every config that can declare ``auto_map`` (model/tokenizer/processor) as raw dicts. Returns the configs present (``[]`` when all 404, a definitive "no auto_map"), or None when one is unreadable (transient/auth) so the caller scans. The 404-vs-error split matters: real absence is "allow", unreadable is "unknown"."""
import json
from pathlib import Path
try:
from utils.paths import is_local_path, normalize_path
if is_local_path(model_name):
root = Path(normalize_path(model_name)).expanduser()
configs = []
for name in remote_code_config_paths(load_subdirs):
p = root.joinpath(*Path(name).parts)
if p.is_file():
configs.append(json.loads(p.read_text(encoding = "utf-8-sig")))
return configs
configs = []
for name in remote_code_config_paths(load_subdirs):
try:
p = hub_config_path(model_name, name, hf_token)
except Exception:
# Transient/auth failure is not "absent" -> fail closed to "unknown" so the caller scans.
return None
if p is not None:
configs.append(json.loads(Path(p).read_text(encoding = "utf-8-sig")))
# Every config was read or a genuine 404 -> an empty list is a definitive "no auto_map".
return configs
except Exception as exc:
logger.debug("auto_map check could not read config for %s: %s", model_name, exc)
return None
def _unscannable_decision(target: str, *, declared: bool, missing: bool) -> RemoteCodeDecision:
"""Fails closed either way; only a declaration read from a config says the repo has code."""
from utils.hf_probe import repo_not_found_message
from utils.hub_settings import active_source_label
if not declared and missing:
logger.warning(
"Blocking load of '%s': the repo was not found on %s, so it could not be scanned.",
target,
active_source_label(),
)
return RemoteCodeDecision(
target,
False,
True,
None,
None,
repo_not_found_message(target),
"blocked: repo not found on the model source",
approvable = False,
block_cause = NOT_ON_SOURCE,
)
logger.warning(
"Blocking trust_remote_code load of '%s': %s could not be downloaded and scanned.",
target,
"remote code present (auto_map) but it" if declared else "its configs or code",
)
return RemoteCodeDecision(
target,
True,
True,
None,
None,
(
"Remote code is present (auto_map) but could not be downloaded and scanned."
if declared
else f"Could not read this model from {active_source_label()} to check it for "
"custom code, so it could not be downloaded and scanned."
)
+ " Retry when the repo is reachable and the correct token is set.",
"blocked: remote code could not be scanned",
approvable = False,
block_cause = UNSCANNABLE,
)
def evaluate_remote_code_consent(
model_name: str,
hf_token: Optional[str] = None,
*,
trust_remote_code: bool,
approved_fingerprint: Optional[str] = None,
trusted_org: Optional[bool] = None,
subject: Optional[str] = None,
) -> RemoteCodeDecision:
"""Single-repo consent; thin wrapper over the for_targets form. ``trusted_org`` is accepted for backward compatibility but no longer changes the decision."""
return evaluate_remote_code_consent_for_targets(
[model_name],
hf_token,
trust_remote_code = trust_remote_code,
approved_fingerprint = approved_fingerprint,
subject = subject,
)
def _fingerprint_target_key(target: str) -> str:
"""Canonical namespace key for a target in the combined fingerprint."""
try:
import os
from pathlib import Path
from utils.paths import is_local_path, normalize_path
if is_local_path(target):
path = Path(normalize_path(target)).expanduser().resolve(strict = False)
return os.path.normcase(str(path))
except Exception:
return target
return target.lower()
def evaluate_remote_code_consent_for_targets(
targets,
hf_token: Optional[str] = None,
*,
trust_remote_code: bool,
approved_fingerprint: Optional[str] = None,
subject: Optional[str] = None,
load_subdirs_by_target = None,
) -> RemoteCodeDecision:
"""Scans every target as one unit under one fingerprint, so adapter code is never unreviewed; a prior approval skips the dialog, never the scan."""
targets = [t for t in dict.fromkeys(targets) if t]
primary = targets[0] if targets else ""
if not trust_remote_code:
return RemoteCodeDecision(
primary, False, False, None, None, "", "trust_remote_code disabled"
)
# Persistent per-user approval seeds the stored fingerprint so the scan below auto-approves an unchanged repo, skipping the prompt but never the scan. Gated so it cannot weaken the scan: the approval must match the current ruleset and a resolvable commit SHA the approved revision, and the fingerprint and the CRITICAL block still apply.
caller_approved_fingerprint = approved_fingerprint
if subject:
from utils.security import remote_code_approvals
_ak = remote_code_approvals.approval_target_key(targets)
_stored = remote_code_approvals.lookup(subject, _ak)
if _stored is not None and _stored.scanner_version == remote_code_approvals.SCANNER_VERSION:
_sha = remote_code_approvals.resolve_combined_sha(targets, hf_token)
if _sha is None or _sha == _stored.commit_sha:
approved_fingerprint = approved_fingerprint or _stored.fingerprint
# Gather executable .py from every target that ships auto_map. A definitively auto_map-free target contributes nothing, an unreadable config is scanned anyway, and if ANY target's code is present but unscannable the whole load fails closed.
combined: dict = {}
has_remote_code = False
load_subdirs_by_target = load_subdirs_by_target or {}
for target in targets:
load_subdirs = tuple(load_subdirs_by_target.get(target, ()))
scan_kwargs = {"load_subdirs": load_subdirs} if load_subdirs else {}
declares_code = _config_has_auto_map(target, hf_token, **scan_kwargs)
if declares_code is False:
continue
try:
files = repo_remote_code_files(target, hf_token = hf_token, **scan_kwargs)
except RemoteCodeUnscannable:
from utils.hf_probe import hub_repo_not_found
from utils.hub_settings import MODELSCOPE, active_source
from utils.paths import is_local_path
from utils.utils import hf_cache_snapshot_dir_for_repo
declared = declares_code is True
on_modelscope = active_source() == MODELSCOPE
missing = (
(on_modelscope or not declared)
and not is_local_path(target)
and hub_repo_not_found(target, hf_token)
)
# Hugging Face's 404 may only mean private to this caller, so only ModelScope's counts.
snapshot = hf_cache_snapshot_dir_for_repo(target) if missing and on_modelscope else None
if snapshot is None:
return _unscannable_decision(target, declared = declared, missing = missing)
# The hub falls back to this snapshot on a 404, so judge what it holds.
if _config_has_auto_map(str(snapshot), hf_token, **scan_kwargs) is False:
continue
try:
files = repo_remote_code_files(str(snapshot), hf_token = hf_token, **scan_kwargs)
except RemoteCodeUnscannable:
return _unscannable_decision(target, declared = True, missing = False)
has_remote_code = True
# Namespace filenames by (casing-normalized) target so two repos' same-named files stay distinct.
target_key = _fingerprint_target_key(target)
for filename, body in files.items():
combined[f"{target_key}\0{filename}"] = body
if not has_remote_code:
return RemoteCodeDecision(
primary, False, False, None, None, "", "no auto_map; trust_remote_code is a no-op"
)
if not combined:
# auto_map declared but no executable .py (e.g. GGUF repo) -> nothing to scan -> allow.
return RemoteCodeDecision(
primary,
False,
False,
None,
None,
"",
"auto_map declared but no executable code present; trust_remote_code is a no-op",
)
if managed_remote_code_refused():
return RemoteCodeDecision(
primary,
True,
True,
None,
None,
"",
MANAGED_REMOTE_CODE_REFUSAL,
approvable = False,
block_cause = MANAGED_REFUSED,
)
result = scan_remote_code_files(combined)
fingerprint = remote_code_fingerprint(combined)
sev = result.max_severity
# CRITICAL is never approvable; a fingerprint pins approval for lower severities only.
approvable = sev != CRITICAL
approved = (
approvable and approved_fingerprint is not None and approved_fingerprint == fingerprint
)
if sev == CRITICAL:
blocked, reason = True, "blocked: scan found CRITICAL patterns"
elif approved:
blocked, reason = False, "approved by fingerprint"
elif sev == HIGH:
# HIGH is user-approvable but must pin the fingerprint via the dialog.
blocked, reason = True, "blocked: scan found HIGH patterns; approval required"
elif sev == MEDIUM:
# MEDIUM (e.g. a big embedded base64 blob) also pins approval like HIGH, so a direct API caller cannot run flagged code by just setting trust_remote_code=True.
blocked, reason = True, "blocked: scan found MEDIUM patterns; approval required"
else:
blocked, reason = False, "allowed: no high-risk patterns"
if blocked:
logger.warning(
"Blocking trust_remote_code load of '%s': scan severity %s (fingerprint %s)",
primary,
sev,
fingerprint[:12],
)
# Persist a genuine user approval (a matching fingerprint from the caller, not a cache seed) under the current scanner version, so the repo is not re-prompted until code or ruleset changes.
if approved and subject and caller_approved_fingerprint == fingerprint:
from utils.security import remote_code_approvals
remote_code_approvals.record(
subject,
remote_code_approvals.approval_target_key(targets),
commit_sha = remote_code_approvals.resolve_combined_sha(targets, hf_token),
fingerprint = fingerprint,
max_severity = sev,
scanner_version = remote_code_approvals.SCANNER_VERSION,
)
return RemoteCodeDecision(
primary,
True,
blocked,
fingerprint,
sev,
result.summary(),
reason,
findings = result.findings_payload(),
approvable = approvable,
block_cause = CRITICAL_FINDINGS if sev == CRITICAL else None,
)