crosshair-tool 0.0.99__cp312-cp312-macosx_10_13_x86_64.whl

crosshair/_tracers_test.py

@@ -0,0 +1,138 @@
+import dis
+import gc
+import sys
+from typing import List
+
+import pytest
+
+from _crosshair_tracers import (  # type: ignore
+    CTracer,
+    code_stack_depths,
+    frame_stack_read,
+)
+from crosshair.util import mem_usage_kb
+
+
+class ExampleModule:
+    opcodes_wanted = frozenset([42, 255])
+
+
+def test_CTracer_module_refcounts_dont_leak():
+    mod = ExampleModule()
+    base_count = sys.getrefcount(mod)
+    tracer = CTracer()
+    tracer.push_module(mod)
+    assert sys.getrefcount(mod) == base_count + 1
+    tracer.push_module(mod)
+    tracer.start()
+    tracer.stop()
+    assert sys.getrefcount(mod) == base_count + 2
+    tracer.pop_module(mod)
+    assert sys.getrefcount(mod) == base_count + 1
+    del tracer
+    gc.collect()
+    assert sys.getrefcount(mod) == base_count
+
+
+def _get_depths(fn):
+    # dis.dis(fn)
+    depths = code_stack_depths(fn.__code__)
+    for instr in dis.Bytecode(fn):
+        wordpos = instr.offset // 2
+        depth = depths[wordpos]
+        if depth != -9:
+            assert depth >= 0
+            assert depth + dis.stack_effect(instr.opcode, instr.arg) >= 0
+    return depths
+
+
+class RawNull:
+    def __repr__(self):
+        return "_RAW_NULL"
+
+
+_RAW_NULL = RawNull()
+
+
+def _log_execution_stacks(fn, *a, **kw):
+    depths = _get_depths(fn)
+    stacks = []
+
+    def _tracer(frame, event, arg):
+        if event == "opcode":
+            lasti = frame.f_lasti
+            opcode = frame.f_code.co_code[lasti]
+            oparg = frame.f_code.co_code[lasti + 1]  # TODO: account for EXTENDED_ARG
+            opname = dis.opname[opcode]
+            entry: List = [f"{opname}({oparg})"]
+            for i in range(-depths[lasti // 2], 0, 1):
+                try:
+                    entry.append(frame_stack_read(frame, i))
+                except ValueError:
+                    entry.append(_RAW_NULL)
+            stacks.append(tuple(entry))
+        frame.f_trace = _tracer
+        frame.f_trace_opcodes = True
+        return _tracer
+
+    old_tracer = sys.gettrace()
+    # Caller needs opcode tracing since Python 3.12; see https://github.com/python/cpython/issues/103615
+    sys._getframe().f_trace_opcodes = True
+
+    sys.settrace(_tracer)
+    try:
+        result = (fn(*a, **kw), None)
+    except Exception as exc:
+        result = (None, exc)
+    finally:
+        sys.settrace(old_tracer)
+    return stacks
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 12) or sys.version_info >= (3, 14),
+    reason="stack depths only in 3.12 & 3.13",
+)
+def test_one_function_stack_depth():
+    _E = (TypeError, KeyboardInterrupt)
+
+    def a(x):
+        return {k for k in (35, x)}
+
+    # just enure no crashes:
+    _log_execution_stacks(a, 4)
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 12) or sys.version_info >= (3, 14),
+    reason="stack depths only in 3.12 & 3.13",
+)
+def test_stack_get():
+    def to_be_traced(x):
+        r = 8 - x
+        return 9 - r
+
+    stacks = _log_execution_stacks(to_be_traced, 3)
+    assert ("BINARY_OP(10)", 8, 3) in stacks
+    assert ("BINARY_OP(10)", 9, 5) in stacks
+
+
+@pytest.mark.skipif(
+    sys.platform.startswith("win"), reason="getrusage not available on windows"
+)
+def test_CTracer_does_not_leak_memory():
+    import resource  # (available only on unix; delay import)
+
+    for i in range(1_000):
+        tracer = CTracer()
+        tracer.start()
+        mods = [ExampleModule() for _ in range(6)]
+        for mod in mods:
+            tracer.push_module(mod)
+        for mod in reversed(mods):
+            tracer.pop_module(mod)
+        tracer.stop()
+        if i == 100:
+            usage = mem_usage_kb()
+    usage_increase = mem_usage_kb() - usage
+    assert usage_increase < 200

