deaced 0.1.0__py3-none-any.whl

deaced/__init__.py

@@ -0,0 +1,49 @@
+"""DeACED - dump and inspect Java Object Serialization (``0xAC 0xED``) streams.
+
+A small, dependency-free library and CLI that turns a Java serialization stream
+(and Java RMI packet contents) into a human-readable, hierarchical text dump.
+
+This is a Python port of SerializationDumper by Nicky Bloor (MIT); see NOTICE.
+"""
+
+from __future__ import annotations
+
+from .model import Stream
+from .parser import Parser, parse, run_deep
+from .render import render_json, render_pretty, render_text
+
+__all__ = ["dump", "parse", "__version__"]
+__version__ = "0.1.0"
+
+_FORMATS = ("text", "json", "pretty")
+
+
+def dump(data: bytes, *, format: str = "text", offsets: bool = False) -> str:
+    """Parse ``data`` and render it.
+
+    Args:
+        data: The raw serialization stream.
+        format: Output format -- ``"text"`` (the default hierarchical dump,
+            byte-for-byte compatible with the patched upstream jar), ``"json"``
+            (a structured machine-readable view), or ``"pretty"`` (a compact
+            human-readable data tree).
+        offsets: When true (``text`` only), prefix every line with
+            ``@<byte-offset>|``.
+
+    Returns:
+        The rendered output as a single string.
+    """
+    if format not in _FORMATS:
+        raise ValueError(f"unknown format: {format!r}")
+    if offsets and format != "text":
+        raise ValueError("offsets are only supported for the 'text' format")
+
+    def render() -> str:
+        node: Stream = Parser(data).parse()
+        if format == "text":
+            return render_text(node, offsets=offsets)
+        if format == "json":
+            return render_json(node)
+        return render_pretty(node)
+
+    return run_deep(render)

