Skip to content

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.

16.0 KB
Raw Blame
# 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,
    )