23s2s

✏️ Editing: phpinfo_utils.py

# Copyright © Cloud Linux GmbH & Cloud Linux Software, Inc 2010-2021 All Rights Reserved
#
# Licensed under CLOUD LINUX LICENSE AGREEMENT
# http://cloudlinux.com/docs/LICENSE.TXT
import dataclasses
import logging
import pwd
import re
import secrets
import subprocess
import time
from contextlib import contextmanager
from pathlib import Path
from urllib.parse import urlsplit, urlunsplit

import requests
import urllib3
from clcommon.clpwd import drop_privileges
from clcommon.cpapi import docroot
from requests.adapters import HTTPAdapter
from requests.exceptions import ChunkedEncodingError
from secureio import disable_quota
from urllib3.exceptions import ReadTimeoutError

from xray import gettext as _
from xray.internal import exceptions, probe_targets, utils
from xray.internal.constants import canonical_variants, is_allowed_ini_path
from xray.internal.user_plugin_utils import verify_user_owns_domain

logger = logging.getLogger(__name__)

# long timeout is set because our tested
# sites may be really slow
TIMEOUT: int = 10
# Connect phase only, kept well under TIMEOUT. Every candidate is an address
# configured on THIS machine, so a connect that does not complete promptly is a
# firewall DROP on a local address, not a slow site. Without splitting it out,
# `timeout=TIMEOUT` covers connect AND read, so a handful of DROP-ed interface
# addresses could spend the whole sweep on connects that will never succeed.
_CONNECT_TIMEOUT: int = 2
# Wall-clock ceiling for the WHOLE candidate sweep. TIMEOUT is the budget for one
# genuinely slow site; without a shared ceiling the sweep multiplies it by
# candidates x schemes, and the temporary probe file sits in the tenant's docroot
# for that entire window (the sweep runs inside `_temporary_phpinfo_file`).
_SWEEP_BUDGET_SECONDS: int = 25
# The phpinfo probe targets a vhost hosted on THIS machine. The hostname is
# tenant-controlled and resolves via public DNS, so following DNS would let a
# tenant repoint their domain at an arbitrary host and turn the root daemon's
# probe into an SSRF primitive. Never resolve the hostname: connect to an
# address taken from `probe_targets.connect_candidates` (loopback, or an address
# verified to be configured on THIS machine) and preserve the original Host
# header so the local webserver still routes to the right vhost.
#
# Loopback alone is not enough: DirectAdmin and cPanel bind each vhost to a
# specific address while the server listens globally, so a loopback request
# lands in the 127.0.0.1 address bucket, matches no vhost there and is answered
# by that bucket's default vhost -> the probe file 404s. See probe_targets.
_PIN_ADDRESS: str = probe_targets.LOOPBACK_ADDRESS
# Cap the response body at 1 MiB. The phpinfo payload we ship in
# `_temporary_phpinfo_file` is well under 1 KiB, so 1 MiB leaves a
# generous margin while preventing a tenant-controlled webserver from
# inflating the root daemon's RSS via an unbounded response body.
_MAX_RESPONSE_BYTES: int = 1024 * 1024
_CHUNK_BYTES: int = 8192
HEADERS = {
    'User-Agent': 'Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2.13) '
    'Gecko/20101209 CentOS/3.6-2.el5.centos Firefox/3.6.13'
}

def _unreachable_message(error) -> str:
    """The user-facing "website not accessible" text.

Shared by every terminal probe failure path so the message the tenant sees —
    and its translation — is identical regardless of which failure produced it.
    """
    return _(
        "Unable to detect php version for website "
        "because it is not accessible. "
        "Try again and contact an administrator if the issue persists. "
        "Original error: %s. "
    ) % str(error)

class WebsiteNotResponding(exceptions.XRayManagerError):
    """Nothing usable answered the probe on this connect target and scheme.

``url`` and ``details`` drive the caller's scheme + connect-candidate
    fallback. But this exception can also ESCAPE get_php_configuration — when
    every candidate failed on both schemes — and the CLI then renders it with
    ``print(e)`` (console_utils/base_app.py), i.e. XRayError.__str__, which reads
    attributes that ONLY XRayError.__init__ sets. So the base MUST be initialised:
    without it `str(e)` raised AttributeError('type_flag') and the tenant got an
    unhandled traceback instead of the error message.

The message is the same "website not accessible" text every other terminal
    probe failure uses, so a caller that lets this escape produces exactly the
    output an unreachable site produced before connect failures were routed
    through this class.
    """

def __init__(self, url, details):
        self.url = url
        self.details = details
        super().__init__(_unreachable_message(details))

class WebsiteTooSlow(exceptions.XRayManagerError):
    """A webserver accepted the connection on this address but did not finish
    responding within the read timeout.

Kept distinct from WebsiteNotResponding (nothing answered at all) because the
    two mean different things in a support log. It is NOT treated as terminal: a
    timeout says a webserver answered, but says nothing about WHICH vhost did —
    and on the very topology this module exists for, the loopback connection is
    accepted by the address bucket's DEFAULT vhost. Aborting the sweep there would
    reproduce the CLOS-6825 symptom whenever that default vhost is slow, so the
    sweep advances and `_SWEEP_BUDGET_SECONDS` (not terminality) is what stops a
    slow site from multiplying the stall across candidates.
    """

# The keys `_temporary_phpinfo_file`'s payload always emits. A body missing any of
# them is not this probe's output.
_REQUIRED_PROBE_KEYS = frozenset({'phpversion', 'ini_scan_dir', 'php_sapi_name', 'include_path'})

