"""
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License,
or (at your option) any later version.


This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
See the GNU General Public License for more details.


You should have received a copy of the GNU General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.

Copyright © 2019 Cloud Linux Software Inc.

This software is also available under ImunifyAV commercial license,
see <https://www.imunify360.com/legal/eula>

Conservative recognition of attack traces in web logs and web statistics.

See docs/log-attack-traces.md for accepted formats and sample sources.
Unknown formats, unsafe paths and unreadable files keep malware handling.
"""
import functools
import os
import pwd
import re
import stat
import zlib
from contextlib import ExitStack, contextmanager

from defence360agent.utils import _get_max_min_uid
from defence360agent.utils.safe_fileops import open_fd

PREFIX_LIMIT = 16 * 1024
COMPRESSED_LIMIT = 64 * 1024
EVENT = "log_attack_trace"
WEB_LOG = "web_log"
USER_LOG = "user_log"
# Quoted fields cannot consume line separators or unescaped quote delimiters.
_QUOTED = rb'"(?:[^"\\\r\n]|\\[^\r\n])*"'
_ACCESS_HEAD = (
    rb"(?:[A-Za-z0-9_.-]+(?::\d+)? )?"
    rb"(?P<client>[^\s]+) [^\s]+ [^\s]+ "
    rb"\[(?P<time>\d{2}/[A-Za-z]{3}/\d{4}:"
    rb"\d{2}:\d{2}:\d{2} [+-]\d{4})\] "
    rb'"(?P<request>(?:[^"\\\r\n]|\\[^\r\n])* HTTP/\d(?:\.\d)?)" '
    rb"(?P<status>\d{3}) (?:\d+|-)"
)
_ACCESS = re.compile(
    _ACCESS_HEAD
    + rb"(?: "
    + rb"(?P<referer>"
    + _QUOTED
    + rb")"
    + rb" "
    + rb"(?P<agent>"
    + _QUOTED
    + rb")"
    + rb"(?: (?:\d+(?:\.\d+)?|-|"
    + _QUOTED
    + rb"))*)?"
)
_APACHE_ERROR = re.compile(
    rb"\[[A-Za-z]{3} [A-Za-z]{3} +\d{1,2} \d{2}:\d{2}:\d{2}"
    rb"(?:\.\d+)? \d{4}\] \[(?:[a-z_]+:)?"
    rb"(?:emerg|alert|crit|error|warn|notice|info|debug)\] [^\r\n]+"
)
_NGINX_ERROR = re.compile(
    rb"\d{4}/\d{2}/\d{2} \d{2}:\d{2}:\d{2} "
    rb"\[(?:emerg|alert|crit|error|warn|notice|info|debug)\] "
    rb"\d+#\d+: [^\r\n]+"
)

# Every opener PHP may execute: <? (short tags included), <% (asp_tags) and
# <script language=php> (PHP 5), as PHP 5's scanner spells it. No unbounded
# attribute scan: the account writes the lines it is run on.
_PHP_OPEN = re.compile(rb"<\?|<%|<script\s+language\s*=\s*[\"']?php", re.I)
_LOG_PATH = re.compile(
    r"(?P<root>/(?:var/www/vhosts/(?:system/)?[^/]+/logs|"
    r"usr/local/apache/domlogs|var/log/(?:httpd|apache2|nginx)))/.+"
)

_ROTATION = re.compile(
    r"(?:\.(?:processed|webstat))?(?:\.[1-9][0-9]*|-[0-9]{8})?" r"(?:\.gz)?$"
)
_WEB_LOG_NAME = re.compile(
    r"(?:(?:proxy_)?(?:access|access_ssl|error)_log|"
    r"(?:access|error)\.log|ssl_(?:access|error)_log)"
)
_DOMAIN = r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z]{2,63}"