crosshair/abcstring.py

@@ -0,0 +1,245 @@
+import collections.abc
+import sys
+from collections import UserString
+from numbers import Integral
+
+from crosshair.tracers import NoTracing
+
+# Similar to UserString, but allows you to lazily supply the contents
+# when accessed.
+
+# Sadly, this illusion doesn't fully work: various Python operations
+# require a actual strings or subclasses.
+# (see related issue: https://bugs.python.org/issue16397)
+
+# TODO: Our symbolic strings likely already override most of these methods.
+# Consider removing this class.
+
+_MISSING = object()
+
+
+def _real_string(thing: object):
+    with NoTracing():
+        return thing.data if isinstance(thing, (UserString, AbcString)) else thing
+
+
+def _real_int(thing: object):
+    return thing.__int__() if isinstance(thing, Integral) else thing
+
+
+class AbcString(collections.abc.Sequence, collections.abc.Hashable):
+    """
+    Implement just ``__str__``.
+
+    Useful for making lazy strings.
+    """
+
+    data = property(lambda s: s.__str__())
+
+    def __repr__(self):
+        return repr(self.data)
+
+    def __hash__(self):
+        return hash(self.data)
+
+    def __eq__(self, string):
+        return self.data == _real_string(string)
+
+    def __lt__(self, string):
+        return self.data < _real_string(string)
+
+    def __le__(self, string):
+        return self.data <= _real_string(string)
+
+    def __gt__(self, string):
+        return self.data > _real_string(string)
+
+    def __ge__(self, string):
+        return self.data >= _real_string(string)
+
+    def __contains__(self, char):
+        return _real_string(char) in self.data
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, index):
+        return self.data[index]
+
+    def __add__(self, other):
+        other = _real_string(other)
+        if isinstance(other, str):
+            return self.data + other
+        return self.data + str(other)
+
+    def __radd__(self, other):
+        other = _real_string(other)
+        if isinstance(other, str):
+            return other + self.data
+        return str(other) + self.data
+
+    def __mul__(self, n):
+        return self.data * n
+
+    def __rmul__(self, n):
+        return self.data * n
+
+    def __mod__(self, args):
+        return self.data % args
+
+    def __rmod__(self, template):
+        return str(template) % self.data
+
+    # the following methods are defined in alphabetical order:
+    def capitalize(self):
+        return self.data.capitalize()
+
+    def casefold(self):
+        return self.data.casefold()
+
+    def center(self, width, *args):
+        return self.data.center(width, *args)
+
+    def count(self, sub, start=0, end=sys.maxsize):
+        return self.data.count(_real_string(sub), start, end)
+
+    def encode(self, encoding=_MISSING, errors=_MISSING):
+        if encoding is not _MISSING:
+            if errors is not _MISSING:
+                return self.data.encode(encoding, errors)
+            return self.data.encode(encoding)
+        return self.data.encode()
+
+    def endswith(self, suffix, start=0, end=sys.maxsize):
+        return self.data.endswith(suffix, start, end)
+
+    def expandtabs(self, tabsize=8):
+        return self.data.expandtabs(_real_int(tabsize))
+
+    def find(self, sub, start=0, end=sys.maxsize):
+        return self.data.find(_real_string(sub), start, end)
+
+    def format(self, *args, **kwds):
+        return self.data.format(*args, **kwds)
+
+    def format_map(self, mapping):
+        return self.data.format_map(mapping)
+
+    def index(self, sub, start=0, end=sys.maxsize):
+        return self.data.index(_real_string(sub), start, end)
+
+    def isalpha(self):
+        return self.data.isalpha()
+
+    def isalnum(self):
+        return self.data.isalnum()
+
+    def isascii(self):
+        return self.data.isascii()
+
+    def isdecimal(self):
+        return self.data.isdecimal()
+
+    def isdigit(self):
+        return self.data.isdigit()
+
+    def isidentifier(self):
+        return self.data.isidentifier()
+
+    def islower(self):
+        return self.data.islower()
+
+    def isnumeric(self):
+        return self.data.isnumeric()
+
+    def isprintable(self):
+        return self.data.isprintable()
+
+    def isspace(self):
+        return self.data.isspace()
+
+    def istitle(self):
+        return self.data.istitle()
+
+    def isupper(self):
+        return self.data.isupper()
+
+    def join(self, seq):
+        return self.data.join(seq)
+
+    def ljust(self, width, *args):
+        return self.data.ljust(width, *args)
+
+    def lower(self):
+        return self.data.lower()
+
+    def lstrip(self, chars=None):
+        return self.data.lstrip(_real_string(chars))
+
+    maketrans = str.maketrans
+
+    def partition(self, sep):
+        return self.data.partition(_real_string(sep))
+
+    def replace(self, old, new, maxsplit=-1):
+        return self.data.replace(_real_string(old), _real_string(new), maxsplit)
+
+    def rfind(self, sub, start=0, end=sys.maxsize):
+        return self.data.rfind(_real_string(sub), start, end)
+
+    def rindex(self, sub, start=0, end=sys.maxsize):
+        return self.data.rindex(_real_string(sub), start, end)
+
+    def rjust(self, width, *args):
+        return self.data.rjust(width, *args)
+
+    def rpartition(self, sep):
+        return self.data.rpartition(sep)
+
+    def rsplit(self, sep=None, maxsplit=-1):
+        return self.data.rsplit(sep, maxsplit)
+
+    def rstrip(self, chars=None):
+        return self.data.rstrip(_real_string(chars))
+
+    def split(self, sep=None, maxsplit=-1):
+        return self.data.split(sep, maxsplit)
+
+    def splitlines(self, keepends=False):
+        return self.data.splitlines(keepends)
+
+    def startswith(self, prefix, start=0, end=sys.maxsize):
+        return self.data.startswith(prefix, start, end)
+
+    def strip(self, chars=None):
+        return self.data.strip(_real_string(chars))
+
+    def swapcase(self):
+        return self.data.swapcase()
+
+    def title(self):
+        return self.data.title()
+
+    def translate(self, *args):
+        return self.data.translate(*args)
+
+    def upper(self):
+        return self.data.upper()
+
+    def zfill(self, width):
+        return self.data.zfill(width)
+
+    if sys.version_info >= (3, 9):
+
+        def removeprefix(self, prefix: str) -> "AbcString":
+            if self.startswith(prefix):
+                return self[len(prefix) :]
+            return self
+
+        def removesuffix(self, suffix: str) -> "AbcString":
+            if self.endswith(suffix):
+                suffixlen = len(suffix)
+                if suffixlen == 0:
+                    return self
+                return self[:-suffixlen]
+            return self

