tentod 0.1.0__py3-none-any.whl

tentod/GUIDE.md

@@ -0,0 +1,53 @@
+# tentod — guide for automated (LLM) use
+
+tentod recovers readable Python from .NET assemblies in stages. The
+deterministic stages are commands; the one creative stage (writing the Python)
+is done by you, the model, against the contract below. Print this any time with
+`python -m tentod guide`.
+
+## Turnkey workflow
+
+Given one assembly, or a list/folder of them, process **each assembly
+independently** — they share nothing, so fan out one worker per assembly and run
+these steps for each:
+
+1. **Recover.** `python -m tentod recover <assembly.dll>`
+   - If it prints `SKIP not a managed assembly`, the file is native or not a
+     .NET assembly — move on, it is not yours to process.
+   - Otherwise it prints the paths of the decompiled C#, the **deobfuscated C#**,
+     and `facts.json`, plus counts (`types`/`strings`/`routes`/`inlined`).
+2. **Read** the deobfuscated C# and `facts.json`. The deobfuscated C# is the
+   source of truth for control flow and every literal (routes, keys, headers).
+3. **Write** the Python module (see the contract below). Map the assembly's
+   namespace to directories: `A.B.C` → `A/B/C.py`.
+4. **Verify.** `python -m tentod verify <assembly.dll> <your_output.py>`
+   - Resolve every entry under `missing` (a required literal your Python lacks).
+   - Review every entry under `omitted`: each must be something you dropped on
+     purpose (an internal log line, a diagnostic message) — never a route, query
+     key, header, or secret name.
+5. **Report** the coverage line and any deliberate omissions for that assembly.
+
+Work on independent assemblies concurrently; each worker owns one assembly end
+to end (recover → write → verify).
+
+## Style contract for the Python you write
+
+Faithful, idiomatic Python — not a mechanical transliteration of the C#.
+
+1. **One module** at the namespace-mapped path.
+2. **Class-based.** No module-level functions. The public surface is a single
+   class; each user-facing operation is one public method.
+3. **Private helpers are `__`-prefixed** (name-mangled) — request building, key
+   resolution, response handling.
+4. **Module-level `CONSTANTS`** (base URLs, defaults) are fine.
+5. **Faithful.** Use the exact literals from the C#/facts. Invent nothing.
+   Reproduce behavior, not the C# class hierarchy — skip DTOs, DI, and
+   async-state-machine scaffolding a client does not need.
+6. **Type hints throughout.** Prefer the standard library.
+7. **Docstring states provenance** and lists any endpoints/behavior you
+   intentionally left out, so the omission is a decision, not an oversight.
+
+## Done
+
+`python -m tentod verify` reports `OK` (nothing under `missing`) and every
+`omitted` entry is one you can justify.

tentod/__init__.py

@@ -0,0 +1 @@
+"""tentod."""

tentod/__main__.py

@@ -0,0 +1,81 @@
+"""CLI."""
+
+from pathlib import Path
+
+from class_argparse import ClassArgParser
+
+from .assembly import DotNetAssembly, NotManagedAssembly
+from .pipeline import DotNetRecoveryPipeline
+
+DEFAULT_OUT_ROOT = "out"
+GUIDE = Path(__file__).with_name("GUIDE.md")
+
+
+class Main(ClassArgParser):
+    """tentod."""
+
+    def __init__(self) -> None:
+        super().__init__(name="tentod")
+
+    def __resolve(self, assembly: str) -> str:
+        p = Path(assembly)
+        if p.exists():
+            return str(p)
+        if not p.suffix:
+            withdll = p.with_suffix(".dll")
+            if withdll.exists():
+                return str(withdll)
+        raise SystemExit(f"not found: {assembly}")
+
+    def guide(self):
+        print(GUIDE.read_text())
+
+    def recover(
+        self,
+        assembly: str,
+        out_dir: str = DEFAULT_OUT_ROOT,
+        force: bool = False,
+    ):
+        dll = self.__resolve(assembly)
+        try:
+            result = DotNetRecoveryPipeline(dll, out_dir).recover(force=force)
+        except NotManagedAssembly:
+            print(f"SKIP not a managed assembly: {dll}")
+            return
+        print(result.csharp)
+        print(result.deobfuscated)
+        print(result.facts_path)
+        print(
+            f"types={len(result.facts.types)} "
+            f"strings={len(result.facts.flat_strings())} "
+            f"routes={len(result.facts.routes)} "
+            f"inlined={result.replacements}"
+        )
+
+    def verify(
+        self,
+        assembly: str,
+        python: str,
+        out_dir: str = DEFAULT_OUT_ROOT,
+    ):
+        dll = self.__resolve(assembly)
+        report = DotNetRecoveryPipeline(dll, out_dir).verify(python)
+        print(report.render())
+        if not report.ok:
+            raise SystemExit(1)
+
+    def strings(self, assembly: str):
+        try:
+            asm = DotNetAssembly.load(self.__resolve(assembly))
+        except NotManagedAssembly:
+            print(f"SKIP not a managed assembly: {assembly}")
+            return
+        for bank, entries in asm.decrypt_strings().items():
+            print(f"### {bank}")
+            for name, value in entries.items():
+                print(f"    {name}() = {value!r}")
+            print()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    Main()()