class ProbeBodyNotUnderstood(exceptions.XRayManagerError):
    """The fetch succeeded, but the body is not this probe's output.

A 200 does NOT prove the right vhost answered. On a per-IP-vhost host the
    address bucket's default vhost may carry a front controller or catch-all that
    serves its own page with status 200 instead of 404 — so the sweep must treat
    an unparseable body as "this candidate failed" and keep going, or it stops on
    a wrong-but-successful answer before ever reaching the account's real vhost
    address (the CLOS-6825 symptom, from the other direction).

Raised instead of the bare ValueError/TypeError that `_parse_configuration`
    used to leak: those are not XRayErrors, so the CLI could not render them.
    """

class IniScanDirRejected(exceptions.XRayError, ValueError):
    """The probe's ini_scan_dir did not pass validation for the privileged write.

An XRayError so the CLI can RENDER it. This used to be a bare ValueError,
    which `console_utils/base_app.py` neither prints nor reports: it catches only
    XRayError, so a rejected ini_scan_dir surfaced as an unhandled traceback and
    never reached `capture_exception`. That is what made CLOS-6825 look unfixed
    after its connect-address fix shipped — the probe succeeded on the vhost's own
    address, this gate discarded the result, and the newest renderable line left in
    manager.log was the UNRELATED "failed against 127.0.0.1" INFO from the sweep's
    first candidate. Support and the customer both read that as the original 404
    bug persisting.

Deliberately XRayError and NOT XRayManagerError, even though every other error
    on this path is the latter. `manager/cpanel.get_domain_info` wraps
    `check_domain` — which is where `absolute_ini_scan_dir` is evaluated — in
    `except XRayManagerError` and retries the whole thing against
    `resolve_alias(domain)`. As an XRayManagerError this would be swallowed there:
    the probe would re-run (a second temp-file write into a docroot plus a second
    connect sweep) and the surfaced error would be the alias attempt's, not the
    real cause — reintroducing the exact misdiagnosis this class exists to end.
    XRayError renders identically (`XRayError.__str__` does the work; base_app
    catches XRayManagerExit then XRayError) and the only other broad
    `except XRayError`, in `manager/base.stop`, re-raises anything without the
    `_internal_missing_domain` marker.

Still a ValueError as well: callers and tests that predate this class treat a
    rejected ini_scan_dir as one, and `manager/base.get_ini_path` catches
    ValueError around the neighbouring ini properties.
    """

def _reject_ini_scan_dir(username: str, detail: str) -> IniScanDirRejected:
    """Log the technical detail, and return an error that does NOT carry it.

``detail`` keeps the exact wording these rejections have always had — a support
    engineer greping manager.log for "outside allowed paths" or "not bound to user"
    still finds it, and now finds it as a log line of its own rather than only
    inside a traceback.

It deliberately does NOT reach the returned exception. ``ini_scan_dir`` is
    attacker-controlled (the probe body is served from the tenant's own docroot, and
    on a CGI/FastCGI SAPI PHP_INI_SCAN_DIR is reachable from the vhost's
    environment), and the message is rendered to an unprivileged tenant by the panel
    plugin. Echoing the resolved path back — and distinguishing "does not resolve to
    an existing dir" from "outside allowed paths" from "not bound to user" — would
    make the root daemon a path-existence oracle for arbitrary absolute paths. So
    every reason yields ONE uniform message and the detail stays in the root-only
    log. Same reasoning as the missing-vs-foreign domain unification in
    `user_plugin_utils.user_mode_verification`.
    """
    logger.warning('Rejected probe-reported ini_scan_dir for user %s: %s', username, detail)
    return IniScanDirRejected(
        _(
            "Unable to detect php configuration for website "
            "because its PHP configuration directory is not supported. "
            "Contact an administrator if the issue persists. "
        )
    )

class _BoundedResponse:
    """A drop-in replacement exposing `.text` from a bounded streamed read."""

__slots__ = ('text',)

def __init__(self, text: str):
        self.text = text

def _pinned_netloc(address: str, port: int | None) -> str:
    """Build the netloc for a pinned connect target, bracketing IPv6 literals."""
    host = f'[{address}]' if ':' in address else address
    return host if port is None else f'{host}:{port}'

class _LocalAddressPinnedAdapter(HTTPAdapter):
    """requests adapter that pins every connection to one local address.

The vhost is hosted on this machine; we must not follow the
    tenant-controlled public-DNS record. We rewrite the connect target to
    ``pin_address`` — loopback, or an address the caller has already verified is
    configured on this machine — while keeping the original hostname in the Host
    header so the local webserver routes to the correct vhost. The TLS SNI/cert
    mismatch that results is tolerated because the caller already requests
    verify=False.
    """

def __init__(self, pin_address: str = _PIN_ADDRESS, *args, **kwargs):
        self.pin_address = pin_address
        super().__init__(*args, **kwargs)

def send(self, request, **kwargs):
        split = urlsplit(request.url)
        original_host = split.hostname
        if original_host is not None:
            request.headers['Host'] = split.netloc
            request.url = urlunsplit(split._replace(netloc=_pinned_netloc(self.pin_address, split.port)))
        return super().send(request, **kwargs)

def _pinned_session(pin_address: str = _PIN_ADDRESS) -> requests.Session:
    session = requests.Session()
    adapter = _LocalAddressPinnedAdapter(pin_address)
    session.mount('http://', adapter)
    session.mount('https://', adapter)
    return session