def _known_log_name(path):
    name = _ROTATION.sub("", path.rsplit("/", 1)[-1])
    if _WEB_LOG_NAME.fullmatch(name):
        return True
    if path.startswith("/usr/local/apache/domlogs/"):
        # A plain .log file is not evidence of a cPanel domain log.
        return not name.endswith(".log") and bool(
            re.fullmatch(_DOMAIN + r"(?:-(?:ssl|bytes)_log)?", name)
        )
    if path.startswith(("/var/log/httpd/domains/", "/var/log/nginx/domains/")):
        return bool(re.fullmatch(_DOMAIN + r"(?:\.error)?\.log", name))
    return False


@contextmanager
def _open_log(path):
    """Pin a root-owned log under trusted directories or its Plesk hard link."""
    from imav.malwarelib.plugins.cleanup import _system_owned

    parts = path.split("/")
    if not path.startswith("/") or any(
        p in (".", "..", "") for p in parts[1:]
    ):
        raise ValueError("Unsafe log path")
    webspace = re.fullmatch(
        r"/var/www/vhosts/(?!system/)([^/]+)/logs/(.+)", path
    )
    match = _LOG_PATH.fullmatch(path)
    root_depth = match["root"].count("/") if match else len(parts) - 2
    with ExitStack() as stack:
        fd = stack.enter_context(open_fd("/", os.O_RDONLY | os.O_DIRECTORY))
        for depth, part in enumerate(parts[1:-1], 1):
            fd = stack.enter_context(
                open_fd(
                    part,
                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
                    dir_fd=fd,
                )
            )
            if not webspace and depth >= root_depth:
                info = os.fstat(fd)
                if not _system_owned(info.st_uid) or info.st_mode & 0o022:
                    raise ValueError("Untrusted log directory")
        fd = stack.enter_context(
            open_fd(
                parts[-1],
                os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK,
                dir_fd=fd,
            )
        )
        info = os.fstat(fd)
        if not stat.S_ISREG(info.st_mode) or info.st_uid != 0:
            raise ValueError("Not a root-owned regular log")
        if webspace:
            domain, name = webspace.groups()
            # The user-owned webspace directory is not a trust boundary.
            # Pin its trusted system counterpart before reading either alias.
            system_fd = stack.enter_context(
                _open_log(f"/var/www/vhosts/system/{domain}/logs/{name}")
            )
            system_info = os.fstat(system_fd)
            if (info.st_dev, info.st_ino) != (
                system_info.st_dev,
                system_info.st_ino,
            ):
                raise ValueError("Not the Plesk system log inode")
        yield fd


def _read_prefix(path: str) -> tuple[bytes, bool]:
    """Bound both input and decompressed output; never follow a path symlink."""
    try:
        with _open_log(path) as fd:
            compressed = path.endswith(".gz")
            data = os.read(
                fd, COMPRESSED_LIMIT if compressed else PREFIX_LIMIT + 1
            )
            compressed_eof = compressed and len(data) >= os.fstat(fd).st_size
        eof = len(data) <= PREFIX_LIMIT
        if compressed:
            stream = zlib.decompressobj(16 + zlib.MAX_WBITS)
            data = stream.decompress(data, PREFIX_LIMIT + 1)
            eof = stream.eof and len(data) <= PREFIX_LIMIT
            # Missing stream termination at physical EOF is not a sample
            # boundary. The output cap may still leave compressed data unread.
            if compressed_eof and not stream.eof and len(data) <= PREFIX_LIMIT:
                return b"", True
            # Do not classify a prefix while silently ignoring another member.
            if stream.unused_data:
                return b"", True
        # One lookahead byte distinguishes a full sample from actual EOF.
        return data[:PREFIX_LIMIT], eof
    except (OSError, ValueError, zlib.error):
        return b"", True


LINE_LIMIT = 4096
LINE_COUNT_LIMIT = 64 * 1024


def _text(value):
    # Decode invalid bytes losslessly, then escape controls and non-printables.
    result = ""
    for char in value.decode("utf-8", "surrogateescape"):
        code = ord(char)
        if char.isprintable():
            escaped = char
        elif 0xDC80 <= code <= 0xDCFF:
            escaped = "\\x%02x" % (code - 0xDC00)
        else:
            escaped = ascii(char)[1:-1]
        if len(result) + len(escaped) > 300:
            break
        result += escaped
    return result