deaced/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m deaced``."""
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

deaced/cli.py

@@ -0,0 +1,94 @@
+"""Command-line interface for DeACED."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, dump
+
+
+def _read_input(args: argparse.Namespace) -> bytes:
+    if args.hex is not None:
+        return bytes.fromhex("".join(args.hex.split()))
+    if args.hex_file is not None:
+        with open(args.hex_file, "rb") as f:
+            txt = f.read().decode("latin-1")
+        return bytes.fromhex("".join(c for c in txt if c in "0123456789abcdefABCDEF"))
+    # raw bytes ('-' = stdin)
+    if args.raw == "-":
+        return sys.stdin.buffer.read()
+    with open(args.raw, "rb") as f:
+        return f.read()
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="deaced",
+        description="Dump and inspect Java Object Serialization (0xAC 0xED) streams "
+        "and RMI packets in human-readable form.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  deaced -r dump.bin                 dump a raw serialized file\n"
+            "  cat dump.bin | deaced -r -         read from stdin\n"
+            "  deaced -x aced0005740004414243...  decode hex from the command line\n"
+            "  deaced -f hexdump.txt              read a file of hex-ascii bytes\n"
+            "  deaced -r dump.bin -F json         emit structured JSON\n"
+            "  deaced -r dump.bin -F pretty       emit a compact data tree\n"
+            "  deaced -r dump.bin --offsets       annotate each line with its byte offset\n"
+            "  deaced -r dump.bin -o out.txt      write the dump to a file"
+        ),
+    )
+    src = p.add_mutually_exclusive_group(required=True)
+    src.add_argument(
+        "-r", "--raw", metavar="FILE", help="raw binary serialization file ('-' for stdin)"
+    )
+    src.add_argument(
+        "-f", "--hex-file", metavar="FILE", dest="hex_file", help="file of hex-ascii bytes"
+    )
+    src.add_argument("-x", "--hex", metavar="HEX", help="hex-ascii bytes on the command line")
+    p.add_argument("-o", "--output", metavar="FILE", help="write the dump to FILE (default stdout)")
+    p.add_argument(
+        "-F",
+        "--format",
+        choices=["text", "json", "pretty"],
+        default="text",
+        help="output format (default: text)",
+    )
+    p.add_argument(
+        "--offsets",
+        action="store_true",
+        help="prefix each line with '@<byte-offset>|' (text format only)",
+    )
+    p.add_argument("-V", "--version", action="version", version=f"deaced {__version__}")
+    args = p.parse_args(argv)
+
+    if args.offsets and args.format != "text":
+        p.error("--offsets is only valid with -F text")
+
+    try:
+        data = _read_input(args)
+    except (OSError, ValueError) as e:
+        print(f"deaced: cannot read input: {e}", file=sys.stderr)
+        return 2
+
+    try:
+        text = dump(data, format=args.format, offsets=args.offsets)
+    except Exception as e:  # parser errors carry an offset in the message
+        print(f"deaced: parse error: {e}", file=sys.stderr)
+        return 1
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(text)
+    else:
+        reconfigure = getattr(sys.stdout, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8")
+        sys.stdout.write(text)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

deaced/errors.py

@@ -0,0 +1,27 @@
+"""Exception types for DeACED.
+
+Every error carries the byte offset in the serialization stream where it was
+detected, which makes truncated or malformed streams much easier to diagnose.
+"""
+
+from __future__ import annotations
+
+
+class SerDumpError(Exception):
+    """Base class for all DeACED parse errors."""
+
+    def __init__(self, message: str, offset: int | None = None) -> None:
+        self.offset = offset
+        super().__init__(f"{message} (at offset {offset})" if offset is not None else message)
+
+
+class TruncatedStreamError(SerDumpError):
+    """The stream ended before the expected number of bytes was available."""
+
+
+class UnknownTagError(SerDumpError):
+    """An unexpected or illegal type-code byte was encountered."""
+
+
+class IllegalStateError(SerDumpError):
+    """The stream violated a structural rule of the serialization protocol."""

deaced/jfloat.py

@@ -0,0 +1,86 @@
+"""Format floats/doubles exactly as Java's ``Double.toString`` / ``Float.toString``.
+
+The reference dumper is Java, so to reproduce its output we must match Java's
+notation: decimal form when ``1e-3 <= |x| < 1e7`` and "computerized scientific
+notation" (``d.dddEexp``) otherwise, always with at least one fractional digit,
+an uppercase ``E`` and no ``+`` on the exponent.
+
+The shortest round-tripping digits are found by formatting with increasing
+precision until the value reparses to the identical bit pattern (checked via
+:mod:`struct`), which matches the shortest-representation algorithm Java uses
+(JDK 19+). Java itself does not emit the shortest digits for the smallest
+subnormals (a small cluster near ``Double``/``Float.MIN_VALUE``), so DeACED
+diverges from Java there; every value it prints still round-trips exactly.
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+
+
+def _shortest_sci(m: float, fmt: str, max_prec: int) -> str:
+    """Return Python scientific notation with the fewest digits that round-trips."""
+    target = struct.pack(fmt, m)
+    for prec in range(max_prec + 1):
+        s = f"{m:.{prec}e}"
+        try:
+            packed = struct.pack(fmt, float(s))
+        except OverflowError:
+            # rounding pushed the value just past the type's max; try more digits
+            continue
+        if packed == target:
+            return s
+    return f"{m:.{max_prec}e}"
+
+
+def _parts(sci: str) -> tuple[str, int]:
+    """Split Python scientific notation into (significant digits, exponent-of-first-digit)."""
+    mant, _, exp = sci.partition("e")
+    sci_exp = int(exp)
+    digits = mant.lstrip("+-").replace(".", "").rstrip("0") or "0"
+    return digits, sci_exp
+
+
+def _format(neg: bool, digits: str, sci_exp: int) -> str:
+    sign = "-" if neg else ""
+    n = len(digits)
+    if -3 <= sci_exp <= 6:
+        if sci_exp >= 0:
+            int_len = sci_exp + 1
+            if n <= int_len:
+                int_part = digits + "0" * (int_len - n)
+                frac = "0"
+            else:
+                int_part = digits[:int_len]
+                frac = digits[int_len:]
+        else:
+            int_part = "0"
+            frac = "0" * (-sci_exp - 1) + digits
+        return f"{sign}{int_part}.{frac}"
+    mant = digits + ".0" if n == 1 else digits[0] + "." + digits[1:]
+    return f"{sign}{mant}E{sci_exp}"
+
+
+def _to_string(v: float, fmt: str, max_prec: int) -> str:
+    if v != v:
+        return "NaN"
+    if v == math.inf:
+        return "Infinity"
+    if v == -math.inf:
+        return "-Infinity"
+    neg = math.copysign(1.0, v) < 0
+    if v == 0.0:
+        return "-0.0" if neg else "0.0"
+    digits, sci_exp = _parts(_shortest_sci(abs(v), fmt, max_prec))
+    return _format(neg, digits, sci_exp)
+
+
+def double_to_string(v: float) -> str:
+    """Format ``v`` as Java ``Double.toString`` would."""
+    return _to_string(v, ">d", 16)
+
+
+def float_to_string(v: float) -> str:
+    """Format a 32-bit float value ``v`` as Java ``Float.toString`` would."""
+    return _to_string(v, ">f", 8)

deaced/model.py

@@ -0,0 +1,209 @@
+"""Semantic AST for a parsed Java Object Serialization stream (ADR-0001).
+
+Nodes mirror the entities of the serialization protocol, not the text dump:
+there are no presentation-only grouping nodes here -- the text renderer adds
+lines like ``Contents``/``values``/``(object)``. Each node keeps the raw bytes
+of its primitives -- the renderers use them to reproduce the hex columns and, in
+``--offsets`` mode, to advance their own byte cursor -- and records its source
+``offset`` (start position in the stream) so callers can map a node back to the
+input.
+
+:class:`Stream` is the root; :attr:`Stream.handles` maps wire handles to the
+node that owns them, so :class:`Reference` targets can be resolved.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Utf:
+    """A plain modified-UTF-8 string (class/field/interface name; no handle)."""
+
+    value: str
+    raw: bytes
+
+
+@dataclass
+class Node:
+    """Base class for every AST node; ``offset`` is the start byte position."""
+
+    offset: int
+
+
+# --- values (may appear as stream content, field values or array elements) ---
+
+
+@dataclass
+class Null(Node):
+    """``TC_NULL`` -- a null reference."""
+
+
+@dataclass
+class Reference(Node):
+    """``TC_REFERENCE`` -- a back-reference to a previously seen handle."""
+
+    handle: int
+    target: Node | None = None
+
+
+@dataclass
+class StringVal(Node):
+    """``TC_STRING`` / ``TC_LONGSTRING`` -- a string object with a handle."""
+
+    handle: int
+    value: str
+    raw: bytes
+    long: bool = False
+
+
+@dataclass
+class Primitive(Node):
+    """A primitive field/array value (type code one of ``BCDFIJSZ``)."""
+
+    tc: str
+    value: int | float | bool
+    raw: bytes
+
+
+@dataclass
+class BlockData(Node):
+    """``TC_BLOCKDATA`` / ``TC_BLOCKDATALONG`` -- an opaque byte block."""
+
+    data: bytes
+    long: bool = False
+
+
+@dataclass
+class Reset(Node):
+    """``TC_RESET`` -- resets the stream's handle table to the base handle."""
+
+
+@dataclass
+class ExceptionObj(Node):
+    """``TC_EXCEPTION`` -- a serialized Throwable describing a serialization abort."""
+
+    throwable: Node
+
+
+@dataclass
+class ClassObj(Node):
+    """``TC_CLASS`` -- a Class object."""
+
+    handle: int
+    class_desc: ClassDescLike
+
+
+@dataclass
+class EnumObj(Node):
+    """``TC_ENUM`` -- an enum constant."""
+
+    handle: int
+    class_desc: ClassDescLike
+    constant: StringVal | Reference
+
+
+@dataclass
+class ArrayObj(Node):
+    """``TC_ARRAY`` -- an array object.
+
+    ``component`` is the element type code (the second char of the array class
+    name). For a ``byte[]`` the data is kept in ``byte_values``; otherwise each
+    element is a node in ``elements``.
+    """
+
+    handle: int
+    class_desc: ClassDescLike
+    component: str
+    size: int
+    elements: list[Node] = field(default_factory=list)
+    byte_values: bytes = b""
+
+
+@dataclass
+class ObjectInstance(Node):
+    """``TC_OBJECT`` -- a serialized object instance."""
+
+    handle: int
+    class_desc: ClassDescLike
+    data: list[ClassData] = field(default_factory=list)
+    na: bool = False
+
+
+# --- class descriptions (the classDesc slot: one of these or Null/Reference) ---
+
+
+@dataclass
+class FieldDesc:
+    """A field declaration inside a class description."""
+
+    tc: str
+    name: Utf
+    class_name1: StringVal | Reference | None = None
+
+
+@dataclass
+class ClassDesc(Node):
+    """``TC_CLASSDESC`` -- a concrete class description."""
+
+    name: Utf
+    svuid: bytes
+    handle: int
+    flags: int
+    fields: list[FieldDesc] = field(default_factory=list)
+    annotations: list[Node] = field(default_factory=list)
+    super_desc: ClassDescLike | None = None
+
+
+@dataclass
+class ProxyClassDesc(Node):
+    """``TC_PROXYCLASSDESC`` -- a dynamic proxy class description."""
+
+    handle: int
+    interfaces: list[Utf] = field(default_factory=list)
+    annotations: list[Node] = field(default_factory=list)
+    super_desc: ClassDescLike | None = None
+
+
+# --- object-instance class data ---
+
+
+@dataclass
+class FieldValue:
+    """One field's value within a class's slice of an object's data."""
+
+    name: str
+    declared_tc: str
+    value: Node
+
+
+@dataclass
+class ClassData:
+    """One class's contribution to an object's data (values + annotations)."""
+
+    class_name: str
+    serializable: bool
+    values: list[FieldValue] = field(default_factory=list)
+    has_annotation: bool = False
+    annotations: list[Node] = field(default_factory=list)
+
+
+# --- root ---
+
+
+@dataclass
+class Stream(Node):
+    """The parsed stream: optional RMI prefix, header, and top-level contents."""
+
+    magic: bytes
+    magic_valid: bool
+    version: bytes | None = None
+    version_valid: bool = False
+    rmi: int | None = None
+    contents: list[Node] = field(default_factory=list)
+    handles: dict[int, Node] = field(default_factory=dict)
+
+
+#: Anything that can occupy a ``classDesc`` slot.
+ClassDescLike = ClassDesc | ProxyClassDesc | Null | Reference

deaced/mutf8.py

@@ -0,0 +1,70 @@
+"""Java "modified UTF-8" -- the string encoding used by serialization.
+
+``DataOutput.writeUTF`` / ``DataInput.readUTF`` (and therefore the Object
+Serialization Stream Protocol) encode strings in a variant of UTF-8 that differs
+from the standard in exactly two ways:
+
+* ``U+0000`` is written as the two bytes ``C0 80`` (never a bare ``00``);
+* characters outside the Basic Multilingual Plane are written as a UTF-16
+  surrogate pair, each surrogate emitted in its 3-byte form (i.e. CESU-8), rather
+  than as one 4-byte UTF-8 sequence.
+
+For every other (BMP, non-zero) character it is identical to standard UTF-8.
+Decoding is tolerant: malformed sequences yield U+FFFD rather than raising.
+"""
+
+from __future__ import annotations
+
+_REPLACEMENT = 0xFFFD
+
+
+def decode(data: bytes) -> str:
+    """Decode modified-UTF-8 ``data`` into a string."""
+    units = bytearray()  # UTF-16 code units, big-endian
+    i = 0
+    n = len(data)
+    while i < n:
+        a = data[i]
+        if a < 0x80:
+            unit = a
+            i += 1
+        elif (a & 0xE0) == 0xC0:
+            if i + 1 < n and (data[i + 1] & 0xC0) == 0x80:
+                unit = ((a & 0x1F) << 6) | (data[i + 1] & 0x3F)
+                i += 2
+            else:
+                unit = _REPLACEMENT
+                i += 1
+        elif (a & 0xF0) == 0xE0:
+            if i + 2 < n and (data[i + 1] & 0xC0) == 0x80 and (data[i + 2] & 0xC0) == 0x80:
+                unit = ((a & 0x0F) << 12) | ((data[i + 1] & 0x3F) << 6) | (data[i + 2] & 0x3F)
+                i += 3
+            else:
+                unit = _REPLACEMENT
+                i += 1
+        else:
+            unit = _REPLACEMENT
+            i += 1
+        units += unit.to_bytes(2, "big")
+    # Combine surrogate pairs; keep lone surrogates as-is (Java permits them).
+    return units.decode("utf-16-be", errors="surrogatepass")
+
+
+def encode(text: str) -> bytes:
+    """Encode ``text`` as modified UTF-8."""
+    b16 = text.encode("utf-16-be", errors="surrogatepass")
+    out = bytearray()
+    for j in range(0, len(b16), 2):
+        unit = (b16[j] << 8) | b16[j + 1]
+        if unit == 0x0000:
+            out += b"\xc0\x80"
+        elif unit <= 0x7F:
+            out.append(unit)
+        elif unit <= 0x7FF:
+            out.append(0xC0 | (unit >> 6))
+            out.append(0x80 | (unit & 0x3F))
+        else:
+            out.append(0xE0 | (unit >> 12))
+            out.append(0x80 | ((unit >> 6) & 0x3F))
+            out.append(0x80 | (unit & 0x3F))
+    return bytes(out)