@utils.retry_on_exceptions(3, [ChunkedEncodingError])
def _request_url(url, pin_address: str = _PIN_ADDRESS, read_timeout: float = TIMEOUT):
    """
    Fetch ``url``, connecting to ``pin_address`` instead of resolving the host.

``read_timeout`` lets the caller shrink the read budget for one attempt so a
    sweep over several candidates stays inside `_SWEEP_BUDGET_SECONDS`.

retry on:
     - ChunkedEncodingError -> sometimes error happens due to network issues/glitch
    """
    # Defence in depth for the F-08 property. `connect_candidates` already
    # validated every address it returns, but THIS is the function that opens the
    # socket, so re-check here rather than resting the invariant on caller
    # discipline alone — a future caller passing an unvalidated address (or a
    # default that drifts) must not be able to reach off-box.
    if pin_address not in probe_targets.local_addresses():
        raise exceptions.XRayManagerError(
            _unreachable_message(f'refusing to probe {pin_address}: not an address configured on this server')
        )
    try:
        # allow_redirects=False: the probe targets a fixed temporary file on
        # the tenant's own vhost, so a redirect is never legitimate. Following
        # one would re-run the loopback-pinned adapter with a tenant-chosen
        # port+path, turning the root probe into an SSRF primitive against
        # arbitrary loopback services.
        with (
            _pinned_session(pin_address) as session,
            session.get(
                url,
                timeout=(_CONNECT_TIMEOUT, read_timeout),
                verify=False,
                headers=HEADERS,
                stream=True,
                allow_redirects=False,
            ) as response,
        ):
            if response.is_redirect or 300 <= response.status_code < 400:
                # A redirect on the probe is never legitimate to follow (the
                # pinned adapter would send the tenant-chosen loopback
                # port+path). Treat it as "this scheme is not usable" so
                # get_php_configuration retries the probe directly over
                # https, where a force-HTTPS vhost serves it with 200.
                raise WebsiteNotResponding(url, details=f'probe returned redirect status {response.status_code}')
            response.raise_for_status()
            buf = bytearray()
            for chunk in response.iter_content(chunk_size=_CHUNK_BYTES):
                if not chunk:
                    continue
                if len(buf) + len(chunk) > _MAX_RESPONSE_BYTES:
                    raise exceptions.XRayManagerError(
                        _("phpinfo response for %s exceeds %d bytes; refusing to buffer attacker-controlled body.")
                        % (url, _MAX_RESPONSE_BYTES)
                    )
                buf.extend(chunk)
            # NB: do not use response.apparent_encoding here — with stream=True
            # the body is already consumed by iter_content(), so accessing it
            # touches response.content and raises RuntimeError. The buffered
            # bytes are decoded with errors='replace', so utf-8 is a safe
            # fallback when the server sends no charset in Content-Type.
            encoding = response.encoding or 'utf-8'
            try:
                text = buf.decode(encoding, errors='replace')
            except LookupError:
                # response.encoding comes from the tenant-controlled
                # Content-Type charset; an unknown codec name (e.g.
                # charset=bogus) raises LookupError that errors='replace'
                # does not catch. requests' own .text falls back here, so
                # mirror that and decode as utf-8.
                text = buf.decode('utf-8', errors='replace')
    except (requests.exceptions.ConnectionError, ConnectionError) as e:
        # really strange behavior of requests that wrap
        # errors inside of ConnectionError
        #
        # NB: requests.exceptions.ConnectionError does NOT subclass the builtin
        # ConnectionError (it descends from RequestException -> OSError), so
        # naming only the builtin here let every connect-level failure fall
        # through to the generic RequestException branch below. That turned a
        # closed port into a terminal XRayManagerError instead of the
        # WebsiteNotResponding this branch exists to raise, so the https retry in
        # the caller never ran for an https-only vhost. Catch both.
        if e.args and isinstance(e.args[0], ReadTimeoutError):
            # We read the body with stream=True + iter_content, and requests
            # wraps a urllib3 ReadTimeoutError raised MID-STREAM in its own
            # ConnectionError (models.py iter_content: `except ReadTimeoutError
            # as e: raise ConnectionError(e)`). So a site that stalls part-way
            # through the body arrives here, not in the ReadTimeout branch below,
            # and it means the same thing: the site answered, it is just slower
            # than TIMEOUT. Terminal, and an XRayError so the CLI can render it —
            # a bare `raise` here would escape base_app's `except XRayError` and
            # print a traceback instead of the message.
            raise WebsiteTooSlow(_unreachable_message(e))
        raise WebsiteNotResponding(url, details=str(e))
    except requests.exceptions.ReadTimeout as e:
        # Timed out waiting for the response headers. Same terminal meaning as
        # the mid-body timeout above — see WebsiteTooSlow.
        raise WebsiteTooSlow(_unreachable_message(e))
    except requests.RequestException as e:
        raise exceptions.XRayManagerError(_unreachable_message(e))

return _BoundedResponse(text)

@contextmanager
def _temporary_phpinfo_file(username: str, document_root: Path):
    php_file_contents = """
<?php

$php_ini_scan_dir = getenv("PHP_INI_SCAN_DIR");
if(!empty($php_ini_scan_dir)) {
  // get first non-empty path
  $php_ini_scan_dir = array_values(array_filter(explode(":", $php_ini_scan_dir)))[0];
}

echo "phpversion=" . phpversion() . "\n";
echo "ini_scan_dir=" . ($php_ini_scan_dir ? $php_ini_scan_dir: PHP_CONFIG_FILE_SCAN_DIR) . "\n";
echo "php_sapi_name=". php_sapi_name() . "\n";
echo "include_path=" . get_include_path() . "\n";

"""
    php_file_name = f'xray_info_{secrets.token_hex(8)}.php'
    php_file_path = document_root / php_file_name
    with drop_privileges(username), disable_quota():
        php_file_path.write_text(php_file_contents)