def _line_at(fd, pos):
    """The raw line holding byte *pos* and its start; bounded reads only."""
    if type(pos) is not int or not 0 <= pos < 2**63:
        return None
    start = max(0, pos - LINE_LIMIT)
    data = os.pread(fd, LINE_LIMIT * 2 + 1, start)
    relative = pos - start
    if relative >= len(data):
        return None
    left = data.rfind(b"\n", 0, relative) + 1
    right = data.find(b"\n", relative)
    if (start and not left) or (right < 0 and len(data) == LINE_LIMIT * 2 + 1):
        return None
    if right < 0:
        right = len(data)
    line = data[left:right].removesuffix(b"\r")
    if len(line) > LINE_LIMIT:
        return None
    return line, start + left


def read_context(path, pos, opener=None, parser=None):
    """Read only the containing line, through the same checked descriptor walk.

    Scanner offsets address raw bytes, so gzip offsets cannot locate a log line.
    Reopening after classification is safe: every component is no-follow and
    ownership is checked again. Once opened, all reads use that one descriptor.
    """
    if path.endswith(".gz") or type(pos) is not int or not 0 <= pos < 2**63:
        return None
    try:
        with (opener or _open_log)(path) as fd:
            found = _line_at(fd, pos)
            if found is None:
                return None
            line, line_start = found
            details = (parser or _parse_context)(line)
            if details is None:
                return None
            if line_start <= LINE_COUNT_LIMIT:
                prefix = os.pread(fd, line_start, 0)
                if len(prefix) == line_start:
                    details["line"] = prefix.count(b"\n") + 1
            return details
    except (OSError, ValueError, OverflowError):
        return None


def _parse_context(line):
    match = _ACCESS.fullmatch(line)
    if match:
        result = {
            key: _text(match[key])
            for key in ("client", "time", "request", "status")
        }
        result["status"] = int(result["status"])
        return result
    elif _APACHE_ERROR.fullmatch(line):
        timestamp, message = line[1:].split(b"] ", 1)
        message = message.split(b"] ", 1)[1]
        result = {"time": _text(timestamp), "message": _text(message)}
        client = re.search(rb"\[client ([^\]]+)\]", message)
        if client:
            result["client"] = _text(client[1])
        return result
    elif _NGINX_ERROR.fullmatch(line):
        message = line.split(b": ", 1)[1]
        result = {"time": _text(line[:19]), "message": _text(message)}
        client = re.search(rb"(?:^|, )client: ([^,]+)", message)
        if client:
            result["client"] = _text(client[1])
        return result
    match = _PHP_ERROR.fullmatch(line)
    if match:
        return {
            "time": _text(match["time"]),
            "message": _text(match["message"]),
        }
    return None


def _is_log_line(line):
    match = _ACCESS.fullmatch(line)
    if match:
        # Only the request, referer and user-agent carry permitted attack text.
        free_text = line
        for field in ("agent", "referer", "request"):
            start, end = match.span(field)
            if start >= 0:
                free_text = free_text[:start] + free_text[end:]
        return not _PHP_OPEN.search(free_text)
    return not _PHP_OPEN.search(line) and any(
        pattern.fullmatch(line) for pattern in (_APACHE_ERROR, _NGINX_ERROR)
    )


def is_log_trace(path: str) -> bool:
    if not _LOG_PATH.fullmatch(path):
        return False
    if any(p in (".", "..") for p in path.split("/")):
        return False
    # Script-like names stay malware candidates regardless of their location.
    if re.search(
        r"\.(?:php[3-8]?|phtml|inc|js|html?|cgi|pl|sh|py)$",
        _ROTATION.sub("", path),
        re.I,
    ):
        return False
    if not _known_log_name(path):
        return False
    data, eof = _read_prefix(path)
    lines = data.split(b"\n")
    if not eof or not lines[-1]:
        lines.pop()
    return bool(lines) and all(
        _is_log_line(line.removesuffix(b"\r")) for line in lines
    )


