strilight 0.2.0__py3-none-any.whl

strilight/__init__.py

@@ -0,0 +1,174 @@
+"""
+Strilight: High-Performance O(1) SMT Loop Lifting & Strided Interval Domain
+============================================================================
+A lightweight, high-performance abstract interpretation and symbolic loop-lifting library for x86_64 binaries.
+"""
+
+import logging
+import sys
+from typing import List, Union, Optional, Any
+
+__version__ = "0.2.0"
+
+# Module-level logger with default NullHandler (zero unwanted stdout noise when imported)
+logger = logging.getLogger("strilight")
+logger.addHandler(logging.NullHandler())
+
+
+def set_log_level(level: Union[int, str]):
+    """
+    Sets the logging level for the strilight root logger.
+    Example: sl.set_log_level(logging.DEBUG) or sl.set_log_level("INFO")
+    """
+    if isinstance(level, str):
+        level = getattr(logging, level.upper(), logging.INFO)
+    logger.setLevel(level)
+
+
+def enable_logging(level: Union[int, str] = logging.INFO, stream=None):
+    """
+    Enables console logging for strilight with a clean, standard formatter.
+    """
+    if stream is None:
+        stream = sys.stderr
+    set_log_level(level)
+    
+    # Avoid adding multiple StreamHandlers
+    if not any(isinstance(h, logging.StreamHandler) and not isinstance(h, logging.NullHandler) for h in logger.handlers):
+        handler = logging.StreamHandler(stream)
+        formatter = logging.Formatter("[%(levelname)s] [%(name)s] %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+
+# Core abstractions
+from strilight.engine.vsa import LoopSummary, LoopInvariantContract
+from strilight.engine.domains import Interval, StridedInterval, DisjointIntervalSet
+from strilight.frontend import SourceLifter, CodeGenerator, accelerate, accelerate_c_source
+
+
+def __getattr__(name: str):
+    """
+    Lazy load optional extension and architecture modules on demand (PEP 562).
+    Keeps core mathematical engine purely isolated from binary dependencies upon import.
+    """
+    try:
+        if name in ("LoopEvaluator", "X86LoopEvaluator"):
+            from strilight.arch.x86.evaluator import LoopEvaluator
+            return LoopEvaluator
+        if name in ("SymbolicInductionAnalyzer", "X86SymbolicInductionAnalyzer"):
+            from strilight.arch.x86.symbolic import SymbolicInductionAnalyzer
+            return SymbolicInductionAnalyzer
+        if name in ("Instruction", "LoopBlock", "TraceCompressor"):
+            import strilight.arch as a
+            return getattr(a, name)
+        if name in ("ConditionExtractor", "StaticFlagTracker"):
+            import strilight.arch.x86 as x86
+            return getattr(x86, name)
+        if name in (
+            "Tracker",
+            "TraceRecord",
+            "BackwardSliceTracker",
+            "ForwardSliceTracker",
+            "Descendant",
+            "Ancestor",
+        ):
+            import strilight.extensions.tracker as t
+            return getattr(t, name)
+        if name == "BackwardTracker":
+            import strilight.extensions.tracker as t
+            return getattr(t, "BackwardSliceTracker")
+        if name == "Z3Translator":
+            from strilight.extensions.translator import Z3Translator
+            return Z3Translator
+        if name in ("SymbolicStackEngine", "StackByteCell"):
+            import strilight.extensions.stack_engine as s
+            return getattr(s, name)
+        if name == "AnalyzerCore":
+            from strilight.extensions.core import AnalyzerCore
+            return AnalyzerCore
+        if name == "setup_hooks":
+            from strilight.extensions.hooks import setup_hooks
+            return setup_hooks
+        if name == "AngrBridge":
+            from strilight.extensions.angr_bridge import AngrBridge
+            return AngrBridge
+    except ImportError as e:
+        raise AttributeError(f"Optional module {name!r} could not be loaded: {e}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# =============================================================================
+# High-Level Facade API (Instant Developer Experience)
+# =============================================================================
+
+def disassemble(code_bytes: bytes, base_address: int = 0x1000, bit_mode: int = 64) -> List[Any]:
+    """
+    Disassembles raw machine code bytes into standard Instruction objects.
+    """
+    from strilight.arch.instruction import Instruction
+    return Instruction.disassemble_bytes(code_bytes, base_address=base_address, bit_mode=bit_mode)
+
+
+def compress(trace: List[Any], min_iterations: int = 3) -> List[Any]:
+    """
+    Compresses repeated instruction execution traces into LoopBlock hierarchies.
+    """
+    from strilight.arch.loop_compressor import TraceCompressor
+    return TraceCompressor.compress_trace(trace, min_iterations=min_iterations)
+
+
+def evaluate(block_or_trace: Any, k_passes: int = 100, iterations: int = 1000) -> LoopSummary:
+    """
+    Evaluates abstract strided intervals and generates the closed-form loop invariant contract.
+    """
+    from strilight.arch.loop_compressor import LoopBlock
+    from strilight.arch.x86.evaluator import LoopEvaluator
+    if isinstance(block_or_trace, list):
+        block_or_trace = LoopBlock(body=block_or_trace, iterations=iterations)
+    evaluator = LoopEvaluator(k_passes=k_passes)
+    return evaluator.evaluate(block_or_trace)
+
+
+def analyze(code_bytes: bytes, iterations: int = 1000, base_address: int = 0x1000, bit_mode: int = 64, k_passes: int = 100) -> LoopSummary:
+    """
+    One-line end-to-end loop analysis:
+    Disassembles machine code bytes, wraps into a LoopBlock, and extracts closed-form deltas & invariant contracts.
+    """
+    from strilight.arch.loop_compressor import LoopBlock
+    instructions = disassemble(code_bytes, base_address=base_address, bit_mode=bit_mode)
+    block = LoopBlock(body=instructions, iterations=iterations)
+    return evaluate(block, k_passes=k_passes)
+
+
+__all__ = [
+    # High-Level Facade Functions & Decorators
+    "disassemble",
+    "compress",
+    "evaluate",
+    "analyze",
+    "accelerate",
+    "accelerate_c_source",
+    
+    # Logging Configuration
+    "logger",
+    "set_log_level",
+    "enable_logging",
+    
+    # Core Classes
+    "Instruction",
+    "LoopBlock",
+    "TraceCompressor",
+    "LoopEvaluator",
+    "LoopSummary",
+    "LoopInvariantContract",
+    "ConditionExtractor",
+    "StaticFlagTracker",
+    "Interval",
+    "StridedInterval",
+    "DisjointIntervalSet",
+    "SymbolicStackEngine",
+    "StackByteCell",
+    "SourceLifter",
+    "CodeGenerator",
+]

strilight/engine/__init__.py

@@ -0,0 +1,16 @@
+"""
+Strilight Engine Subpackage (strilight.engine)
+==============================================
+Pure mathematical foundation: abstract interpretation domains, abstract state,
+recurrence equation models, and SMT closed-form translation.
+"""
+
+from strilight.engine.abstract_state import AbstractState
+import strilight.engine.domains as domains
+import strilight.engine.vsa as vsa
+
+__all__ = [
+    "AbstractState",
+    "domains",
+    "vsa",
+]

strilight/engine/abstract_state.py

@@ -0,0 +1,106 @@
+from typing import Dict, List, Tuple, Union
+from strilight.engine.domains import Interval, StridedInterval, DisjointIntervalSet
+
+class StridedMemoryMap:
+    """
+    Abstract memory mapping using Strided Intervals for fast, safe loop execution.
+    Implements 'Safe Approximation' and 'Bézout Modulo Congruence Non-Aliasing'
+    (Notion Sections 3 & 8) to maintain O(1) mathematical speed and zero false aliasing.
+    """
+    def __init__(self):
+        # List of memory transactions: (address_interval, size_in_bytes, value_dset)
+        self.writes: List[Tuple[Union[Interval, StridedInterval], int, DisjointIntervalSet]] = []
+        
+    def write(self, addr: Union[Interval, StridedInterval], size: int, value: DisjointIntervalSet):
+        """Records an abstract write transaction."""
+        self.writes.append((addr, size, value))
+        
+    def read(self, addr: Union[Interval, StridedInterval], size: int) -> DisjointIntervalSet:
+        """
+        Reads from the abstract memory.
+        Uses Bézout Modulo Congruence Non-Aliasing (Rule 8.b.1) and Must-Alias (Rule 8.b.2):
+        - If proven Definite Non-Alias via gcd(s1, s2) or disjoint bounds: skip safely.
+        - If read exactly matches a recent write (Must-Alias): returns the precise value.
+        - If complex partial overlap is detected: returns TOP (UNKNOWN).
+        """
+        # Search backwards (most recent write first)
+        for w_addr, w_size, w_value in reversed(self.writes):
+            # 1. Modulo Congruence Non-Alias Test (Bézout GCD)
+            if hasattr(addr, 'is_disjoint_modulo') and hasattr(w_addr, 'is_disjoint_modulo'):
+                if addr.is_disjoint_modulo(w_addr):
+                    continue  # Definite Non-Alias: No interference!
+                    
+            # 2. Must-Alias Test
+            if hasattr(addr, 'is_must_alias') and hasattr(w_addr, 'is_must_alias'):
+                if addr.is_must_alias(w_addr) and size == w_size:
+                    return w_value
+                    
+            # 3. Fallback Intersection Check for Interval objects
+            if hasattr(addr, 'intersect') and hasattr(w_addr, 'intersect'):
+                intersected = addr.intersect(w_addr)
+                if intersected.min_val <= intersected.max_val:
+                    # Physical overlap detected
+                    if (addr.min_val == w_addr.min_val and 
+                        addr.max_val == w_addr.max_val and 
+                        size == w_size and 
+                        getattr(addr, 'stride', 1) == getattr(w_addr, 'stride', 1) and 
+                        getattr(addr, 'stride_offset', 0) == getattr(w_addr, 'stride_offset', 0)):
+                        return w_value
+                    else:
+                        # Complex partial overlap -> TOP (Safe Approximation)
+                        dset = DisjointIntervalSet(k_limit=8)
+                        dset.add(Interval(0, (1 << (size * 8)) - 1, size * 8))
+                        return dset
+                else:
+                    continue
+                    
+        # Not found in writes, return TOP (Symbolic/Unknown initial memory)
+        dset = DisjointIntervalSet(k_limit=8)
+        dset.add(Interval(0, (1 << (size * 8)) - 1, size * 8))
+        return dset
+
+
+class AbstractState:
+    """
+    Represents the full hardware state in the Abstract Domain for the Loop Evaluator.
+    """
+    def __init__(self):
+        # Registers are stored as DisjointIntervalSets for Surgical Precision + K-Limit
+        self.registers: Dict[str, DisjointIntervalSet] = {}
+        
+        # Strided Memory to track loop array access
+        self.memory = StridedMemoryMap()
+        
+        # Flags are stored as Interval (3-valued logic: 0, 1, or Unknown/TOP)
+        # 1-bit width: [0, 0] means False, [1, 1] means True, [0, 1] means Unknown
+        self.flags: Dict[str, Interval] = {}
+        
+    def get_register(self, reg_name: str, bit_width: int = 64) -> DisjointIntervalSet:
+        if reg_name not in self.registers:
+            dset = DisjointIntervalSet(k_limit=8)
+            # Default to TOP (Unknown)
+            dset.add(Interval(0, (1 << bit_width) - 1, bit_width))
+            self.registers[reg_name] = dset
+        return self.registers[reg_name]
+        
+    def set_register(self, reg_name: str, value: DisjointIntervalSet):
+        self.registers[reg_name] = value
+
+    # Generic mathematical variable aliases
+    get_variable = get_register
+    set_variable = set_register
+
+    @property
+    def variables(self) -> Dict[str, DisjointIntervalSet]:
+        """Generic alias for abstract variables/registers."""
+        return self.registers
+
+    def get_flag(self, flag_name: str) -> Interval:
+        if flag_name not in self.flags:
+            # TOP for 1 bit is [0, 1] (Unknown)
+            self.flags[flag_name] = Interval(0, 1, 1)
+        return self.flags[flag_name]
+        
+    def set_flag(self, flag_name: str, value: Interval):
+        assert value.bit_width == 1, f"Flags must be 1-bit Intervals, got {value.bit_width}-bit"
+        self.flags[flag_name] = value

strilight/engine/domains/__init__.py

@@ -0,0 +1,18 @@
+"""
+Strilight Mathematical Abstract Domains (strilight.engine.domains)
+==================================================================
+Modular ring arithmetic intervals, Strided Intervals, Bézout GCD congruence,
+dual-mask reduced products, and disjoint set management for VSA.
+"""
+
+from strilight.engine.domains.interval import (
+    Interval,
+    StridedInterval,
+    DisjointIntervalSet,
+)
+
+__all__ = [
+    "Interval",
+    "StridedInterval",
+    "DisjointIntervalSet",
+]