try:
        yield php_file_name
    finally:
        php_file_path.unlink()

@dataclasses.dataclass
class PhpConfiguration:
    # 'user'
    username: str
    # '8.3.30'
    phpversion: str
    # '/etc/php.d/'
    ini_scan_dir: str
    # 'cgi-fcgi'
    php_sapi_name: str
    # '.:/opt/alt/php80/usr/share/pear'
    include_path: str
    # The account's REAL provisioned PHP HANDLER, as known to the panel — kept
    # in its FULL, distro-carrying shape (cPanel domain['version'] 'ea-php80',
    # Plesk resolve_lsphp_version(handler) 'plesk-php80'/'alt-php80', DirectAdmin
    # opts[...]['ver'] 'php80', custom domain_conf.php.version '80'). This is a
    # SERVER-side trust anchor, distinct from `phpversion` which is parsed from
    # the tenant-served probe body and is therefore attacker-controlled. NOT
    # stripped to a bare number: the distro family is exactly what binds branch
    # (3) to the user's OWN per-distro+version INI_LOCATION (a same-number dir of
    # a DIFFERENT distro family must be rejected). None — or a bare number that
    # carries no distro — disables the global per-version accept branch.
    trusted_php_version: str | None = None

@property
    def short_php_version(self) -> str:
        return ''.join(self.phpversion.split('.')[:2])

def get_full_php_version(self, default_prefix: str):
        if '/opt/alt' in self.include_path:
            return f"alt-php{self.short_php_version}"
        return f"{default_prefix}{self.short_php_version}"

@property
    def absolute_ini_scan_dir(self):
        # the only directory that we expect to be changed in cagefs
        # is our conf link which is managed by selectorctl
        if 'link/conf' in self.ini_scan_dir:
            resolved = _resolve_ini_path_in_cagefs(self.username, self.ini_scan_dir)
        else:
            resolved = self.ini_scan_dir

if resolved:
            # Resolve symlinks/.. and require the directory to exist, so a
            # symlink or traversal escape cannot point the privileged xray.ini
            # write outside the realpath we then bind to the tenant.
            try:
                resolved = str(Path(resolved).resolve(strict=True))
            except (OSError, RuntimeError):
                raise _reject_ini_scan_dir(
                    self.username, f'ini_scan_dir does not resolve to an existing dir: {resolved!r}'
                )
            if not is_allowed_ini_path(resolved):
                raise _reject_ini_scan_dir(self.username, f'ini_scan_dir outside allowed paths: {resolved!r}')
            # The probe response is served from the tenant's own docroot, so
            # ini_scan_dir is tenant-controlled. ALLOWED_INI_PREFIXES is a
            # prefix-only allowlist that ALSO admits global root-owned dirs
            # (/etc/php.d, /etc/cl.php.d, /usr/share/cagefs[-skeleton],
            # /opt/cpanel/ea-php*, ...) and the shared CageFS root
            # (/var/cagefs/) — accepting any of those unconditionally would let a
            # tenant steer the root-performed xray.ini write into a dir loaded by
            # all PHP or another tenant's jail. Default-deny: accept ONLY paths
            # provably tied to self.username (own CageFS subtree, own per-domain
            # ini dir) OR the EXACT global INI_LOCATION of the account's TRUSTED,
            # full provisioned handler (distro+version), not the probe's and not
            # a distro-blind same-number match.
            if not _ini_scan_dir_belongs_to_user(self.username, resolved, self.trusted_php_version):
                raise _reject_ini_scan_dir(
                    self.username, f'ini_scan_dir not bound to user {self.username!r}: {resolved!r}'
                )
        return resolved

@property
    def is_php_fpm(self):
        return self.php_sapi_name == 'fpm-fcgi'

def _parse_configuration(username: str, response: str, trusted_php_version: str | None = None) -> PhpConfiguration:
    """Parse the probe payload, or raise ProbeBodyNotUnderstood.

Deliberately lenient per line and strict overall: unusable lines are skipped
    and only `_REQUIRED_PROBE_KEYS` decides whether this really is our payload.
    That single gate replaces three ways this used to leak a non-XRayError the CLI
    could not render — `line.split('=')` raising ValueError on a line with no `=`
    (a default vhost's HTML) or with two (`include_path=.:/a=b`), and
    `PhpConfiguration(**config)` raising TypeError on an unexpected key.
    """
    config = {}
    for line in response.split('\n'):
        key, separator, value = line.partition('=')
        # partition, not split: the value may legitimately contain '=' (an
        # include_path entry), and only the first '=' separates key from value.
        if not separator:
            continue
        key = key.strip()
        # Ignore anything outside the payload's own keys rather than forwarding it
        # to the dataclass, which would raise TypeError on an unexpected keyword.
        if key in _REQUIRED_PROBE_KEYS:
            config[key] = value.strip()

missing = _REQUIRED_PROBE_KEYS - config.keys()
    if missing:
        raise ProbeBodyNotUnderstood(_unreachable_message(f'probe response is missing {", ".join(sorted(missing))}'))

return PhpConfiguration(username=username, trusted_php_version=trusted_php_version, **config)

# Root of the shared CageFS tree. A resolved dir under here is the tenant's own
# area only when it sits inside /var/cagefs/<prefix>/<username>/...
_CAGEFS_ROOT = '/var/cagefs/'

