oswatcher-plugins 0.14.0__py3-none-any.whl

plugins/syscalls/nodes.py

@@ -0,0 +1,119 @@
+"""Domain Node and MerkleNode classes for syscall data transformation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Iterator, List, Optional
+
+from attrs import define, field
+from neogit.core.merkle import MerkleVisitor
+from neogit.core.model import MerkleLabel, MerkleNode, Node
+from neogit.core.visitor import VisitedNode
+
+
+@define(auto_attribs=True)
+class SyscallNode(Node):
+    """Represents a single syscall entry (leaf node)."""
+
+    name: str
+    index: int
+    entry_point: str
+    parameters: Optional[List[str]]
+
+    def iter_child_nodes(self) -> Iterator[Node]:
+        """Syscall is a leaf node with no children."""
+        return iter([])
+
+
+@define(auto_attribs=True)
+class SyscallTableNode(Node):
+    """Represents a syscall table for an architecture (internal node)."""
+
+    architecture: str  # e.g., "lief._lief.ELF.ARCH.x86_64"
+    syscalls: List[dict]  # Raw syscall data from extraction
+
+    def iter_child_nodes(self) -> Iterator[Node]:
+        """Yield SyscallNode for each syscall in the table."""
+        for sc in self.syscalls:
+            yield SyscallNode(
+                name=sc["name"],
+                index=sc["index"],
+                entry_point=sc["entry_point"],
+                parameters=sc.get("parameters"),
+            )
+
+
+@define(auto_attribs=True)
+class SyscallMerkleNode(MerkleNode):
+    """Merkle node for a syscall (content-addressed)."""
+
+    name: str = field(kw_only=True)
+    index: int = field(kw_only=True)
+    entry_point: str = field(kw_only=True)
+    parameters: str = field(kw_only=True)  # JSON serialized
+
+
+@define(auto_attribs=True)
+class SyscallTableMerkleNode(MerkleNode):
+    """Merkle node for a syscall table (content-addressed)."""
+
+    architecture: str = field(kw_only=True)
+
+
+class SyscallsMerkleVisitor(MerkleVisitor):
+    """Visitor for computing merkle hashes of syscall nodes."""
+
+    def visit_SyscallNode(self, node: SyscallNode, hash_obj: hashlib._Hash, *args, **kwargs):
+        """Visit a syscall leaf node and compute its hash.
+
+        Hash includes: index + name + entry_point + parameters (sorted)
+        """
+        # Serialize parameters to JSON (sorted for determinism)
+        params_json = json.dumps(node.parameters, sort_keys=True) if node.parameters else ""
+
+        # Hash: index + name + entry_point + parameters
+        data = f"{node.index}-{node.name}-{node.entry_point}-{params_json}".encode()
+        hash_obj.update(data)
+
+        merkle_node = SyscallMerkleNode(  # type: ignore[call-arg]
+            hash=hash_obj.hexdigest(),
+            label=MerkleLabel.Blob,  # Leaf node
+            name=node.name,
+            index=node.index,
+            entry_point=node.entry_point,
+            parameters=params_json,
+        )
+        return VisitedNode(node, merkle_node)
+
+    def visit_SyscallTableNode(self, node: SyscallTableNode, hash_obj: hashlib._Hash, *args, **kwargs):
+        """Visit a syscall table and aggregate child hashes.
+
+        Hash includes: all syscall hashes (sorted by index) + architecture
+        """
+        children = {}
+
+        # Sort by index for deterministic ordering
+        sorted_syscalls = sorted(node.iter_child_nodes(), key=lambda s: s.index)
+
+        for syscall_node in sorted_syscalls:
+            # Recursively visit child
+            visited = self.visit(syscall_node, *args, **kwargs)
+            merkle_child = visited.return_value
+
+            # Accumulate: syscall_name + hash
+            data = f"{syscall_node.name}{merkle_child.hash}\n".encode()
+            hash_obj.update(data)
+
+            children[syscall_node.name] = merkle_child
+
+        # Add table metadata
+        hash_obj.update(f"{node.architecture}".encode())
+
+        merkle_node = SyscallTableMerkleNode(  # type: ignore[call-arg]
+            hash=hash_obj.hexdigest(),
+            children=children,
+            label=MerkleLabel.Tree,  # Internal node
+            architecture=node.architecture,
+        )
+        return VisitedNode(node, merkle_node)

plugins/syscalls/syscall_table_parser.py

@@ -0,0 +1,46 @@
+"""Syscall table parsing from syscall_64.tbl format."""
+
+import re
+from typing import Optional
+
+from .kernel_parser import SyscallIndex
+
+# Compiled regex pattern for syscall table line parsing
+# Pattern: <number> <abi> <name> [<entry_point>] [optional_fields...]
+SYSCALL_TABLE_PATTERN = re.compile(r"^(\d+)\s+(common|64|x32)\s+(\w+)(?:\s+(\w+))?")
+
+
+def parse_syscall_table_line(line: str) -> Optional[SyscallIndex]:
+    """Parse a single line from syscall_64.tbl format.
+
+    Args:
+        line: Table line like '0\tcommon\tread\tsys_read'
+
+    Returns:
+        SyscallIndex instance or None for filtered/invalid lines
+
+    Raises:
+        ValueError: If line format is invalid but not filtered
+    """
+    line = line.strip()
+
+    # Filter out empty lines and comments
+    if not line or line.startswith("#"):
+        return None
+
+    match = SYSCALL_TABLE_PATTERN.match(line)
+    if not match:
+        raise ValueError(f"Invalid syscall table line format: {line}")
+
+    number_str, abi, name, entry_point = match.groups()
+
+    # Some syscalls don't have entry points defined (like uselib)
+    if entry_point is None:
+        entry_point = f"sys_{name}"
+
+    # Filter out x32 ABI for 64-bit focus
+    if abi == "x32":
+        return None
+
+    index = int(number_str)
+    return SyscallIndex(name=name, index=index)

plugins/syscalls/syscalls_h_parser.py

@@ -0,0 +1,52 @@
+"""Syscalls.h signature parsing from kernel headers."""
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class SyscallSignature:
+    """Represents a syscall signature with parameters."""
+
+    name: str
+    parameters: List[str]
+
+
+def parse_syscall_signature(syscalls_h_content: str, entry_name: str) -> Optional[SyscallSignature]:
+    """Parse syscall signature for a specific entry from syscalls.h content.
+
+    Args:
+        syscalls_h_content: Content of syscalls.h file
+        entry_name: Entry point name like 'sys_read'
+
+    Returns:
+        SyscallSignature instance or None if not found
+    """
+    # Use Filippo's regex pattern: (?:asmlinkage|unsigned) long {entry}\(([^)]+)\);
+    pattern = rf"(?:asmlinkage|unsigned) long {re.escape(entry_name)}\(([^)]+)\)"  # noqa: E231
+
+    # Make multiline and handle whitespace
+    match = re.search(pattern, syscalls_h_content, re.MULTILINE | re.DOTALL)
+
+    if not match:
+        return None
+
+    params_str = match.group(1)
+
+    # Handle void case
+    if params_str.strip() == "void":
+        parameters: list = []
+    else:
+        # Split by comma and clean up
+        parameters = []
+        for param in params_str.split(","):
+            param = param.strip()
+            # Remove __user qualifier
+            param = param.replace("__user ", "")
+            parameters.append(param)
+
+    # Extract syscall name from entry_name (remove sys_ prefix)
+    name = entry_name.replace("sys_", "")
+
+    return SyscallSignature(name=name, parameters=parameters)

plugins/types.py

@@ -0,0 +1,108 @@
+# define abstract Plugin Class
+
+import logging
+import tempfile
+from abc import abstractmethod
+from contextlib import contextmanager, suppress
+from datetime import datetime, timezone
+from typing import Any, List
+
+from attrs import Factory, define, field
+from neogit.model.neo import Commit, PluginRun
+from neogit.service import Neogit
+from neogit.utils import BetterContextManager
+
+QUERY_CREATE_UNIQUE_CONSTRAINT = """
+CREATE CONSTRAINT {name}
+IF NOT EXISTS
+FOR (n:{label})
+REQUIRE n.{property} IS UNIQUE
+""".strip()
+
+
+@define(auto_attribs=True)
+class UniqueConstraint:
+    label: str = field()
+    property_list: list[str] = field()
+
+
+@define(auto_attribs=True)
+class AbstractPlugin(BetterContextManager):
+    logger: logging.Logger = field(
+        init=False,
+        default=Factory(
+            lambda self: logging.getLogger(f"{self.__module__}.{self.__class__.__name__}"),
+            takes_self=True,
+        ),
+    )
+    neogit: Neogit = field(init=False, default=Neogit())
+
+    def __call__(self, commit: Commit, plugin_name: str, *args: Any, force: bool = False, **kwds: Any) -> Any:
+        """Execute the run method inside a neomodel transaction
+
+        Args:
+            commit: The commit to process
+            plugin_name: Name of the plugin being run
+            force: If True, rerun the plugin even if already executed
+        """
+        with suppress(IndexError):
+            plugin_run_node = commit.plugin.all()[0]
+            plugin_date = getattr(plugin_run_node, plugin_name, None)
+            if plugin_date is not None and not force:
+                self.logger.info(
+                    "Plugin run node already executed at %s for commit %s", plugin_run_node.filetype, commit.hash
+                )
+                return
+            if plugin_date is not None and force:
+                self.logger.info(
+                    "Force rerun enabled - re-executing plugin for commit %s (previously run at %s)",
+                    commit.hash,
+                    plugin_date,
+                )
+        # can't mix schema modification and write query in the same transaction
+        with self.neogit.db.transaction:
+            self.ensure_constraints()
+        # TODO: fix transaction
+        # with self.neogit.db.transaction:
+        self.run(commit)
+        with self.neogit.db.write_transaction:
+            try:
+                plugin_run_node = commit.plugin.all()[0]
+                self.logger.info("Plugin run node already exists for commit %s", commit.hash)
+            except IndexError:
+                self.logger.info("Creating plugin run node for commit %s", commit.hash)
+                plugin_run_node = PluginRun()
+                # node needs to be saved for the connection to be created as well
+                plugin_run_node.save()
+            # ensure connected
+            commit.plugin.connect(plugin_run_node)
+            # update plugin run with datetime (timzeone-aware UTC)
+            setattr(plugin_run_node, plugin_name, datetime.now(timezone.utc))
+            plugin_run_node.save()
+
+        self.logger.info("Plugin run node updated for commit %s", commit.hash)
+
+    def ensure_constraints(self):
+        """Ensure the constraints are in the database"""
+        for constraint in self.constraints_data():
+            for prop in constraint.property_list:
+                name = f"{constraint.label.lower()}_{prop}_unique"
+                query = QUERY_CREATE_UNIQUE_CONSTRAINT.format(name=name, label=constraint.label, property=prop)
+                self.neogit.db.cypher_query(query)
+
+    def constraints_data(self) -> List[UniqueConstraint]:
+        """Return the constraints data"""
+        return []
+
+    @abstractmethod
+    def run(self, commit: Commit):
+        """Run the plugin"""
+        pass
+
+    @contextmanager
+    def downloaded_file(self, hash: str):
+        with tempfile.NamedTemporaryFile(delete=True) as tmp_file:
+            for chunk in self.neogit.download_object_as_stream(hash):
+                tmp_file.write(chunk)
+            tmp_file.flush()
+            yield tmp_file.name