crosshair/auditwall.py

@@ -0,0 +1,190 @@
+import importlib
+import inspect
+import os
+import sys
+import traceback
+from contextlib import contextmanager
+from types import ModuleType
+from typing import Callable, Dict, Generator, Iterable, Optional, Set, Tuple
+
+
+class SideEffectDetected(Exception):
+    pass
+
+
+_BLOCKED_OPEN_FLAGS = (
+    os.O_WRONLY | os.O_RDWR | os.O_APPEND | os.O_CREAT | os.O_EXCL | os.O_TRUNC
+)
+
+
+def accept(event: str, args: Tuple) -> None:
+    pass
+
+
+def reject(event: str, args: Tuple) -> None:
+    raise SideEffectDetected(
+        f'A "{event}{args}" operation was detected. '
+        f"CrossHair should not be run on code with side effects"
+    )
+
+
+def inside_module(modules: Iterable[ModuleType]) -> bool:
+    """Checks whether the current call stack is inside one of the given modules."""
+    for frame, _lineno in traceback.walk_stack(None):
+        frame_module = inspect.getmodule(frame)
+        if frame_module and frame_module in modules:
+            return True
+    return False
+
+
+def check_open(event: str, args: Tuple) -> None:
+    (filename_or_descriptor, mode, flags) = args
+    if filename_or_descriptor in ("/dev/null", "nul"):
+        # (no-op writes on unix/windows)
+        return
+    if flags & _BLOCKED_OPEN_FLAGS:
+        raise SideEffectDetected(
+            f'We\'ve blocked a file writing operation on "{filename_or_descriptor}". '
+            f"CrossHair should not be run on code with side effects"
+        )
+
+
+def check_msvcrt_open(event: str, args: Tuple) -> None:
+    print(args)
+    (handle, flags) = args
+    if flags & _BLOCKED_OPEN_FLAGS:
+        raise SideEffectDetected(
+            f'We\'ve blocked a file writing operation on "{handle}". '
+            f"CrossHair should not be run on code with side effects"
+        )
+
+
+_MODULES_THAT_CAN_POPEN: Optional[Set[ModuleType]] = None
+
+
+def modules_with_allowed_subprocess():
+    global _MODULES_THAT_CAN_POPEN
+    if _MODULES_THAT_CAN_POPEN is None:
+        allowed_module_names = ("_aix_support", "ctypes", "platform", "uuid")
+        _MODULES_THAT_CAN_POPEN = set()
+        for module_name in allowed_module_names:
+            try:
+                _MODULES_THAT_CAN_POPEN.add(importlib.import_module(module_name))
+            except ImportError:
+                pass
+    return _MODULES_THAT_CAN_POPEN
+
+
+def check_subprocess(event: str, args: Tuple) -> None:
+    if not inside_module(modules_with_allowed_subprocess()):
+        reject(event, args)
+
+
+_SPECIAL_HANDLERS = {
+    "open": check_open,
+    "subprocess.Popen": check_subprocess,
+    "os.posix_spawn": check_subprocess,
+    "msvcrt.open_osfhandle": check_msvcrt_open,
+}
+
+
+def make_handler(event: str) -> Callable[[str, Tuple], None]:
+    special_handler = _SPECIAL_HANDLERS.get(event, None)
+    if special_handler:
+        return special_handler
+    # Block certain events
+    if event in (
+        "winreg.CreateKey",
+        "winreg.DeleteKey",
+        "winreg.DeleteValue",
+        "winreg.SaveKey",
+        "winreg.SetValue",
+        "winreg.DisableReflectionKey",
+        "winreg.EnableReflectionKey",
+    ):
+        return reject
+    # Allow certain events.
+    if event in (
+        # These seem not terribly dangerous to allow:
+        "os.putenv",
+        "os.unsetenv",
+        "msvcrt.heapmin",
+        "msvcrt.kbhit",
+        # These involve I/O, but are hopefully non-destructive:
+        "glob.glob",
+        "msvcrt.get_osfhandle",
+        "msvcrt.setmode",
+        "os.listdir",  # (important for Python's importer)
+        "os.scandir",  # (important for Python's importer)
+        "os.chdir",
+        "os.fwalk",
+        "os.getxattr",
+        "os.listxattr",
+        "os.walk",
+        "pathlib.Path.glob",
+        "socket.gethostbyname",  # (FastAPI TestClient uses this)
+        "socket.__new__",  # (FastAPI TestClient uses this)
+        "socket.bind",  # pygls's asyncio needs this on windows
+        "socket.connect",  # pygls's asyncio needs this on windows
+    ):
+        return accept
+    # Block groups of events.
+    event_prefix = event.split(".", 1)[0]
+    if event_prefix in (
+        "os",
+        "fcntl",
+        "ftplib",
+        "glob",
+        "imaplib",
+        "msvcrt",
+        "nntplib",
+        "pathlib",
+        "poplib",
+        "shutil",
+        "smtplib",
+        "socket",
+        "sqlite3",
+        "subprocess",
+        "telnetlib",
+        "urllib",
+        "webbrowser",
+    ):
+        return reject
+    # Allow other events.
+    return accept
+
+
+_HANDLERS: Dict[str, Callable[[str, Tuple], None]] = {}
+_ENABLED = True
+
+
+def audithook(event: str, args: Tuple) -> None:
+    if not _ENABLED:
+        return
+    handler = _HANDLERS.get(event)
+    if handler is None:
+        handler = make_handler(event)
+        _HANDLERS[event] = handler
+    handler(event, args)
+
+
+@contextmanager
+def opened_auditwall() -> Generator:
+    global _ENABLED
+    assert _ENABLED
+    _ENABLED = False
+    try:
+        yield
+    finally:
+        _ENABLED = True
+
+
+def engage_auditwall() -> None:
+    sys.dont_write_bytecode = True  # disable .pyc file writing
+    sys.addaudithook(audithook)
+
+
+def disable_auditwall() -> None:
+    global _ENABLED
+    assert _ENABLED
+    _ENABLED = False