# Roots of the per-domain scan dirs an OPERATOR can put in PHP_INI_SCAN_DIR, all
# of the shape <root>/<account>/php/<vhost>, where <account> is the same account
# passed as self.username to get_php_configuration.
#
# These are NOT panel-owned paths — no stock cPanel, DirectAdmin, Plesk or
# CloudLinux component creates them. They are a hoster's own layout, exposed to
# PHP through LiteSpeed's PHP external-app Environment, where LSWS expands
# $VH_USER / $VH_NAME (e.g. PHP_INI_SCAN_DIR=/etc/configs/users/$VH_USER/php/
# $VH_NAME). The prefix is therefore operator-chosen and the set below is a list
# of layouts we have actually seen, not a derivable rule:
#
#   /etc/configs/users/  the layout phpinfo mode was BUILT for (CLPRO-1574,
#                        Jan 2024, quoted verbatim in that ticket)
#   /etc/users/          kept: it has been allowlisted since 0.6-47 and removing
#                        an accepted path would be its own regression
#
# <vhost> is the LiteSpeed vhost name = $VH_NAME = the Apache ServerName, so with
# DirectAdmin's stock template (`ServerName www.<domain>`) the reporter's dir is
# /etc/configs/users/przemek2/php/www.przemek2.vot.pl. Nothing here matches that
# segment against a domain: it is opaque, and may be <domain>, www.<domain>, or
# either shape of a subdomain.
#
# Why '/etc/users/' alone was not enough — the actual CLOS-6825 round-2 root
# cause: phpinfo mode exists BECAUSE of CLPRO-1574, i.e. to support exactly this
# hoster's /etc/configs/users layout, and back then nothing constrained the dir at
# all. When ALLOWED_INI_PREFIXES arrived in 0.6-47 (CLPRO-3059 NEW-F6) it picked up
# '/etc/users/' — a value that appears in CLPRO-1574 only as a TEST FIXTURE
# (`ini_scan_dir=/etc/users/admin/php/www.website.local`, f2a7c55) — and never the
# real path. So the one layout the feature was written for stopped being accepted.
# 0.6-50's loopback pin then masked it for three releases by 404ing the probe
# before it could report any dir at all; fixing that in round 1 is what finally
# surfaced this.
#
# Every root here is PER-TENANT, whatever the leaf's ownership turns out to be:
# containment is always checked against <root>/<self.username> with a separator
# boundary, so another account's subtree — including a <self.username>EVIL
# lookalike — is rejected, and the write-time inode binding
# (types.Task._ini_dir_validator) keeps the pinned dir inside that same subtree.
_PER_DOMAIN_INI_ROOTS = ('/etc/users/', '/etc/configs/users/')

# Per-distro INI_LOCATION templates, keyed by the TRUSTED handler's distro
# family. Each maps the FULL handler 'family-phpNN' (or DirectAdmin's 'phpNN')
# to the ONE global, root-owned, server-wide INI_LOCATION that the user's
# provisioned per-distro+version PHP scans (see docs/design/xray-ini-placement.md
# "Server-wide locations" and base.py VERSIONS / the per-panel VERSIONS_* maps,
# which carry the same alt-php→/opt/alt/phpNN/link/conf,
# ea-php→/opt/cpanel/ea-phpNN/root/etc/php.d, plesk-php→/opt/plesk/php/X.Y/etc/php.d,
# php→/usr/local/phpNN/lib/php.conf.d mappings).
#
# The expected dir is selected BY the trusted handler's distro family, never by
# the dir's own family — so a tenant whose trusted handler is ea-php80 maps ONLY
# to /opt/cpanel/ea-php80/root/etc/php.d, and a probe reporting the same-number
# alt-php dir /opt/alt/php80/link/conf does NOT match (cross-distro spoof closed).
#
# A handler that carries no distro family (a bare number, e.g. custom's
# domain_conf.php.version '80') matches no template and yields None, so branch
# (3) default-denies for it — the expected dir cannot be uniquely derived.
#
# The cagefs skeleton/mirror roots (/usr/share/cagefs/.cpanel.multiphp/...,
# /usr/share/cagefs-skeleton/...) and any other-shape subdir (xray.so modules,
# /opt/alt/phpNN/etc/php.d, ...) are excluded for free: they are not equal to the
# single derived INI_LOCATION, so the equality gate rejects them (default-deny).
_HANDLER_INI_LOCATION_TEMPLATES = (
    # cPanel ea-php: 'ea-php80' -> /opt/cpanel/ea-php80/root/etc/php.d
    (re.compile(r'^ea-php(?P<v>\d{2})$'), '/opt/cpanel/ea-php{v}/root/etc/php.d'),
    # alt-php (cl.selector / Plesk lsphp): 'alt-php80' -> /opt/alt/php80/link/conf
    (re.compile(r'^alt-php(?P<v>\d{2})$'), '/opt/alt/php{v}/link/conf'),
    # Plesk native: 'plesk-php80' -> /opt/plesk/php/8.0/etc/php.d (dotted X.Y)
    (re.compile(r'^plesk-php(?P<maj>\d)(?P<min>\d)$'), '/opt/plesk/php/{maj}.{min}/etc/php.d'),
    # DirectAdmin native / usr-local: 'php80' -> /usr/local/php80/lib/php.conf.d
    (re.compile(r'^php(?P<v>\d{2})$'), '/usr/local/php{v}/lib/php.conf.d'),
)

def _expected_ini_location(trusted_handler: str | None) -> str | None:
    """Build the single global INI_LOCATION for a TRUSTED, FULL PHP handler.

``trusted_handler`` is the account's REAL provisioned handler carrying its
    distro family ('ea-php80', 'alt-php80', 'plesk-php80', 'php80'). Returns the
    ONE server-wide per-distro+version dir that handler's PHP scans, keyed BY the
    distro family — so the derived dir's family always equals the trusted
    handler's family, never the family of whatever dir the probe reported.

Returns None when ``trusted_handler`` is empty or carries no distro family
    (a bare number such as custom's '80'): the expected dir cannot be uniquely
    derived, so the caller default-denies the global per-version accept branch.
    """
    if not trusted_handler:
        return None
    for pattern, template in _HANDLER_INI_LOCATION_TEMPLATES:
        match = pattern.match(str(trusted_handler))
        if match:
            return template.format(**match.groupdict())
    return None