# User-owned logs and web statistics, see docs/log-attack-traces.md.
# Whole-file validation cap: 99.9% of the fleet's detected log and
# statistics files are at most 1 MiB (the scanner's default size limit).
USER_FILE_LIMIT = 1024 * 1024
_READ_CHUNK = 64 * 1024
WEB_SERVER_UIDS = frozenset((33, 48, 99))


@functools.lru_cache(maxsize=1)
def web_server_owners():
    """Stored owners of the web-server accounts that may own a user's log:
    their names and, as for owners outside a panel, their numeric uids."""
    owners = {str(uid) for uid in WEB_SERVER_UIDS}
    for uid in WEB_SERVER_UIDS:
        try:
            owners.add(pwd.getpwuid(uid).pw_name)
        except KeyError:
            pass
    return frozenset(owners)


def trace_owners(accounts):
    """{account: stored owners whose rows a trace of that account retires}:
    the web-server accounts and the account, by name and numeric uid."""
    web = web_server_owners()
    owners = {}
    for name in accounts:
        names = set(web)
        if name is not None:
            names.add(name)
            try:
                names.add(str(pwd.getpwnam(name).pw_uid))
            except KeyError:
                pass
        owners[name] = frozenset(names)
    return owners


_PHP_EXECUTABLE = re.compile(
    r"\.(?:php[0-9a-f]*|phtml|pht|phar|inc|phpt|phtm)(?:\.|$)", re.I
)
# Extensions a web server or browser executes or renders as active content,
# checked on every dot component (Apache maps all of them).
_ACTIVE_EXTENSION = re.compile(
    r"\.(?:s?html?|xht(?:ml)?|stm|svgz?|[mc]?js|xslt?|swf|hta|wasm"
    r"|f?cgi|pl|pm|py[cow]?|sh|bash|[kcz]sh|rb|lua|jspx?|as[hmp]x?|cfml?"
    r"|exe|dll|so|bin|elf)(?:\.|$)",
    re.I,
)
# Execution-control files are never traces, whatever folder they are in.
_EXECUTION_CONTROL = re.compile(r"\.htaccess|\.user\.ini|php\.ini", re.I)
_CACHE_DIR = re.compile(
    r"(?:^|/)(?:lscache|litespeed|cache|jch-optimize|wp-rocket)/", re.I
)
_USER_ROTATION = re.compile(
    r"(?:\.(?:processed|webstat))?(?:[.-][0-9]+)*$", re.I
)
_USER_LOG_NAME = re.compile(
    r"(?:error_log|access_log|access_ssl_log|ssl_access_log|ssl_error_log"
    r"|proxy_[a-z_]*log|php_errors?|php_error_log)"
    r"(?:_[A-Za-z0-9][A-Za-z0-9._-]*)?"
    r"|[^/]+\.log",
    re.I,
)
_USER_LOG_FOLDER = re.compile(
    r"(?:access-logs|\.logs)/[^/]+"
    r"|logs/[A-Za-z0-9.-]+(?:-ssl_log)?-[A-Z][a-z]{2}-[0-9]{4}",
)
# Statistics kinds: (location, name) -> required header or line shape.
# Statistics output written by cPanel into the account home (home-relative),
# in lower case only.
_ANALOG = re.compile(r"tmp/analog/(?:.+/)?cache(?:\.out)?")
_AWSTATS = re.compile(
    r"tmp/awstats/(?:.+/)?awstats[0-9]{6}(?:\.[A-Za-z0-9_.-]+)?\.txt"
)
# Every byte of a user log line is text: control bytes other than TAB
# (NUL, \f, \v, a lone \r, ESC, ...) are never part of a log line.
_CONTROL = re.compile(rb"[\x00-\x08\x0a-\x1f\x7f]")
_PHP_ERROR = re.compile(
    rb"\[(?P<time>\d{2}-[A-Za-z]{3}-\d{4} \d{2}:\d{2}:\d{2}"
    rb"(?: [A-Za-z0-9/_+:-]+)?)\] (?P<message>[^\r\n]+)"
)
_ISO_LINE = re.compile(
    rb"\[?(?P<time>\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}"
    rb"(?:[.,]\d{1,9})?(?:Z|[+-]\d{2}(?::?\d{2})?)?)\]?"
    rb"[ \t]+(?P<message>[^\s<][^\r\n]*)"
)
_SYSLOG_LINE = re.compile(
    rb"(?P<time>[A-Z][a-z]{2} [ \d]\d \d{2}:\d{2}:\d{2}) "
    rb"(?P<message>[^\s<][^\r\n]*)"
)
# Stack-trace lines PHP and Monolog write below a timestamped entry; they
# may never carry a PHP opener.
_PHP_CONTINUATION = re.compile(rb"Stack trace:|#[0-9]+ .*|  thrown in .*")
_ISO_CONTINUATION = re.compile(
    rb"\[stacktrace\]|#[0-9]+ .*|\"\}|\[previous exception\] .*"
)
_ANALOG_HEADER = re.compile(rb"CACHE type [0-9]+ produced by analog [^<]*")
_ANALOG_ENTRY = re.compile(rb"(?:-?[0-9]+\t){3,}[^\t]+")
_ANALOG_OTHER = re.compile(rb"(?:[A-Za-z]\t)?-?[0-9]+(?:\t-?[0-9]+)*")
_AWSTATS_HEADER = re.compile(rb"AWSTATS DATA FILE [^<]*")
# An AWStats record: one key (an URL, referer or agent without spaces) and
# numeric counters only.
_AWSTATS_RECORD = re.compile(rb"[^\s<#]\S*(?: -?[0-9]+)+")
_AWSTATS_OTHER = re.compile(rb"(?:BEGIN|END)_[A-Z0-9_]+(?: -?[0-9]+)*|#[^<]*")


