unidecompiler-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unidecompiler-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Command-line host for unidecompiler plugins
 Author-email: Wker <1670133844@qq.com>
 License-Expression: AGPL-3.0-or-later
@@ -11,7 +11,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: unidecompiler<0.3.0,>=0.2.2
 Requires-Dist: unidecompiler-export<0.3.0,>=0.2.2
-Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.2
+Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.3
+Requires-Dist: unidecompiler-symbolic<0.3.0,>=0.2.3
 Requires-Dist: unidecompiler-simulation-host-python<0.3.0,>=0.2.2
 
 # unidecompiler-cli
@@ -111,6 +112,23 @@ separate simulator library:
 unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
 ```
 
+Bounded symbolic execution uses the same opaque frontend query and explores
+the recovered generic IR only. `--symbolic` names scalar symbolic parameters;
+all other parameters are supplied through `--concrete`:
+
+```sh
+unidecompiler symbolic sample.pyc --function add \
+  --symbolic '{"left":{"sort":"int"}}' --concrete '{"right":5}'
+```
+
+Use `--format text` for a human-readable summary. Exploration is bounded by
+`--max-paths`, `--max-steps`, `--max-loop-unroll`, `--max-call-depth`, and
+`--solver-timeout-ms`; symbolic sorts are `bool`, `int`, `real`, and `bitvec`
+with a positive `bit_width`. JSON output contains each path's constraints,
+model, return/raise value, and CFG trace. Non-success statuses such as
+`unsupported`, `solver_timeout`, limits, `cancelled`, and `invalid_request`
+are returned explicitly and produce a non-zero exit code.
+
 For trusted programs that require functions outside the lifted module, pass a
 Python environment file. Top-level functions are matched by name, while their
 stdout and stderr are returned as structured simulation events:

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/README.md

@@ -95,6 +95,23 @@ separate simulator library:
 unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
 ```
 
+Bounded symbolic execution uses the same opaque frontend query and explores
+the recovered generic IR only. `--symbolic` names scalar symbolic parameters;
+all other parameters are supplied through `--concrete`:
+
+```sh
+unidecompiler symbolic sample.pyc --function add \
+  --symbolic '{"left":{"sort":"int"}}' --concrete '{"right":5}'
+```
+
+Use `--format text` for a human-readable summary. Exploration is bounded by
+`--max-paths`, `--max-steps`, `--max-loop-unroll`, `--max-call-depth`, and
+`--solver-timeout-ms`; symbolic sorts are `bool`, `int`, `real`, and `bitvec`
+with a positive `bit_width`. JSON output contains each path's constraints,
+model, return/raise value, and CFG trace. Non-success statuses such as
+`unsupported`, `solver_timeout`, limits, `cancelled`, and `invalid_request`
+are returned explicitly and produce a non-zero exit code.
+
 For trusted programs that require functions outside the lifted module, pass a
 Python environment file. Top-level functions are matched by name, while their
 stdout and stderr are returned as structured simulation events:

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unidecompiler-cli"
-version = "0.2.2"
+version = "0.2.3"
 description = "Command-line host for unidecompiler plugins"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -13,7 +13,8 @@ requires-python = ">=3.11"
 dependencies = [
     "unidecompiler>=0.2.2,<0.3.0",
     "unidecompiler-export>=0.2.2,<0.3.0",
-    "unidecompiler-simulator>=0.2.2,<0.3.0",
+    "unidecompiler-simulator>=0.2.3,<0.3.0",
+    "unidecompiler-symbolic>=0.2.3,<0.3.0",
     "unidecompiler-simulation-host-python>=0.2.2,<0.3.0",
 ]
 

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/src/unidecompiler_cli/cli.py

@@ -24,11 +24,15 @@ from unidecompiler.progress import ProgressEvent, ProgressReporter
 
 def main(argv: list[str] | None = None, *, registry: FrontendRegistry | None = None) -> int:
     command_argv = sys.argv[1:] if argv is None else argv
-    if command_argv and command_argv[0] in {"simulate", "template", "export-template"}:
+    if command_argv and command_argv[0] in {"simulate", "symbolic", "template", "export-template"}:
         if command_argv[0] in {"template", "export-template"}:
             from unidecompiler_cli.templates import main as template_main
 
             return template_main(command_argv[1:])
+        if command_argv[0] == "symbolic":
+            from unidecompiler_cli.symbolic import main as symbolic_main
+
+            return symbolic_main(command_argv[1:], registry=registry)
         from unidecompiler_cli.simulation import main as simulate_main
 
         return simulate_main(command_argv[1:], registry=registry)