def _relative_to_root(root: str, resolved: str) -> str | None:
    """``resolved`` relative to ``root`` ('' for root itself), or None if outside.

The trailing-separator boundary stops /var/cagefs/01/aliceEVIL from being
    treated as inside alice's /var/cagefs/01/alice subtree.

``resolved`` is a realpath, so ``root`` is matched in its canonical spelling
    as well as the literal one: on a host where /var/cagefs is a symlink (the
    documented relocation layout) the tenant's dir resolves to /home/cagefs/...,
    which the literal root would miss (CLOS-7045).
    """
    for candidate in canonical_variants(root):
        candidate = candidate.rstrip('/')
        if resolved == candidate:
            return ''
        if resolved.startswith(candidate + '/'):
            return resolved[len(candidate) + 1 :]
    return None

def _is_within(root: str, resolved: str) -> bool:
    """True if ``resolved`` is ``root`` itself or a path strictly inside it."""
    return _relative_to_root(root, resolved) is not None

def _is_own_per_domain_ini_dir(username: str, resolved: str) -> bool:
    """True if ``resolved`` is inside ``username``'s OWN per-domain ini scan dir.

One helper for every gate that has to answer this question — the phpinfo
    binding gate below, `manager/custom.py._validate_ini_path` and
    `types.Task._ini_dir_validator`'s write-time inode binding. They each used to
    inline the same `/etc/users/<user>` containment check, which is precisely how
    /etc/configs/users ended up supported by none of them: an operator layout has
    to be added in one place, not three. Compare the first relative path segment
    to ``username``; never append caller data to a root before canonicalizing it.
    """
    for root in _PER_DOMAIN_INI_ROOTS:
        rel = _relative_to_root(root, resolved)
        if rel is not None and rel.partition('/')[0] == username:
            return True
    return False

def _is_under_per_domain_ini_root(resolved: str) -> bool:
    """True if ``resolved`` is inside ANY per-domain ini scan root.

Recognises "this is some tenant's per-domain dir" without saying whose. A path
    here that is not the owner's own subtree belongs to a FOREIGN tenant and must
    be rejected outright, never fall through to a root-ownership check that would
    accept it.
    """
    return any(_is_within(root, resolved) for root in _PER_DOMAIN_INI_ROOTS)

def _ini_scan_dir_belongs_to_user(username: str, resolved: str, trusted_php_version: str | None = None) -> bool:
    """Confirm a resolved (realpath'd) ini_scan_dir is one the tenant may drive.

``resolved`` has already been realpath'd and prefix-checked against
    ALLOWED_INI_PREFIXES. That prefix list is intentionally broad and admits
    global root-owned dirs, so this is the default-deny binding gate: accept
    ONLY paths provably tied to the principal, reject everything else.

In phpinfo mode the legitimate ini_scan_dir is one of:
      * the tenant's own CageFS subtree (the link/conf branch is re-rooted there
        by _resolve_ini_path_in_cagefs(self.username, ...));
      * the tenant's own per-domain ini dir, <root>/<self.username>/... for any
        root in _PER_DOMAIN_INI_ROOTS (cPanel's /etc/users, DirectAdmin's
        /etc/configs/users);
      * for a NON-CageFS tenant (ea-php / Plesk / native), the global, root-owned
        per-distro+version INI_LOCATION for the account's PHP handler — e.g.
        /opt/cpanel/ea-php80/root/etc/php.d (see xray-ini-placement.md). This is
        legitimate, so rejecting it outright would regress those tenants.

The danger is that ``ini_scan_dir`` AND the probe ``phpversion`` are both
    served from the tenant's own docroot, so a tenant could report a global dir
    its account does NOT actually run. A bare two-digit version compare is not
    enough: it is distro-BLIND, so an ea-php80 tenant could report the same-number
    alt-php dir /opt/alt/php80/link/conf and steer the root xray.ini write into a
    DIFFERENT distro family's server-wide, all-tenant-shared dir (cross-distro
    spoof) — on a mixed alt-php+ea-php server that dir exists, so strict resolve
    passes. To close that AND the cross-version spoof, the global branch accepts
    ONLY the EXACT INI_LOCATION derived from ``trusted_php_version`` — here the
    account's REAL provisioned FULL handler carrying its distro family (cPanel
    domain['version'] 'ea-php80', Plesk resolve_lsphp_version(handler), DA
    opts[...]['ver'] 'php80'), NOT the probe-reported version and NOT a
    distro-blind number — and requires ``resolved`` to equal it.

Accepted:
      * the tenant's OWN CageFS subtree (/var/cagefs/<prefix>/<username>/...);
      * the tenant's OWN per-domain ini dir (<root>/<username>/..., any root in
        _PER_DOMAIN_INI_ROOTS);
      * the SINGLE INI_LOCATION == _expected_ini_location(trusted_php_version).

Rejected (default-deny): global config dirs with no version segment
    (/etc/php.d, /etc/php.scan.d, /etc/cl.php.d, /usr/share/cagefs[-skeleton]
    roots), a per-version dir of a DIFFERENT distro family (cross-distro spoof) or
    a DIFFERENT version (cross-version spoof) than the trusted handler, a trusted
    handler that carries no distro family (a bare number — expected dir cannot be
    derived), another tenant's CageFS subtree, another account's
    per-domain ini dir under another account's <root>/<other>/ subtree, and any
    other dir not matched above.
    """
    # The tenant's own per-user CageFS area, derived for self.username.
    if _is_own_cagefs_subtree(username, resolved):
        return True