crosshair/auditwall_test.py

@@ -0,0 +1,77 @@
+import os
+import platform
+import sys
+import urllib.request
+from subprocess import call
+
+import pytest
+
+from crosshair.auditwall import SideEffectDetected, engage_auditwall
+
+# audit hooks cannot be uninstalled, and we don't want to wall off the
+# testing process. Spawn subprcoesses instead.
+
+pyexec = sys.executable
+
+
+def test_fs_read_allowed():
+    assert call([pyexec, __file__, "read_open", "withwall"]) != 10
+
+
+def test_scandir_allowed():
+    assert call([pyexec, __file__, "scandir", "withwall"]) == 0
+
+
+def test_import_allowed():
+    assert call([pyexec, __file__, "import", "withwall"]) == 0
+
+
+def test_fs_write_disallowed():
+    assert call([pyexec, __file__, "write_open", "withwall"]) == 10
+
+
+def test_http_disallowed():
+    assert call([pyexec, __file__, "http", "withwall"]) == 10
+
+
+def test_unlink_disallowed():
+    assert call([pyexec, __file__, "unlink", "withwall"]) == 10
+
+
+def test_popen_disallowed():
+    assert call([pyexec, __file__, "popen", "withwall"]) == 10
+
+
+def test_chdir_allowed():
+    assert call([pyexec, __file__, "chdir", "withwall"]) == 0
+
+
+@pytest.mark.skipif(sys.version_info < (3, 9), reason="Python 3.9+ required")
+def test_popen_via_platform_allowed():
+    assert call([pyexec, __file__, "popen_via_platform", "withwall"]) == 0
+
+
+_ACTIONS = {
+    "read_open": lambda: open("/dev/null", "rb"),
+    "scandir": lambda: os.scandir("."),
+    "import": lambda: __import__("shutil"),
+    "write_open": lambda: open("/.auditwall.testwrite.txt", "w"),
+    "http": lambda: urllib.request.urlopen("http://localhost/foo"),
+    "unlink": lambda: os.unlink("./delme.txt"),
+    "popen": lambda: call(["echo", "hello"]),
+    "popen_via_platform": lambda: platform._syscmd_ver(  # type: ignore
+        supported_platforms=(sys.platform,)
+    ),
+    "chdir": lambda: os.chdir("."),
+}
+
+if __name__ == "__main__":
+    action, wall = sys.argv[1:]
+    if wall == "withwall":
+        engage_auditwall()
+
+    try:
+        _ACTIONS[action]()
+    except SideEffectDetected as e:
+        print(e)
+        sys.exit(10)