deaced 0.1.0__tar.gz

deaced-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-27
+
+First public release.
+
+### Added
+- Python port of [NickstaDB/SerializationDumper](https://github.com/NickstaDB/SerializationDumper)
+  as a dependency-free library + CLI.
+- Public API: `dump(data, *, format="text"|"json"|"pretty", offsets=False)` and
+  `parse(data) -> Stream`, which returns a typed semantic AST (nodes mirror
+  protocol entities; back-references are resolved against a handle table).
+- Text dump byte-for-byte compatible with the patched upstream jar; `--offsets`
+  prefixes each line with its byte offset.
+- JSON renderer (structured, machine-readable) and pretty renderer (compact data
+  tree); CLI `deaced -r/-f/-x [-o FILE] [-F text|json|pretty] [--offsets]`, stdin.
+- Layered architecture: `reader` (byte reader), `tags` (`TC`/`SC` enums),
+  `parser` (stream → AST), `model` (the AST), `render/` (visitors), with
+  dedicated exceptions that carry the byte offset.
+
+### Fixed / improved (vs upstream)
+- `(long)`/`(double)` integer-shift bug: bytes are widened before shifting, so
+  `0xFFFFFFFFFFFFFFFF` reads as `-1` (not `-4294967297`).
+- `TC_LONGSTRING` accepted as an object-field value; `TC_BLOCKDATA` /
+  `TC_BLOCKDATALONG` accepted as array-field values.
+- Strings decoded as Java modified UTF-8 (`U+0000` as `C0 80`, supplementary
+  characters as surrogate pairs); the original decoded byte-by-byte.
+- `TC_RESET` (`0x79`) and `TC_EXCEPTION` (`0x7b`) are parsed; upstream aborts on
+  both. `TC_RESET` restarts handle numbering as Java does.
+- `float`/`double` rendered with Java's exact `Double.toString` /
+  `Float.toString` notation (e.g. `1.0E7`, `1.5E-10`), not Python's `repr`.
+- `long` field type code is labelled `Long - J` (the JVM type code, JVMS 4.3.2);
+  upstream's `Long - L` is a typo (the dumped hex byte `0x4a` is already `J`).
+
+### Hardened
+- Output is always valid UTF-8: lone UTF-16 surrogates render as `?` (matching
+  the jar); previously such a value could crash the CLI on write.
+- Structurally-invalid streams (negative array sizes, field/interface counts, or
+  block-data/string lengths) are rejected with a clear `SerDumpError` instead of
+  a misleading dump or a huge allocation attempt.
+- Deeply nested streams parse with an enlarged worker-thread stack and raise a
+  clean error past a generous depth limit, instead of crashing the interpreter.
+- Parse errors distinguish end-of-stream (`EOF`) from a literal `0x00` tag.
+- `--offsets` is validated as a text-format-only option.
+
+[0.1.0]: https://github.com/gmarav/DeACED/releases/tag/v0.1.0

deaced-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to DeACED
+
+Thanks for your interest!
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Before opening a PR
+
+```bash
+ruff check .
+ruff format --check .
+mypy
+pytest -q
+```
+
+## Guidelines
+
+- Keep the core dependency-free (standard library only).
+- All code, comments and commit messages in English.
+- Add a test for every fix or new feature. Fixtures must be small and synthetic
+  (no third-party data) — the repo is public.
+- Preserve the text dump format unless intentionally changing it (it is covered by
+  a golden test); discuss format changes in an issue first.
+- Golden fixtures live in `tests/data`; regenerate them with `tools/regen_goldens.sh`
+  (needs a JDK and the patched jar -- see `tools/README.md`).
+- Update `CHANGELOG.md` and, when behaviour diverges from upstream, `NOTICE`.

deaced-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2017 Nicky Bloor (original SerializationDumper, https://github.com/NickstaDB/SerializationDumper)
+Copyright (c) 2026 Alexander Gmar (Python port, https://github.com/gmarav/DeACED)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deaced-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+# Source distribution contents. The wheel ships only the package (src/deaced);
+# the sdist additionally carries the tests + their fixtures and the dev tools so
+# it is self-contained and auditable, and `pytest` works from an unpacked sdist.
+include LICENSE
+include NOTICE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+recursive-include tests *.py
+recursive-include tests/data *.ser *.golden
+recursive-include tools *.java *.sh *.md

deaced-0.1.0/NOTICE

@@ -0,0 +1,43 @@
+DeACED
+======
+
+DeACED is a Python port of SerializationDumper by Nicky Bloor.
+
+  Original work: SerializationDumper
+  Author:        Nicky Bloor (@NickstaDB)
+  Source:        https://github.com/NickstaDB/SerializationDumper
+  License:       MIT (Copyright (c) 2017 Nicky Bloor)
+
+  Python port:   Alexander Gmar (https://github.com/gmarav/DeACED)
+  Port license:  MIT (Copyright (c) 2026 Alexander Gmar)
+
+The output format (the text dump) mirrors the original so existing dumps remain
+comparable. This port additionally fixes and extends the original:
+
+  * (long)/(double) fields: the original shifts byte operands as 32-bit ints
+    (b1 << 56 == b1 << 24) and sign-extends int masks, so 0xFFFFFFFFFFFFFFFF
+    was read as -4294967297 instead of -1 and some doubles were corrupted.
+    DeACED widens each byte to long before shifting (correct values).
+  * TC_LONGSTRING (0x7c) accepted as an object-field value.
+  * TC_BLOCKDATA (0x77) / TC_BLOCKDATALONG (0x7a) accepted as array-field values.
+  * Strings decoded as Java modified UTF-8 (the encoding serialization actually
+    uses): U+0000 as C0 80 and supplementary characters as surrogate pairs are
+    decoded correctly. The original decoded byte-by-byte, corrupting non-ASCII.
+  * TC_RESET (0x79) and TC_EXCEPTION (0x7b) are parsed; the original aborts on
+    both with "Illegal content element type".
+  * float/double values are rendered with Java's exact Double.toString /
+    Float.toString rules (shortest round-trip digits; decimal vs. scientific by
+    magnitude). This matches Java 19+ except for the smallest subnormals (a small
+    cluster near Double/Float.MIN_VALUE), where Java itself does not emit the
+    shortest digits; DeACED's output still round-trips to the identical value.
+  * The field type code for long is labelled "Long - J" (the JVM type code, per
+    JVMS 4.3.2). The original prints "Long - L", which is a typo -- the dumped
+    hex byte, 0x4a, is already ASCII 'J'.
+  * Lone UTF-16 surrogates in string/char values are rendered as '?', so output
+    is always valid UTF-8 (the original could emit an unencodable character).
+  * Structurally-invalid streams (negative array sizes, field/interface counts,
+    or block-data/string lengths) are rejected with a clear error rather than
+    silently producing a misleading partial dump.
+  * Optional byte-offset annotation mode.
+
+The "rebuild" (-b) mode of the original is not (yet) ported.

deaced-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: deaced
+Version: 0.1.0
+Summary: Dump and inspect Java Object Serialization (0xAC 0xED) streams and RMI packets in human-readable form.
+Author: Alexander Gmar
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gmarav/DeACED
+Project-URL: Repository, https://github.com/gmarav/DeACED
+Project-URL: Documentation, https://github.com/gmarav/DeACED#readme
+Project-URL: Issues, https://github.com/gmarav/DeACED/issues
+Project-URL: Changelog, https://github.com/gmarav/DeACED/blob/main/CHANGELOG.md
+Keywords: java,serialization,deserialization,rmi,security,aced,dump
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: pre-commit>=3; extra == "dev"
+Dynamic: license-file
+
+# DeACED
+
+[![CI](https://github.com/gmarav/DeACED/actions/workflows/ci.yml/badge.svg)](https://github.com/gmarav/DeACED/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)
+
+> Dump and inspect **Java Object Serialization** (`0xAC 0xED`) streams — and Java RMI
+> packet contents — in a clear, human-readable, hierarchical form.
+
+`DeACED` (a nod to the `AC ED` stream magic, and to *de*-serialization) is a small,
+**dependency-free** Python library and CLI. It is a port of
+[SerializationDumper](https://github.com/NickstaDB/SerializationDumper) by Nicky Bloor,
+with several correctness fixes (see [NOTICE](NOTICE)).
+
+## Install
+
+```bash
+pip install deaced            # once published
+# or from source:
+pip install .
+```
+
+## CLI
+
+```bash
+deaced -r dump.bin                 # raw serialized file
+cat dump.bin | deaced -r -         # from stdin
+deaced -x aced0005740004414243...  # hex on the command line
+deaced -f hexdump.txt              # file of hex-ascii bytes
+deaced -r dump.bin --offsets       # prefix each line with '@<byte-offset>|'
+deaced -r dump.bin -o out.txt      # write to a file
+deaced -r dump.bin -F json         # structured, machine-readable JSON
+deaced -r dump.bin -F pretty       # compact, human-readable data tree
+```
+
+Example:
+
+```text
+$ deaced -x aced0005740004414243447071007e0000
+
+STREAM_MAGIC - 0xac ed
+STREAM_VERSION - 0x00 05
+Contents
+  TC_STRING - 0x74
+    newHandle 0x00 7e 00 00
+    Length - 4 - 0x00 04
+    Value - ABCD - 0x41424344
+  TC_NULL - 0x70
+  TC_REFERENCE - 0x71
+    Handle - 8257536 - 0x00 7e 00 00
+```
+
+## Library
+
+```python
+from deaced import dump, parse
+
+data = open("dump.bin", "rb").read()
+
+print(dump(data))                       # text dump (default)
+print(dump(data, offsets=True))         # with '@<offset>|' prefixes
+print(dump(data, format="json"))        # structured JSON
+print(dump(data, format="pretty"))      # compact human-readable tree
+
+tree = parse(data)                      # the semantic AST (deaced.model.Stream)
+```
+
+## Why a port?
+
+Removes the JVM dependency (the original is a Java jar), runs anywhere Python does,
+integrates into Python tooling, and fixes real bugs in the original — most notably
+the `(long)`/`(double)` integer-shift bug (`0xFFFFFFFFFFFFFFFF` was shown as
+`-4294967297` instead of `-1`). See [NOTICE](NOTICE) for the full list.
+
+## Safety
+
+DeACED is built to inspect **untrusted, attacker-controlled** serialization
+streams (that is the usual reason to dump one), so:
+
+- **It never deserializes Java objects.** DeACED only reads and decodes the byte
+  stream into a descriptive tree — it does not load classes, instantiate objects,
+  or invoke `readObject`. The classic Java deserialization gadget chains cannot
+  fire through it.
+- **It fails cleanly on malformed input.** Truncated or structurally-invalid
+  streams raise a `SerDumpError` carrying the byte offset; negative
+  lengths/counts are rejected rather than driving huge allocations; deeply nested
+  streams raise an error instead of crashing the interpreter.
+
+Resource use is still proportional to input size — apply your own limits when
+dumping data straight off the network. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest            # tests (tiny synthetic fixtures)
+ruff check .
+ruff format --check .
+mypy
+```
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING](CONTRIBUTING.md). The stream "rebuild"
+(`-b`) mode of the original is intentionally not ported (see [NOTICE](NOTICE)).
+
+## Credits & license
+
+Python port by **Alexander Gmar** ([@gmarav](https://github.com/gmarav)) —
+[github.com/gmarav/DeACED](https://github.com/gmarav/DeACED).
+Based on **SerializationDumper** by **Nicky Bloor** ([@NickstaDB](https://github.com/NickstaDB)).
+Licensed under the [MIT License](LICENSE); port © 2026 Alexander Gmar, original © 2017 Nicky Bloor.

deaced-0.1.0/README.md

@@ -0,0 +1,112 @@
+# DeACED
+
+[![CI](https://github.com/gmarav/DeACED/actions/workflows/ci.yml/badge.svg)](https://github.com/gmarav/DeACED/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)
+
+> Dump and inspect **Java Object Serialization** (`0xAC 0xED`) streams — and Java RMI
+> packet contents — in a clear, human-readable, hierarchical form.
+
+`DeACED` (a nod to the `AC ED` stream magic, and to *de*-serialization) is a small,
+**dependency-free** Python library and CLI. It is a port of
+[SerializationDumper](https://github.com/NickstaDB/SerializationDumper) by Nicky Bloor,
+with several correctness fixes (see [NOTICE](NOTICE)).
+
+## Install
+
+```bash
+pip install deaced            # once published
+# or from source:
+pip install .
+```
+
+## CLI
+
+```bash
+deaced -r dump.bin                 # raw serialized file
+cat dump.bin | deaced -r -         # from stdin
+deaced -x aced0005740004414243...  # hex on the command line
+deaced -f hexdump.txt              # file of hex-ascii bytes
+deaced -r dump.bin --offsets       # prefix each line with '@<byte-offset>|'
+deaced -r dump.bin -o out.txt      # write to a file
+deaced -r dump.bin -F json         # structured, machine-readable JSON
+deaced -r dump.bin -F pretty       # compact, human-readable data tree
+```
+
+Example:
+
+```text
+$ deaced -x aced0005740004414243447071007e0000
+
+STREAM_MAGIC - 0xac ed
+STREAM_VERSION - 0x00 05
+Contents
+  TC_STRING - 0x74
+    newHandle 0x00 7e 00 00
+    Length - 4 - 0x00 04
+    Value - ABCD - 0x41424344
+  TC_NULL - 0x70
+  TC_REFERENCE - 0x71
+    Handle - 8257536 - 0x00 7e 00 00
+```
+
+## Library
+
+```python
+from deaced import dump, parse
+
+data = open("dump.bin", "rb").read()
+
+print(dump(data))                       # text dump (default)
+print(dump(data, offsets=True))         # with '@<offset>|' prefixes
+print(dump(data, format="json"))        # structured JSON
+print(dump(data, format="pretty"))      # compact human-readable tree
+
+tree = parse(data)                      # the semantic AST (deaced.model.Stream)
+```
+
+## Why a port?
+
+Removes the JVM dependency (the original is a Java jar), runs anywhere Python does,
+integrates into Python tooling, and fixes real bugs in the original — most notably
+the `(long)`/`(double)` integer-shift bug (`0xFFFFFFFFFFFFFFFF` was shown as
+`-4294967297` instead of `-1`). See [NOTICE](NOTICE) for the full list.
+
+## Safety
+
+DeACED is built to inspect **untrusted, attacker-controlled** serialization
+streams (that is the usual reason to dump one), so:
+
+- **It never deserializes Java objects.** DeACED only reads and decodes the byte
+  stream into a descriptive tree — it does not load classes, instantiate objects,
+  or invoke `readObject`. The classic Java deserialization gadget chains cannot
+  fire through it.
+- **It fails cleanly on malformed input.** Truncated or structurally-invalid
+  streams raise a `SerDumpError` carrying the byte offset; negative
+  lengths/counts are rejected rather than driving huge allocations; deeply nested
+  streams raise an error instead of crashing the interpreter.
+
+Resource use is still proportional to input size — apply your own limits when
+dumping data straight off the network. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest            # tests (tiny synthetic fixtures)
+ruff check .
+ruff format --check .
+mypy
+```
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING](CONTRIBUTING.md). The stream "rebuild"
+(`-b`) mode of the original is intentionally not ported (see [NOTICE](NOTICE)).
+
+## Credits & license
+
+Python port by **Alexander Gmar** ([@gmarav](https://github.com/gmarav)) —
+[github.com/gmarav/DeACED](https://github.com/gmarav/DeACED).
+Based on **SerializationDumper** by **Nicky Bloor** ([@NickstaDB](https://github.com/NickstaDB)).
+Licensed under the [MIT License](LICENSE); port © 2026 Alexander Gmar, original © 2017 Nicky Bloor.

deaced-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deaced"
+version = "0.1.0"
+description = "Dump and inspect Java Object Serialization (0xAC 0xED) streams and RMI packets in human-readable form."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Alexander Gmar" }]
+keywords = ["java", "serialization", "deserialization", "rmi", "security", "aced", "dump"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Topic :: Security",
+    "Topic :: Software Development :: Disassemblers",
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/gmarav/DeACED"
+Repository = "https://github.com/gmarav/DeACED"
+Documentation = "https://github.com/gmarav/DeACED#readme"
+Issues = "https://github.com/gmarav/DeACED/issues"
+Changelog = "https://github.com/gmarav/DeACED/blob/main/CHANGELOG.md"
+
+[project.scripts]
+deaced = "deaced.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov>=4", "ruff>=0.4", "mypy>=1.8", "build>=1", "twine>=5", "pre-commit>=3"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+deaced = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/deaced"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["deaced"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 90

deaced-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deaced-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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())