# The tenant's own per-domain ini scan dir
    # (<root>/<self.username>/php/<vhost>, for every root in
    # _PER_DOMAIN_INI_ROOTS — cPanel's /etc/users and DirectAdmin's
    # /etc/configs/users). The username segment is bound to self.username
    # (separator boundary), so another account's subtree — including a
    # <self.username>EVIL lookalike — is rejected.
    if _is_own_per_domain_ini_dir(username, resolved):
        return True

# A global, root-owned per-distro+version INI_LOCATION (legitimate for
    # non-CageFS tenants) — accepted ONLY when ``resolved`` is EXACTLY the one dir
    # derived from the account's TRUSTED FULL handler (distro+version). Equality,
    # not a number match: a same-number dir of another distro family, a
    # different version, or a trusted handler with no derivable dir is rejected.
    expected = _expected_ini_location(trusted_php_version)
    if expected is not None:
        try:
            expected = str(Path(expected).resolve(strict=True))
        except (OSError, RuntimeError):
            # The trusted handler's INI_LOCATION does not exist on this server,
            # so the user does not actually run it here — nothing to accept.
            return False
        if resolved == expected:
            return True

return False

def _is_own_cagefs_subtree(username: str, resolved: str) -> bool:
    """True if ``resolved`` is inside the tenant's OWN /var/cagefs subtree.

Prefer the exact /var/cagefs/<prefix>/<username> root when the server can
    supply the CageFS prefix (cagefsctl). When the prefix is unavailable, fall
    back to a structural check that still binds to the principal: the path must
    be /var/cagefs/<shard>/<username>[/...], i.e. ``username`` must occupy the
    per-user segment directly under a single shard directory. This never accepts
    another tenant's subtree (the username segment is pinned and realpath has
    already been applied) and avoids failing closed on a legitimate own-subtree
    path when a transient cagefsctl lookup fails. Note such a /var/cagefs path
    only reaches here when the prefix WAS resolvable in
    _resolve_ini_path_in_cagefs, so the fallback covers a mid-request race, not
    a routine "no prefix" case. Both the prefix and username are compared as
    relative path segments so neither can alter the canonicalized root.
    """
    rel = _relative_to_root(_CAGEFS_ROOT, resolved)
    if rel is None:
        return False
    parts = rel.split('/')
    try:
        prefix = utils.cagefsctl_get_prefix(username)
    except Exception:  # noqa: BLE001 - cagefsctl failure modes are open-ended; fall through to the structural check
        prefix = None
    if prefix:
        # `if prefix:` not `is not None`: cagefsctl_get_prefix() returns
        # stdout.strip(), so success-with-empty-stdout yields '' (not None).
        # Treating '' as a usable prefix would build '/var/cagefs//<user>' and
        # falsely reject the realpath'd own subtree; fall through to the
        # structural check instead.
        return len(parts) >= 2 and parts[0] == prefix and parts[1] == username
    # Prefix unavailable: accept only /var/cagefs/<shard>/<username>[/...], i.e.
    # the username must be the second path segment under the cagefs root.
    return len(parts) >= 2 and parts[1] == username

def _resolve_ini_path_in_cagefs(username: str, path: str):
    """
    ini path inside cagefs can be a symlink
    and as cagefs has different namespace for each user,
    the only way to know that for sure is to dive into cage
    and resolve path there
    """
    try:
        pwd.getpwnam(username)
    except KeyError:
        return None
    cmd = ['/sbin/cagefs_enter_user', username, '/usr/bin/realpath', path]
    try:
        resolved_path = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL).strip()
    except subprocess.CalledProcessError:
        return None

if resolved_path.startswith('/etc/cl.php.d/'):
        prefix = utils.cagefsctl_get_prefix(username)
        # `not prefix` covers both None and '' (stdout.strip() on empty output):
        # an empty prefix would build a malformed '/var/cagefs//<user>...' path.
        if not prefix:
            raise ValueError(_('CageFS prefix resolved as empty, but should be a number'))
        return f'/var/cagefs/{prefix}/{username}{resolved_path}'

return resolved_path

def _probe_one_candidate(
    username: str,
    domain_phpinfo_file_path: str,
    pin_address: str,
    trusted_php_version: str | None,
    read_timeout: float,
) -> PhpConfiguration:
    """Probe ONE connect target and parse what it returns.

Keeps the pre-existing scheme fallback: a vhost that force-redirects
    http->https answers the http probe with a 3xx (surfaced as
    WebsiteNotResponding and never followed — F-01), so the probe is re-issued
    directly over https against the SAME address.

Parsing happens HERE, inside the candidate loop, not after it. A 200 is not
    proof that the account's vhost answered, so a body that is not our payload has
    to count as this candidate failing — otherwise a default vhost that serves its
    own page with status 200 ends the sweep before the right address is tried.
    """
    try:
        response = _request_url('http://' + domain_phpinfo_file_path, pin_address, read_timeout)
    except WebsiteNotResponding:
        # Some websites did not enable HTTP to HTTPS redirection.
        # Try connecting with HTTPS protocol.
        response = _request_url('https://' + domain_phpinfo_file_path, pin_address, read_timeout)

# you may think that we can use json, but we can't because it;s
    # optional php module on older php versions
    return _parse_configuration(username, response.text, trusted_php_version=trusted_php_version)