tentod/_runtime.py

@@ -0,0 +1,21 @@
+"""Runtime bootstrap."""
+
+import functools
+import os
+
+
+@functools.lru_cache(maxsize=1)
+def runtime():  # pragma: no cover
+    os.environ.setdefault("PYTHONNET_RUNTIME", "mono")
+    import clr  # noqa: F401
+
+    from System.Reflection import Assembly, BindingFlags
+
+    flags = (
+        BindingFlags.Static
+        | BindingFlags.Instance
+        | BindingFlags.Public
+        | BindingFlags.NonPublic
+        | BindingFlags.DeclaredOnly
+    )
+    return Assembly, flags

tentod/assembly.py

@@ -0,0 +1,134 @@
+"""Assembly reflection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ._runtime import runtime
+
+
+class NotManagedAssembly(Exception):
+    """Raised when a file is not a managed assembly (e.g. a native DLL)."""
+
+
+@dataclass
+class MethodInfo:
+    name: str
+    static: bool
+    returns: str
+    params: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TypeInfo:
+    fullname: str
+    kind: str
+    methods: list[MethodInfo] = field(default_factory=list)
+    enum_members: list[str] = field(default_factory=list)
+
+
+class DotNetAssembly:
+    """A loaded assembly queried through reflection."""
+
+    __STRING_BANK_MIN = 3
+
+    def __init__(self, asm, flags=None) -> None:
+        self.__asm = asm
+        self.__flags = flags
+
+    @classmethod
+    def load(cls, dll_path: str) -> "DotNetAssembly":
+        assembly, flags = runtime()
+        try:
+            obj = assembly.LoadFrom(str(dll_path))
+        except Exception as e:
+            if "BadImageFormat" in type(e).__name__:
+                raise NotManagedAssembly(str(dll_path)) from e
+            raise
+        return cls(obj, flags)
+
+    @property
+    def full_name(self) -> str:
+        return str(self.__asm.FullName)
+
+    def __types(self):
+        try:
+            return list(self.__asm.GetTypes())
+        except Exception as e:
+            loaded = getattr(e, "Types", None)
+            return [t for t in loaded if t is not None] if loaded else []
+
+    def __is_accessor(self, m) -> bool:
+        return (
+            m.IsStatic
+            and m.ReturnType.Name == "String"
+            and len(m.GetParameters()) == 0
+            and not m.Name.startswith("get_")
+        )
+
+    def __string_banks(self):
+        banks = []
+        for t in self.__types():
+            accessors = [m for m in t.GetMethods(self.__flags) if self.__is_accessor(m)]
+            if len(accessors) >= self.__STRING_BANK_MIN:
+                banks.append((t, accessors))
+        return banks
+
+    def decrypt_strings(self) -> dict[str, dict[str, str]]:
+        out: dict[str, dict[str, str]] = {}
+        for t, accessors in self.__string_banks():
+            bank: dict[str, str] = {}
+            for m in accessors:
+                try:
+                    bank[m.Name] = str(m.Invoke(None, None))
+                except Exception:
+                    continue
+            if bank:
+                out[t.Name] = bank
+        return out
+
+    def enums(self) -> dict[str, list[str]]:
+        out: dict[str, list[str]] = {}
+        for t in self.__types():
+            if t.IsEnum:
+                try:
+                    out[t.FullName] = list(t.GetEnumNames())
+                except Exception:
+                    out[t.FullName] = []
+        return out
+
+    def __kind(self, t) -> str:
+        if t.IsEnum:
+            return "enum"
+        if t.IsInterface:
+            return "interface"
+        if t.IsValueType:
+            return "struct"
+        return "class"
+
+    def types(self, include_generated: bool = False) -> list[TypeInfo]:
+        bank_names = {t.Name for t, _ in self.__string_banks()}
+        result: list[TypeInfo] = []
+        for t in self.__types():
+            if not include_generated and (
+                t.Name in bank_names or "PrivateImplementationDetails" in t.FullName
+            ):
+                continue
+            ti = TypeInfo(fullname=t.FullName, kind=self.__kind(t))
+            if t.IsEnum:
+                try:
+                    ti.enum_members = list(t.GetEnumNames())
+                except Exception:
+                    pass
+            else:
+                for m in t.GetMethods(self.__flags):
+                    ti.methods.append(
+                        MethodInfo(
+                            name=m.Name,
+                            static=m.IsStatic,
+                            returns=m.ReturnType.Name,
+                            params=[p.ParameterType.Name for p in m.GetParameters()],
+                        )
+                    )
+            result.append(ti)
+        return result

tentod/decompiler.py

@@ -0,0 +1,59 @@
+"""Decompilation stage."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+
+class IlspyDecompiler:
+    """Wrapper over the ``ilspycmd`` executable."""
+
+    __TOOL_CANDIDATES = ("ilspycmd", "~/.dotnet/tools/ilspycmd")
+
+    def __init__(self, ilspycmd: str | None = None) -> None:
+        self.__exe = ilspycmd or self.__discover()
+
+    def __discover(self) -> str:
+        for cand in self.__TOOL_CANDIDATES:
+            found = shutil.which(cand) or (
+                str(Path(cand).expanduser())
+                if Path(cand).expanduser().exists()
+                else None
+            )
+            if found:
+                return found
+        raise RuntimeError("ilspycmd not found")
+
+    def __env(self) -> dict[str, str]:
+        env = dict(os.environ)
+        env.setdefault("DOTNET_ROLL_FORWARD", "Major")
+        env.setdefault("DOTNET_CLI_TELEMETRY_OPTOUT", "1")
+        env.setdefault("DOTNET_NOLOGO", "1")
+        return env
+
+    def decompile(self, dll_path: str, out_dir: str, force: bool = False) -> Path:
+        dll = Path(dll_path)
+        out = Path(out_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        expected = out / f"{dll.stem}.decompiled.cs"
+        if expected.exists() and not force:
+            return expected
+        proc = subprocess.run(
+            [self.__exe, str(dll), "-o", str(out)],
+            env=self.__env(),
+            capture_output=True,
+            text=True,
+        )
+        if proc.returncode != 0:
+            raise RuntimeError(
+                f"ilspycmd failed ({proc.returncode}):\n{proc.stderr or proc.stdout}"
+            )
+        if expected.exists():
+            return expected
+        produced = sorted(out.glob("*.cs"))
+        if not produced:
+            raise RuntimeError(f"no .cs produced in {out}")
+        return produced[0]

tentod/deobfuscator.py

@@ -0,0 +1,50 @@
+"""Deobfuscation stage."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+
+class StringDeobfuscator:
+    """Rewrites accessor calls to their decrypted literals."""
+
+    def __init__(self, string_banks: dict[str, dict[str, str]]) -> None:
+        self.__banks = string_banks
+
+    @staticmethod
+    def __csharp_literal(value: str) -> str:
+        esc = (
+            value.replace("\\", "\\\\")
+            .replace('"', '\\"')
+            .replace("\n", "\\n")
+            .replace("\r", "\\r")
+            .replace("\t", "\\t")
+        )
+        return f'"{esc}"'
+
+    def __bank_pattern(self, qualifier: str, bank: dict[str, str]) -> re.Pattern:
+        names = "|".join(re.escape(n) for n in sorted(bank, key=len, reverse=True))
+        return re.compile(re.escape(qualifier) + r"\.(" + names + r")\(\)")
+
+    def deobfuscate_text(self, source: str) -> tuple[str, int]:
+        count = 0
+        for qualifier, bank in self.__banks.items():
+            if not bank:
+                continue
+            pattern = self.__bank_pattern(qualifier, bank)
+
+            def repl(m: re.Match) -> str:
+                nonlocal count
+                count += 1
+                return self.__csharp_literal(bank[m.group(1)])
+
+            source = pattern.sub(repl, source)
+        return source, count
+
+    def deobfuscate_file(self, cs_in: str, cs_out: str) -> tuple[Path, int]:
+        rewritten, count = self.deobfuscate_text(Path(cs_in).read_text())
+        out = Path(cs_out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(rewritten)
+        return out, count

tentod/facts.py

@@ -0,0 +1,51 @@
+"""Facts stage."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+import json
+
+from .assembly import DotNetAssembly
+
+
+@dataclass
+class AssemblyFacts:
+    assembly: str
+    strings: dict[str, dict[str, str]] = field(default_factory=dict)
+    enums: dict[str, list[str]] = field(default_factory=dict)
+    routes: list[str] = field(default_factory=list)
+    types: list[dict] = field(default_factory=list)
+
+    def flat_strings(self) -> list[str]:
+        seen: dict[str, None] = {}
+        for bank in self.strings.values():
+            for value in bank.values():
+                seen.setdefault(value, None)
+        return list(seen)
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, ensure_ascii=False)
+
+    @classmethod
+    def from_json(cls, text: str) -> "AssemblyFacts":
+        return cls(**json.loads(text))
+
+
+class FactsExtractor:
+    def extract(self, asm: DotNetAssembly) -> AssemblyFacts:
+        strings = asm.decrypt_strings()
+        routes = sorted(
+            {
+                value
+                for bank in strings.values()
+                for value in bank.values()
+                if value.startswith("/")
+            }
+        )
+        return AssemblyFacts(
+            assembly=asm.full_name,
+            strings=strings,
+            enums=asm.enums(),
+            routes=routes,
+            types=[asdict(t) for t in asm.types()],
+        )