@functools.lru_cache(maxsize=1)
def _uid_range():
    return _get_max_min_uid()


def _min_uid():
    return _uid_range()[0]


def _account_uid(uid):
    low, high = _uid_range()
    return low <= uid <= high


def _account(path, user, passwd_cache=None):
    """Home, uid and name of the hosting account whose home holds *path*.

    A named user is looked up directly. Otherwise (web-server-owned files)
    the owner uid of each enclosing directory is resolved with getpwuid;
    passwd is never enumerated.
    """
    cache = {} if passwd_cache is None else passwd_cache

    def by_uid(uid):
        if uid not in cache:
            try:
                cache[uid] = pwd.getpwuid(uid)
            except KeyError:
                cache[uid] = None
        return cache[uid]

    def owns(pw):
        home = pw.pw_dir.rstrip("/")
        return home and _account_uid(pw.pw_uid) and path.startswith(home + "/")

    found = None
    if isinstance(user, str) and user and not user.isdigit():
        try:
            pw = pwd.getpwnam(user)
        except KeyError:
            pw = None
        if pw is not None and owns(pw):
            found = pw
    if found is None:
        parts = path.split("/")
        for depth in range(len(parts) - 1, 1, -1):
            directory = "/".join(parts[:depth])
            try:
                uid = os.lstat(directory).st_uid
            except OSError:
                continue
            pw = by_uid(uid)
            if (
                pw is not None
                and pw.pw_dir.rstrip("/") == directory
                and owns(pw)
            ):
                found = pw
                break
    if found is None:
        return None
    return found.pw_dir.rstrip("/"), found.pw_uid, found.pw_name


def _name_allowed(name):
    stripped = _USER_ROTATION.sub("", name) or name
    return not (
        _PHP_EXECUTABLE.search(name)
        or _ACTIVE_EXTENSION.search(name)
        or _EXECUTION_CONTROL.fullmatch(stripped)
        or name.lower().endswith(".gz")
    )


def _user_rule(relative):
    """Kind of a home-relative path: "log", a statistics kind, or None."""
    if _ANALOG.fullmatch(relative):
        return "analog"
    if _AWSTATS.fullmatch(relative):
        return "awstats"
    name = relative.rsplit("/", 1)[-1]
    stripped = _USER_ROTATION.sub("", name) or name
    if _USER_LOG_NAME.fullmatch(stripped) or _USER_LOG_FOLDER.fullmatch(
        relative
    ):
        return "log"
    return None