def _probe_candidates(
    username: str,
    domain: str,
    domain_phpinfo_file_path: str,
    trusted_php_version: str | None = None,
    panel_address: str | None = None,
) -> PhpConfiguration:
    """Fetch and parse the probe file, trying each validated connect target in turn.

A failure against one address says nothing about the others. The defining
    symptom of a per-IP-vhost host (CLOS-6825) is that the request DOES reach the
    local webserver, but on an address whose bucket holds no matching vhost, so
    that bucket's default vhost answers from the server's own DocumentRoot — with
    a 404, or with its own page if it has a catch-all. An error status, a refused
    connection, a read timeout and an unparseable body therefore all advance to
    the next candidate: none of them tells us which vhost answered.

Two things bound the cost of that, since nothing is terminal any more:
      * `_CONNECT_TIMEOUT` caps the connect phase per attempt — every candidate is
        on-box, so a slow connect is a firewall DROP, not a slow site;
      * `_SWEEP_BUDGET_SECONDS` caps the whole sweep's wall-clock, shrinking each
        attempt's read budget to what is left. The temp probe file lives in the
        tenant's docroot for this whole window, so the ceiling matters.

When no candidate serves the probe the FIRST error is re-raised, not the last:
    loopback is the canonical attempt, so its error is the one a support ticket
    can recognise. Surfacing the last one would report, say, "connection refused"
    against some unrelated interface address on a multi-IP host.
    """
    # Resolve the candidates BEFORE starting the clock. The budget exists to bound
    # the probing, and candidate resolution can itself be slow — Plesk's
    # get_server_ip is a psa DB query — so charging it to the budget could expire
    # the sweep before a single attempt was made.
    candidates = probe_targets.connect_candidates(username, domain, panel_address=panel_address)
    # Logged at INFO, not debug: manager.log is what a support ticket carries, and
    # a sweep that SUCCEEDS on a later candidate otherwise leaves nothing behind
    # but the earlier candidates' failure lines. On CLOS-6825's own reporter that
    # read as "the probe still only ever tries 127.0.0.1" when in fact the second
    # candidate had served the file and a LATER stage was failing.
    logger.info('phpinfo probe for %s will try connect candidates %s', domain, candidates)
    deadline = time.monotonic() + _SWEEP_BUDGET_SECONDS
    first_error = None

for pin_address in candidates:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            logger.warning(
                'phpinfo probe for %s gave up after %ds; candidates left unprobed',
                domain,
                _SWEEP_BUDGET_SECONDS,
            )
            break
        try:
            configuration = _probe_one_candidate(
                username,
                domain_phpinfo_file_path,
                pin_address,
                trusted_php_version,
                read_timeout=min(TIMEOUT, remaining),
            )
        except exceptions.XRayManagerError as probe_error:
            logger.info('phpinfo probe for %s failed against %s: %s', domain, pin_address, probe_error)
            if first_error is None:
                first_error = probe_error
        else:
            logger.info(
                'phpinfo probe for %s succeeded against %s: php %s, ini_scan_dir %s',
                domain,
                pin_address,
                configuration.phpversion,
                configuration.ini_scan_dir,
            )
            return configuration

if first_error is not None:
        raise first_error

# No attempt ever completed, so there is no probe error to re-raise. Reachable
    # when the budget expires before the first attempt, and it must NOT be a bare
    # `raise first_error`: raising None is a TypeError, which is not an XRayError
    # and so escapes base_app's handler as a traceback instead of a message.
    raise exceptions.XRayManagerError(
        _unreachable_message(f'no connect candidate could be probed within {_SWEEP_BUDGET_SECONDS}s')
    )

def get_php_configuration(
    username: str,
    domain: str,
    trusted_php_version: str | None = None,
    panel_address: str | None = None,
) -> PhpConfiguration:
    """
    Writes temporary phpinfo-like file to document root
    and executes request to website to retrieve the current
    php version and configuration

``trusted_php_version`` is the account's REAL provisioned PHP version as
    known to the panel (server-side, not the probe). The caller passes it so a
    global per-version ini_scan_dir can be version-bound in
    absolute_ini_scan_dir; None disables that accept branch for the panel.

``panel_address`` is the address the panel bound THIS domain's vhost to, when
    the caller can resolve it better than `probe_targets` can. DirectAdmin needs
    this: it records the address in the PARENT domain's conf, and only the manager
    knows that mapping for a subdomain or an alias. Still validated against this
    machine's own addresses before use; None falls back to `probe_targets`' own
    lookup.
    """
    # Authorize the user-mode caller before any side effect: this is the single
    # sink every panel manager funnels into, so guarding here covers Plesk,
    # cPanel, DirectAdmin and custom panels at once. `username` is the
    # panel-resolved domain owner; a user-mode caller (XRAYEXEC_UID set) who is
    # not that owner is rejected with the uniform "cannot be found" error before
    # the temp PHP file is written into the target docroot and HTTP-fetched.
    # Root / non-user-mode callers are unaffected (verify_user_owns_domain is a
    # no-op when no XRAYEXEC_UID is set).
    verify_user_owns_domain(domain, username)

# if certificate is bad, but the site itself works,
    # we consider it ok
    urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

with _temporary_phpinfo_file(username, Path(docroot(domain)[0])) as php_info_file:
        domain_phpinfo_file_path = domain + '/' + php_info_file
        # Parsing happens inside the sweep (see _probe_one_candidate), so a body
        # that is not our payload counts as that candidate failing.
        return _probe_candidates(
            username,
            domain,
            domain_phpinfo_file_path,
            trusted_php_version=trusted_php_version,
            panel_address=panel_address,
        )

Sid Gifari From Gifari Industries - BD Cyber Security Team