feat(cli): add --seed, --diff, --strict, -v/-q flags

Author: owanesh

.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 dist/
 build/
 .eggs/
+meta/*

cli/README.md

@@ -25,25 +25,11 @@ swamped obfuscate input.wasm -o output.wasm -s nop_insertion shift_transformatio
 # Apply all strategies at once
 swamped obfuscate input.wasm -o output.wasm -s all
 
-# Only structural or only code-level
-swamped obfuscate input.wasm -o output.wasm -s structural
-swamped obfuscate input.wasm -o output.wasm -s code
+# Abort on first failure (useful in CI)
+swamped obfuscate input.wasm -o output.wasm -s all --strict
 
-# Exclude specific strategies with -e
-swamped obfuscate input.wasm -o output.wasm -s all -e data_encryption direct_to_indirect
-swamped obfuscate input.wasm -o output.wasm -s code -e nop_insertion
-
-# Control intensity (0.0 = none, 1.0 = max)
-swamped obfuscate input.wasm -o output.wasm -s all --ratio 0.3
-
-# Validate the output after obfuscation
-swamped obfuscate input.wasm -o output.wasm -s nop_insertion --validate
-
-# Stack operation insertion: all 6 variants (default)
-swamped obfuscate input.wasm -o output.wasm -s stack_op_insertion
-
-# Stack operation insertion: only specific variants
-swamped obfuscate input.wasm -o output.wasm -s stack_op_insertion --stackop m b f
+# Combine seed + diff for reproducible experiments
+swamped obfuscate input.wasm -o output.wasm -s all --seed 42 --diff -t
 ```
 
 Accepts both `.wasm` and `.wast` as input/output — conversion is automatic.
@@ -109,6 +95,11 @@ Example: `swamped obfuscate input.wasm -o out.wasm -s stack_op_insertion --stack
 | `--alpha`    | `1.0`   | Beta-distribution alpha (target selection bias)              |
 | `--beta`     | `1.0`   | Beta-distribution beta (target selection bias)               |
 | `--validate` | off     | Run `wasm-validate` on the output                            |
+| `--seed`     | —       | RNG seed for reproducible runs (see below)                   |
+| `--diff`     | off     | Print a before/after summary of sections and instructions    |
+| `--strict`   | off     | Abort immediately on the first strategy failure              |
+| `-v`         | off     | Verbose (debug-level) logging                                |
+| `-q`         | off     | Quiet mode — only print errors                               |
 
 ## Parameters
 
@@ -127,6 +118,19 @@ Defaults (`alpha=1, beta=1, ratio=1`) match the original project.
 
 If you just want to control how much gets changed, `--ratio` is enough. Use `--alpha`/`--beta` when you need finer control over the spatial distribution of perturbations.
 
+**`--seed`** enables **reproducible runs**. Given the same input file, seed, and parameters, SWAMPED will produce the exact same output. This is useful for:
+
+- **Research** — reproduce an experiment exactly and report the seed alongside results
+- **Debugging** — if a run produces an invalid module, re-run with the same seed to investigate
+- **Comparison** — test different strategy sets against the same input with identical perturbation distributions
+
+```bash
+swamped obfuscate input.wasm -o out.wasm -s all --seed 42
+swamped obfuscate input.wasm -o out.wasm -s all --seed 42   # same output
+```
+
+Without `--seed`, every run uses a fresh unseeded RNG (non-deterministic).
+
 ## Preliminary tests
 
 **Setup:** the `function_insertion` strategy requires a symlink `strategies/data/function_body.pkl` pointing to one of the precomputed pool files. Create it before running obfuscation:

cli/swamped_cli.py

@@ -8,6 +8,7 @@
 
 import argparse
 import copy
+import logging
 import os
 import subprocess
 import sys
@@ -22,6 +23,9 @@
 from wasmParser import parser
 from strategies import structural_perturbation as sp
 from strategies import code_perturbation as cp
+from strategies import state as strategy_state
+
+logger = logging.getLogger("swamped")
 
 # ── Stack Operation Insertion sub-variants ────────────────────────────────
 
@@ -94,15 +98,15 @@ def wasm_to_wast(wasm_path, wast_path):
         capture_output=True, text=True,
     )
     if result.returncode != 0:
-        print(f"[error] wasm2wat failed: {result.stderr.strip()}", file=sys.stderr)
+        logger.error("wasm2wat failed: %s", result.stderr.strip())
         sys.exit(1)
 
 
 def resolve_input(input_path, tmp_dir):
     """Return the path to a .wast file, converting from .wasm if necessary."""
     if input_path.endswith(".wasm"):
         wast_path = os.path.join(tmp_dir, os.path.basename(input_path).replace(".wasm", ".wast"))
-        print(f"[*] Converting {input_path} -> WAT ...")
+        logger.info("[*] Converting %s -> WAT ...", input_path)
         wasm_to_wast(input_path, wast_path)
         return wast_path
     return input_path
@@ -127,6 +131,39 @@ def list_strategies():
     print()
 
 
+def _count_body_instructions(parsed):
+    """Count total body instructions across all functions."""
+    total = 0
+    for f in parsed.get("Function", {}).values():
+        if f.body:
+            total += len(f.body)
+    return total
+
+
+def _section_counts(parsed):
+    """Return a dict of section_name -> entry count."""
+    return {sec: len(entries) for sec, entries in parsed.items()}
+
+
+def _print_diff(before_counts, before_instructions, after_counts, after_instructions):
+    """Print a summary of what changed."""
+    print("\n  Diff summary:\n")
+    print(f"    {'Section':<20s} {'Before':>8s} {'After':>8s} {'Delta':>8s}")
+    print(f"    {'─' * 20} {'─' * 8} {'─' * 8} {'─' * 8}")
+    for sec in before_counts:
+        b = before_counts[sec]
+        a = after_counts.get(sec, 0)
+        delta = a - b
+        marker = f"+{delta}" if delta > 0 else str(delta) if delta < 0 else "0"
+        if delta != 0:
+            print(f"    {sec:<20s} {b:>8d} {a:>8d} {marker:>8s}")
+    instr_delta = after_instructions - before_instructions
+    marker = f"+{instr_delta}" if instr_delta > 0 else str(instr_delta) if instr_delta < 0 else "0"
+    if instr_delta != 0:
+        print(f"    {'instructions':<20s} {before_instructions:>8d} {after_instructions:>8d} {marker:>8s}")
+    print()
+
+
 # ── CLI entry point ───────────────────────────────────────────────────────
 
 def build_parser():
@@ -150,6 +187,7 @@ def build_parser():
               swamped obfuscate input.wasm -o out.wasm -s code -e direct_to_indirect
               swamped obfuscate input.wasm -o out.wasm -s structural --alpha 2 --beta 5
               swamped obfuscate input.wasm -o out.wasm -s stack_op_insertion --stackop m b
+              swamped obfuscate input.wasm -o out.wasm -s all --seed 42 --diff
         """),
     )
     sub = p.add_subparsers(dest="command", required=True)
@@ -207,6 +245,11 @@ def build_parser():
     obf.add_argument("--ratio", type=float, default=1.0, help="Perturbation ratio 0.0-1.0 (default: 1.0)")
     obf.add_argument("--validate", action="store_true", help="Run wasm-validate on the output")
     obf.add_argument("-t", "--timing", action="store_true", help="Show execution time for each strategy")
+    obf.add_argument("--seed", type=int, default=None, help="RNG seed for reproducible runs")
+    obf.add_argument("--diff", action="store_true", help="Show a summary of sections/instructions changed")
+    obf.add_argument("--strict", action="store_true", help="Abort on the first strategy failure")
+    obf.add_argument("-v", "--verbose", action="store_true", help="Enable debug-level logging")
+    obf.add_argument("-q", "--quiet", action="store_true", help="Suppress all output except errors")
 
     return p
 
@@ -224,14 +267,14 @@ def resolve_strategy_names(requested, excluded):
         elif r in STRATEGIES:
             names.append(r)
         else:
-            print(f"[error] Unknown strategy: '{r}'", file=sys.stderr)
-            print(f"        Run 'swamped list' to see available strategies.", file=sys.stderr)
+            logger.error("Unknown strategy: '%s'", r)
+            logger.error("Run 'swamped list' to see available strategies.")
             sys.exit(1)
 
     # Validate exclusions
     for e in excluded:
         if e not in STRATEGIES:
-            print(f"[error] Unknown strategy to exclude: '{e}'", file=sys.stderr)
+            logger.error("Unknown strategy to exclude: '%s'", e)
             sys.exit(1)
     exclude_set = set(excluded)
 
@@ -244,19 +287,19 @@ def resolve_strategy_names(requested, excluded):
             unique.append(n)
 
     if not unique:
-        print("[error] No strategies left after exclusions.", file=sys.stderr)
+        logger.error("No strategies left after exclusions.")
         sys.exit(1)
 
     # Skip not-yet-implemented strategies with a warning
     final = []
     for n in unique:
         if STRATEGIES[n]["fn"] is None:
-            print(f"[warning] {n} is not yet implemented, skipping.", file=sys.stderr)
+            logger.warning("%s is not yet implemented, skipping.", n)
         else:
             final.append(n)
 
     if not final:
-        print("[error] No implemented strategies left.", file=sys.stderr)
+        logger.error("No implemented strategies left.")
         sys.exit(1)
 
     return final
@@ -267,30 +310,41 @@ def cmd_obfuscate(args):
     output_path = os.path.abspath(args.output)
 
     if not os.path.isfile(input_path):
-        print(f"[error] Input file not found: {input_path}", file=sys.stderr)
+        logger.error("Input file not found: %s", input_path)
         sys.exit(1)
 
     output_dir = os.path.dirname(output_path)
     os.makedirs(output_dir, exist_ok=True)
 
+    # Seed RNG if requested
+    if args.seed is not None:
+        strategy_state.set_seed(args.seed)
+        logger.info("[*] RNG seed set to %d", args.seed)
+
     # Convert .wasm to .wast if needed
     wast_path = resolve_input(input_path, output_dir)
 
     # Parse
-    print(f"[*] Parsing {wast_path} ...")
+    logger.info("[*] Parsing %s ...", wast_path)
     with open(wast_path) as f:
         origin_wast = f.readlines()
     parsed = parser.parseWast(origin_wast)
 
+    # Snapshot before-counts for --diff
+    if args.diff:
+        before_counts = _section_counts(parsed)
+        before_instructions = _count_body_instructions(parsed)
+
     # Apply strategies sequentially
     strategy_names = resolve_strategy_names(args.strategies, args.exclude)
     section = copy.deepcopy(parsed)
 
-    print(f"[*] Applying {len(strategy_names)} perturbation(s) (alpha={args.alpha}, beta={args.beta}, ratio={args.ratio}):\n")
+    logger.info("[*] Applying %d perturbation(s) (alpha=%s, beta=%s, ratio=%s):\n",
+                len(strategy_names), args.alpha, args.beta, args.ratio)
     timings = []
     for name in strategy_names:
         entry = STRATEGIES[name]
-        print(f"    -> {name}", end="", flush=True)
+        logger.info("    -> %s", name)
         t0 = time.monotonic()
         try:
             if name == "stack_op_insertion":
@@ -300,58 +354,83 @@ def cmd_obfuscate(args):
             elapsed = time.monotonic() - t0
             timings.append((name, elapsed, True))
             if args.timing:
-                print(f"  ({elapsed:.2f}s)")
-            else:
-                print()
+                logger.info("       (%0.2fs)", elapsed)
         except Exception as e:
             elapsed = time.monotonic() - t0
             timings.append((name, elapsed, False))
-            print()
-            print(f"       [warning] {name} failed: {e}", file=sys.stderr)
+            if args.strict:
+                logger.error("    [error] %s failed: %s", name, e)
+                sys.exit(1)
+            else:
+                logger.warning("    [warning] %s failed: %s", name, e)
 
     if args.timing and len(timings) > 1:
         total = sum(t for _, t, _ in timings)
         slowest = max(timings, key=lambda x: x[1])
-        print(f"\n    total: {total:.2f}s | slowest: {slowest[0]} ({slowest[1]:.2f}s)")
+        logger.info("\n    total: %.2fs | slowest: %s (%.2fs)", total, slowest[0], slowest[1])
+
+    # --diff summary
+    if args.diff:
+        after_counts = _section_counts(section)
+        after_instructions = _count_body_instructions(section)
+        _print_diff(before_counts, before_instructions, after_counts, after_instructions)
 
     # Save output
     output_name = os.path.basename(output_path)
     if output_path.endswith(".wasm"):
         # savePertWasm writes .wast and converts to .wasm
         wast_out = output_path.replace(".wasm", ".wast")
-        print(f"\n[*] Writing {wast_out} ...")
+        logger.info("[*] Writing %s ...", wast_out)
         parser.savePertWasm(output_dir + "/", os.path.basename(wast_out), section)
         if os.path.isfile(output_path):
-            print(f"[+] Done! Output: {output_path}")
+            logger.info("[+] Done! Output: %s", output_path)
         else:
-            print(f"[!] WAT written but wat2wasm conversion may have failed.", file=sys.stderr)
-            print(f"    WAT output: {wast_out}", file=sys.stderr)
+            logger.error("[!] WAT written but wat2wasm conversion may have failed.")
+            logger.error("    WAT output: %s", wast_out)
             sys.exit(1)
     else:
         # .wast output
-        print(f"\n[*] Writing {output_path} ...")
+        logger.info("[*] Writing %s ...", output_path)
         parser.savePertWasm(output_dir + "/", output_name, section)
-        print(f"[+] Done! Output: {output_path}")
+        logger.info("[+] Done! Output: %s", output_path)
 
     # Validate
     if args.validate:
         wasm_file = output_path if output_path.endswith(".wasm") else output_path.replace(".wast", ".wasm")
         if not os.path.isfile(wasm_file):
-            print(f"[!] No .wasm file to validate.", file=sys.stderr)
+            logger.error("[!] No .wasm file to validate.")
             sys.exit(1)
-        print(f"[*] Validating {wasm_file} ...")
+        logger.info("[*] Validating %s ...", wasm_file)
         result = subprocess.run(["wasm-validate", wasm_file], capture_output=True, text=True)
         if result.returncode == 0:
-            print(f"[+] Validation passed.")
+            logger.info("[+] Validation passed.")
         else:
-            print(f"[!] Validation failed: {result.stderr.strip()}", file=sys.stderr)
+            logger.error("[!] Validation failed: %s", result.stderr.strip())
             sys.exit(1)
 
 
+def _setup_logging(verbose=False, quiet=False):
+    """Configure logging. Default output matches the original print() behaviour."""
+    if quiet:
+        level = logging.ERROR
+    elif verbose:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(level)
+
+
 def main():
     p = build_parser()
     args = p.parse_args()
 
+    # Logging setup — only relevant for obfuscate (list always uses print)
+    if args.command == "obfuscate":
+        _setup_logging(verbose=args.verbose, quiet=args.quiet)
+
     if args.command == "list":
         list_strategies()
     elif args.command == "obfuscate":

strategies/data/function_body.pkl

@@ -0,0 +1 @@
+function_body_tmp10000.pkl