def user_log_candidate(path):
    """Path-only pre-check; no I/O and no account lookup."""
    if not path.startswith("/") or any(
        part in (".", "..", "") for part in path.split("/")[1:]
    ):
        return False
    parts = path.split("/")
    if not _name_allowed(parts[-1]):
        return False
    return any(
        _user_rule("/".join(parts[start:])) is not None
        for start in range(1, len(parts))
    )


@contextmanager
def _open_user_file(path, home, uid):
    """Pin a regular, non-executable single-link file of the account."""
    relative = path[len(home) + 1 :]
    with ExitStack() as stack:
        fd = stack.enter_context(open_fd("/", os.O_RDONLY | os.O_DIRECTORY))
        for part in home.split("/")[1:]:
            fd = stack.enter_context(
                open_fd(
                    part,
                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
                    dir_fd=fd,
                )
            )
        if os.fstat(fd).st_uid != uid:
            raise ValueError("Home directory is not the account's")
        parts = relative.split("/")
        for part in parts[:-1]:
            fd = stack.enter_context(
                open_fd(
                    part,
                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
                    dir_fd=fd,
                )
            )
        fd = stack.enter_context(
            open_fd(
                parts[-1],
                os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK,
                dir_fd=fd,
            )
        )
        info = os.fstat(fd)
        if (
            not stat.S_ISREG(info.st_mode)
            or info.st_mode & 0o111
            or info.st_nlink != 1
            or (info.st_uid != uid and info.st_uid not in WEB_SERVER_UIDS)
        ):
            raise ValueError("Not an account-owned single-link data file")
        yield fd


def _user_location(path, user, passwd_cache=None):
    if not user_log_candidate(path):
        return None
    account = _account(path, user, passwd_cache)
    if account is None:
        return None
    home, uid, name = account
    relative = path[len(home) + 1 :]
    # Cache folders count inside the home only (page caches stay malware).
    if _CACHE_DIR.search(relative):
        return None
    kind = _user_rule(relative)
    return (home, uid, kind, name) if kind else None


def _parse_user_line(line):
    """Context of a user log line; the same parser decides classification."""
    details = _parse_context(line)
    if details is not None:
        return details
    for pattern in (_ISO_LINE, _SYSLOG_LINE):
        match = pattern.fullmatch(line)
        if match:
            return {
                "time": _text(match["time"]),
                "message": _text(match["message"]),
            }
    return None


def _access_line(line):
    match = _ACCESS.fullmatch(line)
    if not match:
        return False
    # A PHP opener only inside the request, referer or user-agent field.
    free_text = line
    for field in ("agent", "referer", "request"):
        start, end = match.span(field)
        if start >= 0:
            free_text = free_text[:start] + free_text[end:]
    return not _PHP_OPEN.search(free_text)


def _primary(pattern):
    return lambda line: bool(pattern.fullmatch(line))


# Families of a user log: the primary (timestamped) line and the lines that
# may follow it. A file belongs to the family of its first line.
_LOG_FAMILIES = (
    (_access_line, None),
    (_primary(_APACHE_ERROR), None),
    (_primary(_NGINX_ERROR), None),
    (_primary(_PHP_ERROR), _PHP_CONTINUATION),
    (_primary(_ISO_LINE), _ISO_CONTINUATION),
    (_primary(_SYSLOG_LINE), None),
)


def _line_check(kind, first):
    """(primary, other) predicates for the lines of a file of *kind*."""
    if kind == "analog":
        if not _ANALOG_HEADER.fullmatch(first):
            return None
        return (
            _primary(_ANALOG_ENTRY),
            lambda line: bool(_ANALOG_OTHER.fullmatch(line)) or line == first,
        )
    if kind == "awstats":
        if not _AWSTATS_HEADER.fullmatch(first):
            return None
        return (
            _primary(_AWSTATS_RECORD),
            lambda line: bool(_AWSTATS_OTHER.fullmatch(line)) or line == first,
        )
    for primary, continuation in _LOG_FAMILIES:
        if primary(first):
            if continuation is None:
                return primary, lambda line: False
            return primary, lambda line: (
                not _PHP_OPEN.search(line)
                and bool(continuation.fullmatch(line))
            )
    return None