@@ -40,6 +44,7 @@ def main(argv: list[str] | None = None, *, registry: FrontendRegistry | None = N
             "  template         export a VM frontend or GUI plugin starter project\n"
             "  export-template  alias for template\n"
             "  simulate         run a recovered generic-IR function\n\n"
+            "  symbolic         explore recovered generic-IR paths\n\n"
             "Template examples:\n"
             "  unidecompiler template frontend MyVM -o ./my-vm --author NAME "
             "--description TEXT --requirements TEXT --suffix .vm --version 1\n"

unidecompiler_cli-0.2.3/src/unidecompiler_cli/symbolic.py

@@ -0,0 +1,148 @@
+"""Symbolic execution command hosted by the unidecompiler CLI package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+from typing import Any
+
+import z3
+
+from unidecompiler.plugin_registry import FrontendRegistry
+from unidecompiler_symbolic import (
+    SymbolicEngine,
+    SymbolicInput,
+    SymbolicLimits,
+    SymbolicSort,
+    SymbolicStatus,
+)
+
+
+def main(argv: list[str] | None = None, *, registry: FrontendRegistry | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="unidecompiler symbolic")
+    parser.add_argument("input")
+    parser.add_argument("--function", required=True, help="frontend-owned function query")
+    parser.add_argument("--frontend")
+    parser.add_argument("--symbolic", default="{}", help="JSON object of symbolic input specifications")
+    parser.add_argument("--concrete", default="{}", help="JSON object of concrete parameter values")
+    parser.add_argument("--max-paths", type=int, default=256)
+    parser.add_argument("--max-steps", type=int, default=100_000)
+    parser.add_argument("--max-loop-unroll", type=int, default=32)
+    parser.add_argument("--max-call-depth", type=int, default=32)
+    parser.add_argument("--solver-timeout-ms", type=int, default=5_000)
+    parser.add_argument("--format", choices=("json", "text"), default="json")
+    args = parser.parse_args(argv)
+    try:
+        symbolic_inputs = _symbolic_inputs(args.symbolic)
+        concrete_args = _object(args.concrete, "--concrete")
+        limits = SymbolicLimits(
+            args.max_paths, args.max_steps, args.max_loop_unroll,
+            args.max_call_depth, args.solver_timeout_ms,
+        )
+        limits.validate()
+        engine = SymbolicEngine.from_registry(registry or FrontendRegistry.discover())
+        result = engine.explore_path(
+            Path(args.input), args.function, frontend_id=args.frontend,
+            symbolic_inputs=symbolic_inputs, concrete_args=concrete_args, limits=limits,
+        )
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"invalid symbolic request: {error}", file=sys.stderr)
+        return 2
+    if args.format == "text":
+        print(_text_result(result))
+    else:
+        print(json.dumps(_result_payload(result), ensure_ascii=False, sort_keys=True, allow_nan=False))
+    return _exit_code(result.status)
+
+
+def _object(value: str, option: str) -> dict[str, Any]:
+    parsed = json.loads(value)
+    if not isinstance(parsed, dict) or not all(isinstance(key, str) for key in parsed):
+        raise ValueError(f"{option} must be a JSON object with string keys")
+    return parsed
+
+
+def _symbolic_inputs(value: str) -> tuple[SymbolicInput, ...]:
+    result: list[SymbolicInput] = []
+    for name, spec in _object(value, "--symbolic").items():
+        if not isinstance(spec, dict):
+            raise ValueError("each --symbolic input must be an object")
+        unknown = set(spec) - {"sort", "bit_width"}
+        if unknown:
+            raise ValueError(f"unknown symbolic input fields for {name!r}: {', '.join(sorted(unknown))}")
+        try:
+            sort = SymbolicSort(spec.get("sort", SymbolicSort.INT.value))
+        except ValueError as error:
+            raise ValueError(f"invalid symbolic sort for {name!r}") from error
+        width = spec.get("bit_width")
+        if width is not None and (not isinstance(width, int) or isinstance(width, bool)):
+            raise ValueError(f"bit_width for {name!r} must be an integer")
+        item = SymbolicInput(name, sort, width)
+        item.validate()
+        result.append(item)
+    return tuple(result)
+
+
+def _value(value: Any) -> Any:
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if z3.is_expr(value):
+        return str(value)
+    if isinstance(value, tuple):
+        return [_value(item) for item in value]
+    if isinstance(value, list):
+        return [_value(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _value(item) for key, item in value.items()}
+    return repr(value)
+
+
+def _result_payload(result) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "status": result.status.value,
+        "explored_paths": result.explored_paths,
+        "pruned_paths": result.pruned_paths,
+        "diagnostic": result.diagnostic,
+        "paths": [
+            {
+                "path_id": path.path_id,
+                "status": path.status.value,
+                "constraints": [str(item) for item in path.constraints],
+                "model": None if path.model is None else {key: _value(value) for key, value in path.model.items()},
+                "returns": [_value(value) for value in path.returns],
+                "raised": _value(path.raised),
+                "blocks": list(path.blocks),
+                "edges": list(path.edges),
+                "steps": path.steps,
+                "diagnostic": path.diagnostic,
+            }
+            for path in result.paths
+        ],
+    }
+
+
+def _text_result(result) -> str:
+    lines = [
+        f"{result.status.value}: {result.explored_paths} explored, {result.pruned_paths} pruned",
+    ]
+    if result.diagnostic:
+        lines.append(result.diagnostic)
+    for path in result.paths:
+        outcome = path.diagnostic or repr(path.raised if path.raised is not None else path.returns)
+        lines.append(f"[{path.path_id}] {path.status.value}; {path.steps} steps; {outcome}")
+        if path.constraints:
+            lines.append("  constraints: " + "; ".join(str(item) for item in path.constraints))
+        if path.model:
+            lines.append("  model: " + json.dumps({key: _value(value) for key, value in path.model.items()}, sort_keys=True))
+    return "\n".join(lines)
+
+
+def _exit_code(status: SymbolicStatus) -> int:
+    if status is SymbolicStatus.COMPLETED:
+        return 0
+    if status is SymbolicStatus.INVALID_REQUEST:
+        return 2
+    return 1

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/src/unidecompiler_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unidecompiler-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Command-line host for unidecompiler plugins
 Author-email: Wker <1670133844@qq.com>
 License-Expression: AGPL-3.0-or-later
@@ -11,7 +11,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: unidecompiler<0.3.0,>=0.2.2
 Requires-Dist: unidecompiler-export<0.3.0,>=0.2.2
-Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.2
+Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.3
+Requires-Dist: unidecompiler-symbolic<0.3.0,>=0.2.3
 Requires-Dist: unidecompiler-simulation-host-python<0.3.0,>=0.2.2
 
 # unidecompiler-cli
@@ -111,6 +112,23 @@ separate simulator library:
 unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
 ```
 
+Bounded symbolic execution uses the same opaque frontend query and explores
+the recovered generic IR only. `--symbolic` names scalar symbolic parameters;
+all other parameters are supplied through `--concrete`:
+
+```sh
+unidecompiler symbolic sample.pyc --function add \
+  --symbolic '{"left":{"sort":"int"}}' --concrete '{"right":5}'
+```
+
+Use `--format text` for a human-readable summary. Exploration is bounded by
+`--max-paths`, `--max-steps`, `--max-loop-unroll`, `--max-call-depth`, and
+`--solver-timeout-ms`; symbolic sorts are `bool`, `int`, `real`, and `bitvec`
+with a positive `bit_width`. JSON output contains each path's constraints,
+model, return/raise value, and CFG trace. Non-success statuses such as
+`unsupported`, `solver_timeout`, limits, `cancelled`, and `invalid_request`
+are returned explicitly and produce a non-zero exit code.
+
 For trusted programs that require functions outside the lifted module, pass a
 Python environment file. Top-level functions are matched by name, while their
 stdout and stderr are returned as structured simulation events:

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/src/unidecompiler_cli.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ src/unidecompiler_cli/__init__.py
 src/unidecompiler_cli/cli.py
 src/unidecompiler_cli/input_sources.py
 src/unidecompiler_cli/simulation.py
+src/unidecompiler_cli/symbolic.py
 src/unidecompiler_cli/templates.py
 src/unidecompiler_cli.egg-info/PKG-INFO
 src/unidecompiler_cli.egg-info/SOURCES.txt

{unidecompiler_cli-0.2.2 → unidecompiler_cli-0.2.3}/src/unidecompiler_cli.egg-info/requires.txt

@@ -1,4 +1,5 @@
 unidecompiler<0.3.0,>=0.2.2
 unidecompiler-export<0.3.0,>=0.2.2
-unidecompiler-simulator<0.3.0,>=0.2.2
+unidecompiler-simulator<0.3.0,>=0.2.3
+unidecompiler-symbolic<0.3.0,>=0.2.3
 unidecompiler-simulation-host-python<0.3.0,>=0.2.2