tentod/pipeline.py

@@ -0,0 +1,61 @@
+"""Pipeline orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .assembly import DotNetAssembly
+from .decompiler import IlspyDecompiler
+from .deobfuscator import StringDeobfuscator
+from .facts import AssemblyFacts, FactsExtractor
+from .verify import RecoveryVerifier, VerifyReport
+
+
+@dataclass
+class RecoverResult:
+    csharp: Path
+    deobfuscated: Path
+    facts_path: Path
+    facts: AssemblyFacts
+    replacements: int
+
+
+class DotNetRecoveryPipeline:
+    def __init__(self, dll_path: str, out_root: str) -> None:
+        self.__dll = Path(dll_path)
+        self.__root = Path(out_root) / self.__dll.stem
+
+    @property
+    def root(self) -> Path:
+        return self.__root
+
+    @property
+    def facts_path(self) -> Path:
+        return self.__root / "facts.json"
+
+    def recover(self, force: bool = False) -> RecoverResult:
+        asm = DotNetAssembly.load(str(self.__dll))  # classifies before decompiling
+        banks = asm.decrypt_strings()
+        csharp = IlspyDecompiler().decompile(
+            str(self.__dll),
+            str(self.__root / "csharp"),
+            force=force,
+        )
+        deobf, replacements = StringDeobfuscator(banks).deobfuscate_file(
+            str(csharp),
+            str(self.__root / "deobf" / f"{self.__dll.stem}.deobf.cs"),
+        )
+        facts = FactsExtractor().extract(asm)
+        self.facts_path.write_text(facts.to_json())
+        return RecoverResult(csharp, deobf, self.facts_path, facts, replacements)
+
+    def load_facts(self) -> AssemblyFacts:
+        if self.facts_path.exists():
+            return AssemblyFacts.from_json(self.facts_path.read_text())
+        return FactsExtractor().extract(DotNetAssembly.load(str(self.__dll)))
+
+    def verify(self, python_path: str) -> VerifyReport:
+        facts = self.load_facts()
+        source = Path(python_path).read_text()
+        return RecoveryVerifier().verify(facts, source)

tentod/verify.py

@@ -0,0 +1,45 @@
+"""Verification stage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .facts import AssemblyFacts
+
+
+@dataclass
+class VerifyReport:
+    matched: list[str] = field(default_factory=list)
+    omitted: list[str] = field(default_factory=list)
+    missing_routes: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.missing_routes
+
+    def render(self) -> str:
+        total = len(self.matched) + len(self.omitted)
+        lines = [f"coverage: {len(self.matched)}/{total}"]
+        if self.missing_routes:
+            lines.append("")
+            lines.append(f"missing ({len(self.missing_routes)}):")
+            lines += [f"  ! {r}" for r in self.missing_routes]
+        if self.omitted:
+            lines.append("")
+            lines.append(f"omitted ({len(self.omitted)}):")
+            lines += [f"  - {s!r}" for s in self.omitted]
+        lines.append("")
+        lines.append("OK" if self.ok else "FAIL")
+        return "\n".join(lines)
+
+
+class RecoveryVerifier:
+    def verify(self, facts: AssemblyFacts, python_source: str) -> VerifyReport:
+        report = VerifyReport()
+        for literal in facts.flat_strings():
+            if not literal.strip():
+                continue
+            bucket = report.matched if literal in python_source else report.omitted
+            bucket.append(literal)
+        report.missing_routes = [r for r in facts.routes if r not in python_source]
+        return report