def _whole_file_ok(fd, kind, size, positions):
    """Every line of the file belongs to its family; every match is on a
    primary line. Read in bounded chunks through the pinned descriptor."""
    pending = sorted(set(positions))
    if pending[0] < 0 or pending[-1] >= size:
        return False
    check = None
    offset = 0
    start = 0
    tail = b""
    while offset < size:
        chunk = os.pread(fd, min(_READ_CHUNK, size - offset), offset)
        if not chunk:
            return False
        offset += len(chunk)
        data = tail + chunk
        lines = data.split(b"\n")
        tail = lines.pop()
        for raw in lines:
            end = start + len(raw)
            line = raw.removesuffix(b"\r")
            if _CONTROL.search(line):
                return False
            if check is None:
                check = _line_check(kind, line)
                if check is None:
                    return False
            primary, other = check
            is_primary = primary(line)
            if not (is_primary or other(line) or not line):
                return False
            while pending and pending[0] <= end:
                if pending.pop(0) < start or not is_primary:
                    return False
            start = end + 1
    # The scanned size must be the whole file: nothing may follow it.
    if os.pread(fd, 1, size):
        return False
    if tail:
        line = tail.removesuffix(b"\r")
        if _CONTROL.search(line):
            return False
        if check is None:
            check = _line_check(kind, line)
            if check is None:
                return False
        primary, other = check
        is_primary = primary(line)
        if not (is_primary or other(line)):
            return False
        while pending:
            if pending.pop(0) < start or not is_primary:
                return False
    return check is not None and not pending


def _scanned_size(size):
    try:
        size = int(size)
    except (TypeError, ValueError):
        return None
    return size if 0 < size <= USER_FILE_LIMIT else None


def _classify_one(path, user, positions, size, mtime, ctime, passwd_cache):
    # Without the scanner's match offsets a trace cannot be proven.
    if not positions or any(type(pos) is not int for pos in positions):
        return None
    # The account can set st_mtime, not st_ctime; without either reported
    # time the file cannot be bound to the content the scanner read.
    if not (ctime or mtime):
        return None
    # The trace must be the content the scanner read, within the size cap.
    size = _scanned_size(size)
    if size is None:
        return None
    location = _user_location(path, user, passwd_cache)
    if location is None:
        return None
    home, uid, kind, name = location
    try:
        with _open_user_file(path, home, uid) as fd:
            info = os.fstat(fd)
            if (
                info.st_size != size
                or (mtime and int(info.st_mtime) != int(mtime))
                or (ctime and int(info.st_ctime) != int(ctime))
            ):
                return None
            if not _whole_file_ok(fd, kind, size, positions):
                return None
    except (OSError, ValueError, OverflowError, TypeError):
        return None
    return name


def classify_user_logs(candidates):
    """Classify (path, user, positions, size, mtime, ctime) in one executor
    call.

    *size*, *mtime* and *ctime* are the scan report's; returns
    {path: account name} for the files that are attack traces.
    """
    passwd_cache = {}
    traces = {}
    for path, user, positions, size, mtime, ctime in candidates:
        name = _classify_one(
            path, user, positions, size, mtime, ctime, passwd_cache
        )
        if name is not None:
            traces[path] = name
    return traces


def is_user_log_trace(
    path: str, user, positions=(), size=None, mtime=None, ctime=None
) -> bool:
    return bool(
        classify_user_logs([(path, user, list(positions), size, mtime, ctime)])
    )


def read_user_context(path, user, pos):
    location = _user_location(path, user)
    if location is None or location[2] != "log":
        return None
    home, uid, _, _ = location
    return read_context(
        path,
        pos,
        opener=lambda path: _open_user_file(path, home, uid),
        parser=_parse_user_line,
    )
