cpanel-importer/scripts/lib/scan-symlinks.php

<?php
/**
 * scan-symlinks.php — standalone port of
 * CpanelBackupImporter::scanTarballForDangerousSymlinks().
 *
 * This is the same classification logic that ships in the WHP panel today
 * (web-files/libs/CpanelBackupImporter.php, ~line 2438). Lifted into a
 * standalone CLI so the container can run it as an independent pre-extract
 * gate without dragging in the rest of the importer.
 *
 * Exit codes:
 *   0 — clean (no DANGEROUS findings)
 *   1 — one or more DANGEROUS findings; tarball MUST NOT be extracted
 *   2 — usage / I/O error
 *
 * Always writes a JSON report to --report describing every absolute-target
 * symlink seen and the classification verdict.
 *
 * SECURITY NOTE — this differs from the panel implementation in ONE way:
 *   The panel uses file_exists($target) on the *host* to decide whether a
 *   target under a dangerous prefix is BENIGN_DANGLING vs DANGEROUS. We
 *   are running INSIDE the container so /etc and /usr DO exist (they're
 *   the container's own), but `--read-only --tmpfs /tmp` plus the worker
 *   running as UID 999 means even DANGEROUS targets cannot reach the host.
 *
 *   We treat any absolute-target symlink under a dangerous prefix as
 *   DANGEROUS regardless of `file_exists()` — this is a stricter check
 *   than the panel's, because in the container we *can* safely refuse to
 *   even try the extract on a clearly malicious tarball.
 */

require __DIR__ . '/safety-net.php';

$opts = getopt('', ['tarball:', 'username:', 'report:']);
if (!isset($opts['tarball']) || !isset($opts['report'])) {
    fwrite(STDERR, "usage: scan-symlinks.php --tarball <path> --report <out.json> [--username <u>]\n");
    exit(2);
}
$tarPath  = $opts['tarball'];
$reportPath = $opts['report'];
$username = $opts['username'] ?? '';

if (!is_file($tarPath) || !is_readable($tarPath)) {
    fwrite(STDERR, "scan-symlinks: not a readable file: $tarPath\n");
    exit(2);
}

// Same prefix list as the panel.
$dangerousPrefixes = [
    '/etc', '/usr', '/bin', '/sbin', '/lib', '/lib64',
    '/boot', '/root',
    '/var/lib', '/var/log', '/var/cache', '/var/spool',
];

$findings = [];
$cpanelUsername = null;

$cmd = 'tar -tvf ' . escapeshellarg($tarPath) . ' 2>/dev/null';
$fh = @popen($cmd, 'r');
if (!$fh) {
    fwrite(STDERR, "scan-symlinks: failed to spawn tar -tvf on $tarPath\n");
    exit(2);
}

while (($line = fgets($fh)) !== false) {
    if ($line === '' || $line[0] !== 'l') continue;
    $arrow = strpos($line, ' -> ');
    if ($arrow === false) continue;
    $left  = substr($line, 0, $arrow);
    $right = rtrim(substr($line, $arrow + 4), "\r\n");
    $parts = preg_split('/\s+/', $left, 6);
    if (count($parts) < 6) continue;
    $archivePath = $parts[5];
    $target = $right;

    if ($target === '' || $target[0] !== '/') continue;

    if ($cpanelUsername === null) {
        if (preg_match('#^cpmove-([^/]+)/#', $archivePath, $m)) {
            $cpanelUsername = $m[1];
        }
    }

    // (1) user-internal — accept symlinks pointing into the customer's
    // own /home/<user>/ tree. The panel rewrites these on extract.
    $userInternal = false;
    $usernames = [];
    if ($cpanelUsername !== null && $cpanelUsername !== '') $usernames[] = $cpanelUsername;
    if ($username !== '')                                   $usernames[] = $username;
    foreach ($usernames as $u) {
        $prefix = '/home/' . $u . '/';
        if (strpos($target, $prefix) === 0 || $target === rtrim($prefix, '/')) {
            $userInternal = true;
            break;
        }
        if (preg_match('#^/home\d+/' . preg_quote($u, '#') . '(/|$)#', $target)) {
            $userInternal = true;
            break;
        }
    }
    if ($userInternal) continue;

    // (2) exact root.
    $type = null;
    $reason = '';
    if ($target === '/') {
        $type = 'DANGEROUS';
        $reason = 'absolute target is root /';
    } else {
        // (3) — in container, every dangerous-prefix target is treated
        // as DANGEROUS without a file_exists() check (see security note
        // at top of file).
        foreach ($dangerousPrefixes as $p) {
            if ($target === $p || strpos($target, $p . '/') === 0) {
                $type = 'DANGEROUS';
                $reason = "absolute target resolves under system path $p";
                break;
            }
        }
        if ($type === null) {
            // Target is absolute, not user-internal, not under a known
            // dangerous prefix. Operators want to know about these.
            $type = 'UNCERTAIN';
            $reason = 'absolute target outside user tree and not on dangerous-prefix list';
        }
    }

    $findings[] = [
        'type'         => $type,
        'archive_path' => $archivePath,
        'target'       => $target,
        'reason'       => $reason,
    ];
}
pclose($fh);

$dangerousCount  = count(array_filter($findings, fn($f) => $f['type'] === 'DANGEROUS'));
$uncertainCount  = count(array_filter($findings, fn($f) => $f['type'] === 'UNCERTAIN'));

$report = [
    'tarball'          => $tarPath,
    'total_findings'   => count($findings),
    'dangerous_count'  => $dangerousCount,
    'uncertain_count'  => $uncertainCount,
    'findings'         => $findings,
];

@file_put_contents($reportPath, json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n");

if ($dangerousCount > 0) {
    fwrite(STDERR, "scan-symlinks: $dangerousCount DANGEROUS finding(s); refusing tarball\n");
    foreach ($findings as $f) {
        if ($f['type'] === 'DANGEROUS') {
            fwrite(STDERR, sprintf("  %s -> %s (%s)\n", $f['archive_path'], $f['target'], $f['reason']));
        }
    }
    exit(1);
}

fwrite(STDERR, "scan-symlinks: clean (uncertain=$uncertainCount, dangerous=0)\n");
exit(0);