tentod-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: tentod
+Version: 0.1.0
+Summary: tentod
+Home-page: https://github.com/rijulg/tentod
+Author: Rijul Gupta
+Author-email: rijulg@gmail.com
+License: MIT
+Keywords: dotnet
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: class-argparse==0.1.4
+Requires-Dist: pythonnet==3.1.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# tentod
+
+```bash
+python -m tentod recover <assembly.dll>
+python -m tentod guide          # workflow for automated/LLM use
+```

tentod-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+tentod/GUIDE.md,sha256=79-M-TsopO0Nukalfg2NZRQsPETLE4ZicRKUHrhRGSk,2706
+tentod/__init__.py,sha256=DT_m3tcHQluSwE01_2q8ksVcfwCXDcVO4OtrykDXX-w,14
+tentod/__main__.py,sha256=rJ6tc5paiElOsl2UUsAKcUbgEwrGEGglGMN09XvG6W8,2267
+tentod/_runtime.py,sha256=jxmXbZZyvvQ35UM7kPd6ahEz4Qj0qxl-aHxDlR4LE8M,471
+tentod/assembly.py,sha256=CqibMBrYanSDGhNKBi6fuYEg0Dq5SbBzvdmUt1R3kdI,4047
+tentod/decompiler.py,sha256=HvU5gW8zd5NXE6GVS-CaLAUVOqj7EDS9l2Dm-P3ljnU,1866
+tentod/deobfuscator.py,sha256=JTMCwe3WwXkT2YOHih7Jvfrf5P_DgDMvW2028Tv9d2A,1613
+tentod/facts.py,sha256=RN4v7ut3kWDoyjykQe37lGhJqp1l7FGJ4q5eGVGDST0,1439
+tentod/pipeline.py,sha256=Kkg9cx8ZtlRBgvH6NMKyVXAsaHvOkaX2kLHzAXxMDJM,1958
+tentod/verify.py,sha256=FcYNzWNKstZl9To3tGiTKmk2RzFaF43YwyKwD6UddTw,1499
+tentod-0.1.0.dist-info/METADATA,sha256=Edhm3FsPg0DWPyN6XIOfDLSo39Olb62C31Ao9A3y6Vw,951
+tentod-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tentod-0.1.0.dist-info/top_level.txt,sha256=rrntAvE4_6vnipt8jAnAiuSVEkCAfGloWl0diEKK010,7
+tentod-0.1.0.dist-info/RECORD,,

tentod-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tentod-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tentod