oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/export/__init__.py

@@ -0,0 +1,25 @@
+"""Export module for TraceKit protocol definitions.
+
+This module provides functionality to export TraceKit protocol definitions
+to various formats for integration with other tools and workflows.
+
+Supported export formats:
+- Wireshark Lua dissectors
+- (Future) Scapy packet definitions
+- (Future) Kaitai Struct definitions
+- (Future) C/C++ parser code
+
+Example:
+    >>> from oscura.export.wireshark import WiresharkDissectorGenerator
+    >>> from oscura.inference.protocol_dsl import ProtocolDefinition
+    >>> protocol = ProtocolDefinition(name="myproto", description="My Protocol")
+    >>> generator = WiresharkDissectorGenerator()
+    >>> generator.generate(protocol, Path("myproto.lua"))
+"""
+
+# Import main exports
+from . import wireshark
+
+__all__ = [
+    "wireshark",
+]

oscura/export/wireshark/README.md

@@ -0,0 +1,265 @@
+# Wireshark Lua Dissector Export
+
+This module generates Wireshark Lua dissectors from Oscura protocol definitions, enabling seamless integration with Wireshark for interactive protocol analysis.
+
+## Features
+
+- **Complete Protocol Support**: Handles all Oscura field types (uint8, uint16, uint32, int8, etc.)
+- **Variable-Length Fields**: Supports fields with dynamic lengths based on other fields
+- **Endianness Support**: Generates correct big-endian and little-endian field readers
+- **Enum Values**: Creates value_string tables for human-readable enum display
+- **Transport Registration**: Automatic TCP/UDP port registration
+- **Syntax Validation**: Optional Lua syntax validation using `luac`
+- **Error Handling**: Generates robust dissectors with malformed packet detection
+
+## Quick Start
+
+```python
+from pathlib import Path
+from oscura.export.wireshark import WiresharkDissectorGenerator
+from oscura.inference.protocol_dsl import ProtocolDefinition, FieldDefinition
+
+# Define your protocol
+protocol = ProtocolDefinition(
+    name="myproto",
+    description="My Custom Protocol",
+    settings={"transport": "tcp", "port": 8000},
+    fields=[
+        FieldDefinition(name="type", field_type="uint8", size=1),
+        FieldDefinition(name="length", field_type="uint16", size=2),
+        FieldDefinition(name="data", field_type="bytes", size="length"),
+    ],
+)
+
+# Generate dissector
+generator = WiresharkDissectorGenerator()
+generator.generate(protocol, Path("myproto.lua"))
+```
+
+## Installation in Wireshark
+
+Copy the generated `.lua` file to your Wireshark plugins directory:
+
+**Linux:**
+
+```bash
+mkdir -p ~/.local/lib/wireshark/plugins/
+cp myproto.lua ~/.local/lib/wireshark/plugins/
+```
+
+**macOS:**
+
+```bash
+mkdir -p ~/.config/wireshark/plugins/
+cp myproto.lua ~/.config/wireshark/plugins/
+```
+
+**Windows:**
+
+```powershell
+Copy-Item myproto.lua $env:APPDATA\Wireshark\plugins\
+```
+
+Then reload Lua plugins in Wireshark: **Analyze > Reload Lua Plugins** (Ctrl+Shift+L)
+
+## Supported Field Types
+
+|Oscura Type|Wireshark Type|Size|Notes|
+|---|---|---|---|
+|`uint8`|`ProtoField.uint8`|1 byte|Unsigned 8-bit integer|
+|`uint16`|`ProtoField.uint16`|2 bytes|Unsigned 16-bit integer|
+|`uint32`|`ProtoField.uint32`|4 bytes|Unsigned 32-bit integer|
+|`uint64`|`ProtoField.uint64`|8 bytes|Unsigned 64-bit integer|
+|`int8`|`ProtoField.int8`|1 byte|Signed 8-bit integer|
+|`int16`|`ProtoField.int16`|2 bytes|Signed 16-bit integer|
+|`int32`|`ProtoField.int32`|4 bytes|Signed 32-bit integer|
+|`int64`|`ProtoField.int64`|8 bytes|Signed 64-bit integer|
+|`float32`|`ProtoField.float`|4 bytes|IEEE 754 single precision|
+|`float64`|`ProtoField.double`|8 bytes|IEEE 754 double precision|
+|`bool`|`ProtoField.bool`|1 byte|Boolean value|
+|`bytes`|`ProtoField.bytes`|Variable|Raw byte array|
+|`string`|`ProtoField.string`|Variable|Text string|
+
+## Display Bases
+
+The generator automatically selects appropriate display bases:
+
+- **Unsigned integers** (uint\*): Displayed in hexadecimal (`base.HEX`)
+- **Signed integers** (int\*): Displayed in decimal (`base.DEC`)
+- **Floating point**: No base (`base.NONE`)
+- **Strings/bytes**: No base (`base.NONE`)
+
+You can override the display base using the `display_base` parameter.
+
+## Variable-Length Fields
+
+For fields with variable lengths, reference another field's value:
+
+```python
+fields=[
+    FieldDefinition(name="length", field_type="uint16", size=2),
+    FieldDefinition(name="payload", field_type="bytes", size="length"),
+]
+```
+
+The generator automatically:
+
+1. Reads the `length` field value
+2. Uses it to determine `payload` size
+3. Validates that enough data is available
+
+## Enum Fields
+
+Create human-readable enum displays:
+
+```python
+FieldDefinition(
+    name="msg_type",
+    field_type="uint8",
+    size=1,
+    enum={
+        0x01: "REQUEST",
+        0x02: "RESPONSE",
+        0x03: "ERROR",
+    }
+)
+```
+
+Wireshark will display "REQUEST" instead of "0x01" in the packet tree.
+
+## Transport Registration
+
+### TCP Registration
+
+```python
+settings={"transport": "tcp", "port": 8000}
+```
+
+### UDP Registration
+
+```python
+settings={"transport": "udp", "port": 5000}
+```
+
+The dissector automatically registers on the specified port. Packets on that port will be decoded automatically.
+
+## Endianness
+
+### Protocol-Level
+
+```python
+protocol = ProtocolDefinition(
+    name="myproto",
+    endian="little",  # All fields default to little-endian
+    ...
+)
+```
+
+### Field-Level
+
+```python
+FieldDefinition(
+    name="value",
+    field_type="uint32",
+    size=4,
+    endian="little",  # Override protocol endianness
+)
+```
+
+## Conditional Fields
+
+Fields with conditions are documented in comments (evaluation not yet implemented):
+
+```python
+FieldDefinition(
+    name="optional_field",
+    field_type="uint32",
+    size=4,
+    condition="flags == 1",  # Only present when flags field equals 1
+)
+```
+
+## Syntax Validation
+
+Enable automatic Lua syntax validation:
+
+```python
+generator = WiresharkDissectorGenerator(validate=True)
+generator.generate(protocol, Path("myproto.lua"))
+```
+
+Requires `luac` (Lua compiler) to be installed:
+
+- **Linux**: `sudo apt install lua5.3` or `sudo yum install lua`
+- **macOS**: `brew install lua`
+- **Windows**: Download from [lua.org](https://www.lua.org/download.html)
+
+## Examples
+
+See `examples/05_export/wireshark_dissector_example.py` for complete examples:
+
+- Simple protocol with enum fields
+- Modbus-like protocol
+- Custom protocol with multiple field types
+
+Run the example:
+
+```bash
+python examples/05_export/wireshark_dissector_example.py
+```
+
+## API Reference
+
+### WiresharkDissectorGenerator
+
+Main class for generating dissectors.
+
+**Methods:**
+
+- `generate(protocol, output_path)`: Generate dissector to file
+- `generate_to_string(protocol)`: Generate dissector as string
+
+### Helper Functions
+
+- `get_protofield_type(field_type, display_base)`: Map field type to ProtoField
+- `get_field_size(field_type)`: Get fixed size for field type
+- `is_variable_length(field_type)`: Check if field is variable length
+- `get_lua_reader_function(field_type, endian)`: Get Lua buffer reader function
+- `validate_lua_syntax(lua_code)`: Validate Lua code syntax
+- `check_luac_available()`: Check if luac is available
+
+## Limitations
+
+- **Conditional fields**: Comment generated but evaluation not implemented
+- **Nested structures**: Not yet supported
+- **Arrays**: Not yet supported
+- **Heuristic dissectors**: Pattern-based registration not implemented
+- **TCP reassembly**: Not yet supported for stream protocols
+
+## Troubleshooting
+
+### Dissector not loading in Wireshark
+
+1. Check Wireshark's Lua console: **Tools > Lua > Evaluate**
+2. Verify file is in correct plugins directory
+3. Check for syntax errors: `luac -p myproto.lua`
+4. Ensure Lua support is enabled in Wireshark build
+
+### Protocol not decoding automatically
+
+1. Verify port registration matches capture
+2. Try manual decode: Right-click packet > Decode As > select protocol
+3. Check minimum length requirements
+
+### Malformed packet errors
+
+1. Verify field sizes match actual protocol
+2. Check variable-length field references are correct
+3. Ensure endianness is set correctly
+
+## References
+
+- [Wireshark Lua API](https://wiki.wireshark.org/LuaAPI)
+- [Writing Lua Dissectors](https://wiki.wireshark.org/lua/dissectors)
+- [ProtoField Reference](https://wiki.wireshark.org/LuaAPI/Proto)
+- [DissectorTable Reference](https://wiki.wireshark.org/LuaAPI/DissectorTable)

oscura/export/wireshark/__init__.py

@@ -0,0 +1,47 @@
+"""Wireshark dissector export module.
+
+This module provides functionality to export TraceKit protocol definitions
+as Wireshark Lua dissectors for integration with Wireshark's protocol
+analysis tools.
+
+Example:
+    >>> from oscura.inference.protocol_dsl import ProtocolDefinition
+    >>> from oscura.export.wireshark import WiresharkDissectorGenerator
+    >>> protocol = ProtocolDefinition(name="myproto", description="My Protocol")
+    >>> generator = WiresharkDissectorGenerator()
+    >>> generator.generate(protocol, Path("myproto.lua"))
+
+Installation:
+    Copy the generated .lua file to your Wireshark plugins directory:
+    - Linux: ~/.local/lib/wireshark/plugins/
+    - macOS: ~/.config/wireshark/plugins/
+    - Windows: %APPDATA%\\Wireshark\\plugins\\
+"""
+
+from .generator import WiresharkDissectorGenerator
+from .lua_builder import LuaCodeBuilder
+from .type_mapping import (
+    BASE_MAPPING,
+    DEFAULT_BASE,
+    FIELD_TYPE_MAPPING,
+    get_field_size,
+    get_lua_reader_function,
+    get_protofield_type,
+    is_variable_length,
+)
+from .validator import check_luac_available, validate_lua_file, validate_lua_syntax
+
+__all__ = [
+    "BASE_MAPPING",
+    "DEFAULT_BASE",
+    "FIELD_TYPE_MAPPING",
+    "LuaCodeBuilder",
+    "WiresharkDissectorGenerator",
+    "check_luac_available",
+    "get_field_size",
+    "get_lua_reader_function",
+    "get_protofield_type",
+    "is_variable_length",
+    "validate_lua_file",
+    "validate_lua_syntax",
+]

oscura/export/wireshark/generator.py

@@ -0,0 +1,312 @@
+"""Wireshark Lua dissector generator.
+
+This module generates Wireshark Lua dissectors from TraceKit protocol definitions.
+The generated dissectors can be loaded into Wireshark for interactive protocol analysis.
+
+Features:
+- Generate ProtoField declarations for all field types
+- Handle fixed and variable-length fields
+- Support TCP/UDP port registration
+- Checksum validation support
+- Proper error handling for malformed packets
+
+References:
+    https://wiki.wireshark.org/lua/dissectors
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from oscura.inference.protocol_dsl import FieldDefinition, ProtocolDefinition
+
+from .type_mapping import get_field_size, get_lua_reader_function, get_protofield_type
+from .validator import validate_lua_syntax
+
+
+class WiresharkDissectorGenerator:
+    """Generate Wireshark Lua dissectors from protocol definitions.
+
+    This class converts TraceKit protocol definitions into Wireshark Lua
+    dissectors that can be loaded into Wireshark for protocol analysis.
+
+    Features:
+    - Generate ProtoField declarations
+    - Handle fixed and variable-length fields
+    - Support nested protocols (dissector stacking)
+    - TCP/UDP registration
+    - Checksum validation
+    - Registration on port/pattern
+
+    Example:
+        >>> from oscura.inference.protocol_dsl import ProtocolDefinition
+        >>> protocol = ProtocolDefinition(name="simple", description="Simple Protocol")
+        >>> generator = WiresharkDissectorGenerator()
+        >>> generator.generate(protocol, Path("simple.lua"))
+
+    References:
+        https://wiki.wireshark.org/lua/dissectors
+        https://wiki.wireshark.org/LuaAPI/Proto
+    """
+
+    def __init__(self, validate: bool = True) -> None:
+        """Initialize the generator.
+
+        Args:
+            validate: Run luac syntax validation if available
+        """
+        self.validate = validate
+        self.env = Environment(
+            loader=PackageLoader("oscura.export.wireshark"),
+            autoescape=select_autoescape(),
+        )
+
+    def generate(self, protocol: ProtocolDefinition, output_path: Path) -> None:
+        """Generate Lua dissector file.
+
+        Args:
+            protocol: Protocol definition to export
+            output_path: Where to write .lua file
+
+        Raises:
+            RuntimeError: If Lua syntax validation fails
+        """
+        lua_code = self.generate_to_string(protocol)
+
+        # Validate if requested
+        if self.validate:
+            is_valid, error_msg = validate_lua_syntax(lua_code)
+            if not is_valid:
+                raise RuntimeError(f"Generated Lua code has syntax errors:\n{error_msg}")
+
+        # Write to file
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(lua_code)
+
+    def generate_to_string(self, protocol: ProtocolDefinition) -> str:
+        """Generate Lua dissector as string.
+
+        Args:
+            protocol: Protocol definition to export
+
+        Returns:
+            Generated Lua code
+
+        Raises:
+            ValueError: If protocol definition is invalid
+        """
+        # Validate protocol
+        if not protocol.name:
+            raise ValueError("Protocol name is required")
+
+        # Prepare template context
+        context = self._build_template_context(protocol)
+
+        # Render template
+        template = self.env.get_template("dissector.lua.j2")
+        return template.render(**context)
+
+    def _build_template_context(self, protocol: ProtocolDefinition) -> dict[str, Any]:
+        """Build context dictionary for template rendering.
+
+        Args:
+            protocol: Protocol definition
+
+        Returns:
+            Template context dictionary
+        """
+        # Generate proto variable name (lowercase, no spaces)
+        proto_var = protocol.name.lower().replace(" ", "_").replace("-", "_") + "_proto"
+
+        # Process fields and calculate offsets
+        field_data = []
+        field_offsets = {}  # Track offset of each field by name
+        current_offset = 0
+        min_length = 0
+
+        for field_def in protocol.fields:
+            # Store offset for this field
+            field_offsets[field_def.name] = current_offset
+
+            field_info = self._process_field(field_def, protocol, field_offsets)
+            field_data.append(field_info)
+
+            # Update offset for next field (if fixed size)
+            if field_info["size"] is not None and not field_info["is_variable_length"]:
+                current_offset += field_info["size"]
+
+            # Calculate minimum length (sum of fixed-size fields)
+            if not field_info["is_variable_length"]:
+                min_length += field_info["size"]
+
+        # Extract transport settings
+        transport = None
+        port = None
+
+        if "transport" in protocol.settings:
+            transport = protocol.settings["transport"]
+        if "port" in protocol.settings:
+            port = protocol.settings["port"]
+
+        # Check framing for transport/port
+        if transport is None and "transport" in protocol.framing:
+            transport = protocol.framing["transport"]
+        if port is None and "port" in protocol.framing:
+            port = protocol.framing["port"]
+
+        context = {
+            "protocol": protocol,
+            "proto_var": proto_var,
+            "fields": field_data,
+            "min_length": max(min_length, 1),  # At least 1 byte
+            "timestamp": datetime.now(UTC).isoformat(),
+            "transport": transport,
+            "port": port,
+            "pattern": protocol.framing.get("sync_pattern"),
+        }
+
+        return context
+
+    def _process_field(
+        self,
+        field_def: FieldDefinition,
+        protocol: ProtocolDefinition,
+        field_offsets: dict[str, int],
+    ) -> dict[str, Any]:
+        """Process a field definition for template rendering.
+
+        Args:
+            field_def: Field definition
+            protocol: Parent protocol definition
+            field_offsets: Dictionary mapping field names to byte offsets
+
+        Returns:
+            Dictionary with field information for template
+        """
+        # Get ProtoField type and display base
+        protofield_type, display_base = get_protofield_type(field_def.field_type)
+
+        # Get field size
+        size = get_field_size(field_def.field_type)
+        is_variable = size is None
+
+        # Handle explicit size specification
+        if field_def.size is not None:
+            if isinstance(field_def.size, int):
+                size = field_def.size
+                is_variable = False
+            elif isinstance(field_def.size, str):
+                # Size is a reference to another field
+                is_variable = True
+
+        # Generate display name
+        display_name = field_def.description or field_def.name.replace("_", " ").title()
+
+        # Get Lua reader function
+        reader_func = get_lua_reader_function(field_def.field_type, field_def.endian)
+
+        field_info = {
+            "name": field_def.name,
+            "display_name": display_name,
+            "protofield_type": protofield_type,
+            "display_base": display_base,
+            "size": size,
+            "is_variable_length": is_variable,
+            "condition": field_def.condition,
+            "reader_function": reader_func,
+            "endian": field_def.endian,
+            "value_string": self._generate_value_string(field_def),
+        }
+
+        # Handle variable-length fields with size reference
+        if is_variable and isinstance(field_def.size, str):
+            # Find the size field
+            size_field_def = self._find_field(protocol, field_def.size)
+            if size_field_def:
+                size_field_size = get_field_size(size_field_def.field_type)
+                size_reader = get_lua_reader_function(
+                    size_field_def.field_type, size_field_def.endian
+                )
+
+                # Get the offset of the size field
+                size_field_offset = field_offsets.get(field_def.size, 0)
+
+                field_info.update(
+                    {
+                        "size_field": field_def.size,
+                        "size_offset": size_field_offset,
+                        "size_field_size": size_field_size,
+                        "size_reader": size_reader,
+                    }
+                )
+
+        return field_info
+
+    def _find_field(self, protocol: ProtocolDefinition, field_name: str) -> FieldDefinition | None:
+        """Find a field definition by name.
+
+        Args:
+            protocol: Protocol definition
+            field_name: Field name to find
+
+        Returns:
+            Field definition or None if not found
+        """
+        for field_def in protocol.fields:
+            if field_def.name == field_name:
+                return field_def
+        return None
+
+    def _generate_value_string(self, field_def: FieldDefinition) -> str | None:
+        """Generate Wireshark value_string table for enum fields.
+
+        Args:
+            field_def: Field definition
+
+        Returns:
+            Lua table definition or None if field has no enum
+        """
+        if not field_def.enum:
+            return None
+
+        # Generate Lua table for enum
+        entries = []
+        for key, value in field_def.enum.items():
+            if isinstance(key, int):
+                entries.append(f'[{key}] = "{value}"')
+            else:
+                # String key - try to get value
+                entries.append(f'["{key}"] = "{value}"')
+
+        return "{" + ", ".join(entries) + "}"
+
+    def _calculate_min_length(self, protocol: ProtocolDefinition) -> int:
+        """Calculate the minimum packet length for the protocol.
+
+        Args:
+            protocol: Protocol definition
+
+        Returns:
+            Minimum length in bytes
+        """
+        min_length = 0
+
+        for field_def in protocol.fields:
+            # Skip conditional fields (they might not be present)
+            if field_def.condition:
+                continue
+
+            # Get field size
+            size = get_field_size(field_def.field_type)
+
+            # Handle explicit size
+            if field_def.size is not None and isinstance(field_def.size, int):
+                size = field_def.size
+
+            # Add to minimum length if fixed size
+            if size is not None:
+                min_length += size
+
+        return max(min_length, 1)  # At least 1 byte