cryptoexp 0.1.0a1__py3-none-any.whl

cryptoexp/__init__.py

@@ -0,0 +1,397 @@
+"""cryptoexp — dependency-free crypto toolkit for CTF, security work and research
+
+Three usage tiers, in order of how much hidden state they involve:
+
+1) The recommended way (no namespace surprises):
+       import cryptoexp as cx
+       cx.algebra.gcd(a, b)
+       cx.long_to_bytes(0x4142)
+       cx.rsa_ops.wiener_attack(e, n)
+       cx.crc_forge_append(prefix, target, 32, 0x04C11DB7)
+
+2) Namespaced imports when a script wants shorter lines:
+       from cryptoexp import algebra, encoding, forensics
+       algebra.gcd(a, b)
+
+3) `from cryptoexp import *` is meant for **throwaway solve scripts**, and it only
+   brings names that are unmistakably ours (attack and helper names such as
+   `wiener_attack`, `audit_rsa_key`, `crc_forge_append`). One-word primitives that
+   user code, `math`, `hashlib` or pycryptodome also define (`gcd`, `sha256`, `AES`,
+   `xor`, ...) are deliberately **not** star-exported - they would silently shadow the
+   caller's own names. They remain available as `cx.gcd` or `from cryptoexp import gcd`.
+
+As a tool:
+       python3 cryptoexp_cli.py analyze challenge.txt --solve
+
+Zero dependencies: the core uses only the standard library (AES/LLL/Coppersmith/MT19937
+are all implemented here); optional extras (gmpy2/sympy/pycryptodome/z3) are auto-detected,
+and missing ones never affect correctness.
+
+Naming convention: attack functions return a unified structure
+    {"ok", "plaintext", "detail", "factors", "d", "note"}
+
+Authors: coolmoon & guaidao2 (MIT)
+"""
+
+from .utils import algebra, encoding, lattice, pad, prng, rsa_ops, aes, gf, dlp
+from .utils.algebra import (
+    egcd, gcd, lcm, modinv, crt, isqrt, iroot, exact_root, perfect_square,
+    is_prime, next_prime, prime_sieve, pollard_rho, factor, factor_limited,
+    divisors, continued_fraction, convergents, wiener_recover_d, fermat_factor,
+    close_factor_probe, bsgs, tonelli_shanks, lcg_recover,
+)
+from .utils.encoding import (
+    score_text, printable_ratio, confidence_of, flag_candidates,
+    loose_flag_candidates, find_flags, build_flag_pattern, set_flag_prefixes,
+    get_flag_prefixes, reset_flag_prefixes, DEFAULT_FLAG_PREFIXES,
+    decode_chain, guess_kinds, single_byte_xor, repeating_key_xor,
+    caesar, rot13, affine_decrypt, morse_decode, morse_encode,
+    vigenere_recover, fence_decrypt, index_of_coincidence,
+    to_hex, to_base64, to_base32, to_base58,
+    enhex, unhex, b64e, b64d, b32e, b32d, b58e, b58d,
+)
+from .utils.pad import (
+    pkcs7_pad, pkcs7_unpad, pkcs7_valid, zero_pad, zero_unpad, xor, xor_repeat,
+    blocks, bitflip_cbc, BLOCK,
+)
+from .utils.lattice import (
+    lll, poly_trim, poly_mul, poly_pow, poly_eval, coppersmith_univariate,
+    known_high_bits_factor, subset_sum_lll,
+)
+from .utils.rsa_ops import (
+    itob, btoi, long_to_bytes, bytes_to_long, keygen, encrypt as rsa_encrypt,
+    decrypt as rsa_decrypt, crt_decrypt, reencrypt_check, factor_from_phi,
+    factor_from_d, decrypt_with_factors, small_e_attack, broadcast_attack,
+    common_modulus_attack, shared_prime_attack, wiener_attack, fermat_attack,
+    pollard_attack, dp_leak_attack, phi_leak_attack, known_high_bits_attack,
+    auto_attack,
+)
+from .utils.prng import (
+    MT19937, untemper, clone_from_outputs, predict_next, clone_python_random,
+    crack_seed,
+)
+from . import oracle
+from .oracle import (
+    detect_block_size, detect_mode, find_prefix_len, ecb_byte_at_a_time,
+    padding_oracle_attack, make_ecb_oracle, make_cbc_oracle, make_padding_oracle,
+)
+from .utils.gf import (
+    mat_rref, solve_linear, nullspace, mat_mul, mat_inv, solve_lcg_params,
+    recover_linear_map,
+)
+from .utils.dlp import discrete_log, pohlig_hellman, dlog_feasibility
+from .utils.lattice import mitm_subset_sum
+from .utils import modular, polytools, gf2, hashes, stream, rsa_attacks, keys, prng_extra
+from .utils import signatures, symtools, classic_extra
+from .utils.modular import (
+    legendre_symbol, jacobi_symbol, kronecker_symbol, is_quadratic_residue,
+    sqrt_mod, totient, carmichael, mobius, is_squarefree, sum_of_divisors,
+    divisor_count, order_mod, primitive_root, is_primitive_root, crt_general,
+    crt_list, gcd_list, lcm_list, pollard_pm1, williams_pp1, is_smooth,
+    smooth_part, integer_log, binomial_mod,
+)
+from .utils.polytools import (
+    poly_divmod, poly_mod, poly_gcd, poly_derivative, poly_roots_mod_p,
+    poly_from_roots, poly_compose, poly_powmod, poly_eval_mod,
+    poly_is_irreducible, poly_resultant, gf2_poly_mul, gf2_poly_mod,
+    gf2_poly_gcd, gf2_poly_roots,
+)
+from .utils.gf2 import (
+    gf2_rref, gf2_rank, gf2_solve, gf2_nullspace, gf2_inv, LFSR,
+    lfsr_from_bits, lfsr_recover, lfsr_next, berlekamp_massey, CRC,
+    crc_compute, crc_known, crc_reverse_params, crc_forge_append,
+    crc_solve_unknown, bits_to_int, int_to_bits, bytes_to_bits, bits_to_bytes,
+)
+from .utils.hashes import (
+    sha1, sha256, sha1_hex, sha256_hex, md5, md5_hex, sha1_state, sha256_state,
+    md5_state, HashState, length_extension, hmac_sha256,
+)
+from .utils.stream import (
+    rc4, rc4_keystream, ChaCha20, chacha20, chacha20_block, aes_ctr,
+    aes_ctr_keystream, crib_drag, keystream_xor, fixed_nonce_reuse_recover,
+)
+from .utils.rsa_attacks import (
+    franklin_reiter, hastad_padded, stereotyped_message, parity_oracle_attack,
+    lsb_oracle_attack, rsa_recover_d_from_factors, bleichenbacher_note,
+)
+from .utils.keys import (
+    parse_pem, parse_der_rsa_public, parse_der_rsa_private, parse_ssh_public_key,
+    parse_openssh_private, rsa_public_der, key_fingerprint_sha256, pem_wrap,
+)
+from .utils.prng_extra import (
+    java_random_next, java_random_ints, java_random_recover, java_random_predict,
+    glibc_rand_values, glibc_rand_recover, glibc_rand_predict,
+    xorshift32_next, xorshift32_stream, xorshift_recover, xorshift_predict,
+    lcg_recover_truncated,
+)
+from .utils.classic_extra import (
+    atbash, rot47, rot_n, bacon_encode, bacon_decode, playfair_encrypt,
+    playfair_decrypt, hill_encrypt, hill_decrypt, columnar_encrypt,
+    columnar_decrypt, rail_fence_encrypt, rail_fence_decrypt, autokey_encrypt,
+    autokey_decrypt, substitution_decrypt, to_base62, from_base62, to_base91,
+    from_base91, url_encode, url_decode, html_entity_decode, detect_classic,
+)
+from .utils.signatures import (
+    hash_to_int, ecdsa_nonce_reuse, dsa_nonce_reuse, ecdsa_recover_k,
+    ecdsa_verify, ecdsa_sign, dsa_sign, rsa_e3_signature_forge, pkcs1_v15_pad,
+    pkcs1_v15_unpad,
+)
+from .utils.symtools import (
+    ecb_repeated_blocks, is_ecb, infer_block_size, block_index,
+    cbc_flip_plaintext, cbc_decrypt_blocks, strip_pkcs7, pad_pkcs7,
+)
+from .utils.forensics import (
+    batch_gcd, common_factor_pairs, parse_der_signature, parse_jwt,
+    audit_rsa_key, detect_weak_prng,
+)
+from . import hypothesis
+from .hypothesis import (
+    evaluate as evaluate_hypotheses, list_hypotheses, register_hypothesis,
+    params_from_ctx,
+)
+from . import lab
+from .lab import build_workbench, write_workbench
+from .core.context import build_context
+from .core.analysis import (
+    analyze_all, register_analyzer, list_analyzers, probe_optional_deps,
+)
+from .core.verify import verify_candidates
+from .core.solve import (
+    register_solver, list_solvers, generate as solve_script,
+)
+
+__version__ = "0.1.0a1"
+__author__ = "coolmoon & guaidao2"
+__license__ = "MIT"
+
+_CANDIDATE_EXPORTS = [
+    # submodules (for finer-grained entry points use cryptoexp.rsa_ops.xxx)
+    "algebra", "encoding", "lattice", "pad", "prng", "rsa_ops", "aes", "oracle",
+    "gf", "dlp", "hypothesis", "lab", "modular", "polytools", "gf2", "hashes",
+    "stream", "rsa_attacks", "keys", "prng_extra", "signatures", "symtools",
+    # hypothesis engine / workbench
+    "evaluate_hypotheses", "list_hypotheses", "register_hypothesis",
+    "params_from_ctx", "build_workbench", "write_workbench",
+    # number theory
+    "egcd", "gcd", "lcm", "modinv", "crt", "isqrt", "iroot", "exact_root",
+    "perfect_square", "is_prime", "next_prime", "prime_sieve", "pollard_rho",
+    "factor", "factor_limited", "divisors", "continued_fraction", "convergents",
+    "wiener_recover_d", "fermat_factor", "close_factor_probe", "bsgs",
+    "tonelli_shanks", "lcg_recover",
+    # encoding / classical
+    "score_text", "printable_ratio", "confidence_of", "flag_candidates",
+    "loose_flag_candidates", "find_flags", "build_flag_pattern",
+    "set_flag_prefixes", "get_flag_prefixes", "reset_flag_prefixes",
+    "DEFAULT_FLAG_PREFIXES",
+    "decode_chain", "guess_kinds", "single_byte_xor", "repeating_key_xor",
+    "caesar", "rot13", "affine_decrypt", "morse_decode", "morse_encode",
+    "vigenere_recover", "fence_decrypt", "index_of_coincidence",
+    "to_hex", "to_base64", "to_base32", "to_base58",
+    "enhex", "unhex", "b64e", "b64d", "b32e", "b32d", "b58e", "b58d",
+    # bytes / padding
+    "pkcs7_pad", "pkcs7_unpad", "pkcs7_valid", "zero_pad", "zero_unpad",
+    "xor", "xor_repeat", "blocks", "bitflip_cbc", "BLOCK",
+    # lattice
+    "lll", "poly_trim", "poly_mul", "poly_pow", "poly_eval",
+    "coppersmith_univariate", "known_high_bits_factor", "subset_sum_lll",
+    "mitm_subset_sum",
+    # GF(p) linear algebra / discrete log
+    "mat_rref", "solve_linear", "nullspace", "mat_mul", "mat_inv",
+    "solve_lcg_params", "recover_linear_map", "discrete_log", "pohlig_hellman",
+    "dlog_feasibility",
+    # RSA
+    "itob", "btoi", "long_to_bytes", "bytes_to_long", "keygen", "rsa_encrypt",
+    "rsa_decrypt", "crt_decrypt", "reencrypt_check", "factor_from_phi",
+    "factor_from_d", "decrypt_with_factors", "small_e_attack",
+    "broadcast_attack", "common_modulus_attack", "shared_prime_attack",
+    "wiener_attack", "fermat_attack", "pollard_attack", "dp_leak_attack",
+    "phi_leak_attack", "known_high_bits_attack", "auto_attack",
+    # PRNG
+    "MT19937", "untemper", "clone_from_outputs", "predict_next",
+    "clone_python_random", "crack_seed",
+    # oracle
+    "detect_block_size", "detect_mode", "find_prefix_len",
+    "ecb_byte_at_a_time", "padding_oracle_attack", "make_ecb_oracle",
+    "make_cbc_oracle", "make_padding_oracle",
+    # analysis / generation / verification
+    "build_context", "analyze_all", "verify_candidates", "solve_script",
+    "register_analyzer", "register_solver", "list_analyzers", "list_solvers",
+    "probe_optional_deps",
+    # modular extras
+    "legendre_symbol", "jacobi_symbol", "kronecker_symbol", "is_quadratic_residue",
+    "sqrt_mod", "totient", "carmichael", "mobius", "is_squarefree",
+    "sum_of_divisors", "divisor_count", "order_mod", "primitive_root",
+    "is_primitive_root", "crt_general", "crt_list", "gcd_list", "lcm_list",
+    "pollard_pm1", "williams_pp1", "is_smooth", "smooth_part", "integer_log",
+    "binomial_mod",
+    # polynomials
+    "poly_divmod", "poly_mod", "poly_gcd", "poly_derivative", "poly_roots_mod_p",
+    "poly_from_roots", "poly_compose", "poly_powmod", "poly_eval_mod",
+    "poly_is_irreducible", "poly_resultant", "gf2_poly_mul", "gf2_poly_mod",
+    "gf2_poly_gcd", "gf2_poly_roots",
+    # GF(2) / LFSR / CRC / bits
+    "gf2_rref", "gf2_rank", "gf2_solve", "gf2_nullspace", "gf2_inv", "LFSR",
+    "lfsr_from_bits", "lfsr_recover", "lfsr_next", "berlekamp_massey", "CRC",
+    "crc_compute", "crc_known", "crc_reverse_params", "crc_forge_append",
+    "crc_solve_unknown", "bits_to_int", "int_to_bits", "bytes_to_bits", "bits_to_bytes",
+    # hashes
+    "sha1", "sha256", "sha1_hex", "sha256_hex", "md5", "md5_hex", "sha1_state",
+    "sha256_state", "md5_state", "HashState", "length_extension", "hmac_sha256",
+    # stream ciphers
+    "rc4", "rc4_keystream", "ChaCha20", "chacha20", "chacha20_block", "aes_ctr",
+    "aes_ctr_keystream", "crib_drag", "keystream_xor", "fixed_nonce_reuse_recover",
+    # symmetric helpers
+    "ecb_repeated_blocks", "is_ecb", "infer_block_size", "block_index",
+    "cbc_flip_plaintext", "cbc_decrypt_blocks", "strip_pkcs7", "pad_pkcs7",
+    # real-world forensics (beyond CTF)
+    "batch_gcd", "common_factor_pairs", "parse_der_signature", "parse_jwt",
+    "audit_rsa_key", "detect_weak_prng",
+    # RSA attacks (extra) / keys
+    "franklin_reiter", "hastad_padded", "stereotyped_message",
+    "parity_oracle_attack", "lsb_oracle_attack", "rsa_recover_d_from_factors",
+    "bleichenbacher_note", "parse_pem", "parse_der_rsa_public",
+    "parse_der_rsa_private", "parse_ssh_public_key", "parse_openssh_private",
+    "rsa_public_der", "key_fingerprint_sha256", "pem_wrap",
+    # signatures
+    "hash_to_int", "ecdsa_nonce_reuse", "dsa_nonce_reuse", "ecdsa_recover_k",
+    "ecdsa_verify", "ecdsa_sign", "dsa_sign", "rsa_e3_signature_forge",
+    "pkcs1_v15_pad", "pkcs1_v15_unpad",
+    # PRNG (extra)
+    "java_random_next", "java_random_ints", "java_random_recover",
+    "java_random_predict", "glibc_rand_values", "glibc_rand_recover",
+    "glibc_rand_predict", "xorshift32_next", "xorshift32_stream",
+    "xorshift_recover", "xorshift_predict", "lcg_recover_truncated",
+    # classic ciphers (extra)
+    "atbash", "rot47", "rot_n", "bacon_encode", "bacon_decode",
+    "playfair_encrypt", "playfair_decrypt", "hill_encrypt", "hill_decrypt",
+    "columnar_encrypt", "columnar_decrypt", "rail_fence_encrypt",
+    "rail_fence_decrypt", "autokey_encrypt", "autokey_decrypt",
+    "substitution_decrypt", "to_base62", "from_base62", "to_base91",
+    "from_base91", "url_encode", "url_decode", "html_entity_decode",
+    "detect_classic",
+]
+
+# ── What a star import brings, and what it deliberately does not ──────────────
+# `from cryptoexp import *` must not shadow the caller's own names. These are the
+# one-word primitives that user code, `math`, `hashlib` and pycryptodome also define;
+# a star import that grabbed `gcd` or `AES` would silently break the calling module.
+# They stay *fully available* - as attributes (`cx.gcd`) and by explicit import
+# (`from cryptoexp import gcd`) - they are just not pushed into the caller's
+# namespace behind their back.
+_COLLISION_PRONE = {
+    "gcd", "egcd", "lcm", "modinv", "crt", "isqrt", "iroot", "exact_root",
+    "perfect_square", "is_prime", "next_prime", "prime_sieve", "pollard_rho",
+    "factor", "factor_limited", "divisors", "totient", "carmichael", "mobius",
+    "is_squarefree", "sum_of_divisors", "divisor_count", "order_mod",
+    "primitive_root", "is_primitive_root", "is_smooth", "smooth_part",
+    "integer_log", "binomial_mod", "legendre_symbol", "jacobi_symbol",
+    "kronecker_symbol", "sqrt_mod", "is_quadratic_residue",
+    "xor", "blocks", "BLOCK", "itob", "btoi", "long_to_bytes", "bytes_to_long",
+    "sha1", "sha256", "md5", "sha1_hex", "sha256_hex", "md5_hex", "hmac_sha256",
+    "keygen", "to_hex", "to_base64", "to_base32", "to_base58",
+    "score_text", "printable_ratio", "confidence_of",
+    "int_to_bits", "bits_to_int", "bytes_to_bits", "bits_to_bytes",
+    "detect_block_size", "is_ecb", "nullspace", "mat_inv", "mat_mul",
+    "poly_trim", "poly_mul", "poly_pow", "poly_eval", "gcd_list", "lcm_list",
+    "factor_from_phi", "factor_from_d", "crt_decrypt", "rsa_encrypt", "rsa_decrypt",
+}
+
+# Submodules are reached through the package (`cx.algebra.gcd`) or imported by name
+# (`from cryptoexp import algebra`); they are not star-exported either, because
+# `encoding`, `keys`, `stream` and `aes` are exactly the kind of names a caller
+# already has.
+_SUBMODULES = {
+    "algebra", "encoding", "lattice", "pad", "prng", "rsa_ops", "aes", "gf", "dlp",
+    "modular", "polytools", "gf2", "hashes", "stream", "rsa_attacks", "keys",
+    "prng_extra", "signatures", "symtools", "classical_extra", "forensics",
+    "oracle", "hypothesis", "lab",
+}
+
+__all__ = [name for name in _CANDIDATE_EXPORTS
+           if name not in _COLLISION_PRONE and name not in _SUBMODULES]
+
+
+def api(verbose: bool = False) -> str:
+    """Print/return the API map (the `from pwn import help` equivalent)"""
+    groups = {        "number theory": ["gcd", "egcd", "modinv", "crt", "iroot", "isqrt", "is_prime",
+                          "next_prime", "factor", "factor_limited", "divisors",
+                          "pollard_rho", "continued_fraction", "convergents",
+                          "fermat_factor", "bsgs", "tonelli_shanks", "lcg_recover"],
+        "encoding/classical": ["enhex", "unhex", "b64e", "b64d", "b32e", "b32d", "b58d",
+                               "score_text", "flag_candidates", "loose_flag_candidates",
+                               "find_flags", "set_flag_prefixes", "get_flag_prefixes",
+                               "build_flag_pattern",
+                               "decode_chain",
+                               "single_byte_xor", "repeating_key_xor", "caesar",
+                               "affine_decrypt", "vigenere_recover", "morse_decode",
+                               "morse_encode", "fence_decrypt"],
+        "bytes/padding": ["pkcs7_pad", "pkcs7_unpad", "pkcs7_valid", "xor",
+                          "xor_repeat", "blocks", "bitflip_cbc"],
+        "AES": ["aes.new", "aes.encrypt_ecb", "aes.decrypt_cbc", "aes.MODE_ECB"],
+        "lattice": ["lll", "coppersmith_univariate", "known_high_bits_factor",
+                    "subset_sum_lll"],
+        "RSA": ["keygen", "rsa_encrypt", "rsa_decrypt", "long_to_bytes",
+                "small_e_attack", "broadcast_attack", "common_modulus_attack",
+                "shared_prime_attack", "wiener_attack", "fermat_attack",
+                "pollard_attack", "dp_leak_attack", "phi_leak_attack",
+                "known_high_bits_attack", "auto_attack", "reencrypt_check"],
+        "PRNG": ["MT19937", "untemper", "clone_from_outputs", "predict_next",
+                 "clone_python_random", "crack_seed"],
+        "oracle attacks": ["detect_block_size", "detect_mode", "find_prefix_len",
+                           "ecb_byte_at_a_time", "padding_oracle_attack",
+                           "make_ecb_oracle", "make_cbc_oracle", "make_padding_oracle"],
+        "analysis/solve": ["analyze_all", "verify_candidates", "solve_script",
+                           "register_analyzer", "register_solver"],
+        "hypothesis engine / workbench": ["evaluate_hypotheses", "list_hypotheses",
+                                          "register_hypothesis", "write_workbench"],
+        "linear algebra / discrete log": ["solve_linear", "mat_inv", "recover_linear_map",
+                                          "solve_lcg_params", "discrete_log", "pohlig_hellman",
+                                          "dlog_feasibility", "mitm_subset_sum"],
+        "modular extras": ["legendre_symbol", "jacobi_symbol", "kronecker_symbol",
+                           "sqrt_mod", "totient", "carmichael", "mobius",
+                           "order_mod", "primitive_root", "crt_general", "pollard_pm1",
+                           "williams_pp1", "is_smooth", "binomial_mod"],
+        "polynomials": ["poly_divmod", "poly_gcd", "poly_roots_mod_p", "poly_from_roots",
+                        "poly_powmod", "poly_is_irreducible", "poly_resultant",
+                        "gf2_poly_gcd", "gf2_poly_roots"],
+        "GF(2) / LFSR / CRC": ["gf2_rref", "gf2_solve", "gf2_nullspace", "gf2_inv",
+                               "LFSR", "lfsr_recover", "lfsr_next", "berlekamp_massey",
+                               "CRC", "crc_compute", "crc_known", "crc_reverse_params",
+                               "crc_forge_append", "crc_solve_unknown",
+                               "bits_to_bytes", "bytes_to_bits"],
+        "hashes": ["sha1", "sha256", "md5", "sha1_hex", "sha256_hex",
+                   "length_extension", "HashState", "hmac_sha256"],
+        "stream ciphers": ["rc4", "ChaCha20", "chacha20", "aes_ctr", "aes_ctr_keystream",
+                           "crib_drag", "keystream_xor", "fixed_nonce_reuse_recover"],
+        "symmetric tools": ["is_ecb", "ecb_repeated_blocks", "infer_block_size",
+                            "cbc_flip_plaintext", "cbc_decrypt_blocks", "pad_pkcs7"],
+        "RSA attacks (extra)": ["franklin_reiter", "hastad_padded", "stereotyped_message",
+                                "parity_oracle_attack", "lsb_oracle_attack",
+                                "bleichenbacher_note"],
+        "keys": ["parse_pem", "parse_der_rsa_public", "parse_der_rsa_private",
+                 "parse_ssh_public_key", "parse_openssh_private", "rsa_public_der",
+                 "key_fingerprint_sha256", "pem_wrap"],
+        "signatures": ["ecdsa_nonce_reuse", "dsa_nonce_reuse", "ecdsa_verify",
+                       "ecdsa_sign", "dsa_sign", "rsa_e3_signature_forge",
+                       "pkcs1_v15_pad", "pkcs1_v15_unpad"],
+        "PRNG (extra)": ["java_random_recover", "java_random_predict",
+                         "glibc_rand_recover", "glibc_rand_predict",
+                         "xorshift_recover", "xorshift_predict",
+                         "lcg_recover_truncated"],
+        "forensics / assessment": ["batch_gcd", "common_factor_pairs",
+                                   "parse_der_signature", "parse_jwt",
+                                   "audit_rsa_key", "detect_weak_prng",
+                                   "find_flags", "set_flag_prefixes"],
+    }
+    lines = [f"cryptoexp {__version__} — dependency-free crypto toolkit", ""]
+    for group, names in groups.items():
+        lines.append(f"[{group}]")
+        lines.append("  " + ", ".join(names))
+    lines.append("")
+    lines.append("usage: import cryptoexp as cx; cx.algebra.gcd(24, 36); "
+                 "cx.crc_forge_append(...)")
+    lines.append("       from cryptoexp import * brings only unmistakably-ours names "
+                 "(star import is for throwaway scripts)")
+    text = "\n".join(lines)
+    print(text)
+    return text

cryptoexp/cli.py

@@ -0,0 +1,229 @@
+"""cryptoexp command line interface.
+
+Installed console script (`cryptoexp`) and the repository-level `cryptoexp_cli.py`
+shim both call `main()` here. English-first output.
+"""
+
+import argparse
+import contextlib
+import io
+import json
+import os
+import sys
+
+from .utils.output import (print_banner, print_error, print_info,
+                           print_section_header, print_success, print_warning)
+from .core.analysis import analyze_all, list_analyzers
+from .core.report import print_results, print_json_summary
+from .core.verify import verify_candidates
+from .core.solve import generate as gen_solve, list_solvers
+
+
+def _run_one(target: str, args) -> dict:
+    results = analyze_all(target, skip_encoding=args.no_encoding,
+                          effort=getattr(args, "effort", "normal"),
+                          flag_prefixes=getattr(args, "flag_prefix", None),
+                          flag_pattern=getattr(args, "flag_regex", None))
+    verification = verify_candidates(results)
+    results["verification"] = verification
+
+    if args.json:
+        print(print_json_summary(results, verification))
+        return results
+
+    print_section_header(f"Analyzing target: {target}")
+    print_results(results, verification)
+
+    if args.solve or args.run:
+        path = gen_solve(results, out_dir=args.out, only=args.only)
+        print_success(f"solve script: {path}")
+        if args.run:
+            print_info(f"running {path} ...")
+            import subprocess
+            proc = subprocess.run([sys.executable, path], capture_output=True,
+                                  text=True, timeout=120)
+            print(proc.stdout.rstrip() or "(no output)")
+            if proc.returncode != 0:
+                print_warning(f"script exit code {proc.returncode} "
+                              f"(may be a [skeleton], see the notes above)")
+                if proc.stderr.strip():
+                    print(proc.stderr.strip()[-500:])
+    return results
+
+
+def cmd_analyze(args):
+    if args.dir:
+        if not os.path.isdir(args.dir):
+            print_error(f"directory does not exist: {args.dir}")
+            return 1
+        entries = [os.path.join(args.dir, n) for n in sorted(os.listdir(args.dir))
+                   if os.path.isfile(os.path.join(args.dir, n))]
+        if not entries:
+            print_error("no files in the directory")
+            return 1
+        all_res = []
+        for i, p in enumerate(entries, 1):
+            if args.json:
+                buf = io.StringIO()
+                with contextlib.redirect_stdout(buf):
+                    r = _run_one(p, args)
+                all_res.append(json.loads(print_json_summary(r, r.get("verification"))))
+            else:
+                print(f"\n=== [{i}/{len(entries)}] {os.path.basename(p)} ===")
+                _run_one(p, args)
+        if args.json:
+            print(json.dumps(all_res, ensure_ascii=False, indent=2, default=str))
+        return 0
+
+    if not args.target:
+        print_error('analyze needs <target> or --dir; '
+                    'the target may be a file, a directory or challenge text')
+        return 1
+    _run_one(args.target, args)
+    return 0
+
+
+def cmd_hypotheses(args):
+    """Run the hypothesis engine end to end (every entry is really attempted)"""
+    from .hypothesis import params_from_ctx, evaluate
+    from .core.context import build_context
+
+    ctx = build_context(args.target)
+    params = params_from_ctx(ctx)
+    result = evaluate(params, budget="full")
+
+    if args.json:
+        print(json.dumps({
+            "target": args.target,
+            "applicable": result["applicable"],
+            "gaps": result["gaps"],
+            "results": [{k: v for k, v in r.items() if k != "plaintext"}
+                        for r in result["results"]],
+        }, ensure_ascii=False, indent=2, default=str))
+        return 0
+
+    print_section_header(f"Hypothesis engine: {args.target}")
+    if not result["results"]:
+        print_warning("no hypothesis applies — see the gap list below for the missing piece")
+    for r in result["results"]:
+        tag = {"confirmed": "[confirmed]", "candidate": "[candidate]",
+               "not_reproduced": "[not_reproduced]"}.get(r["state"], "[?]")
+        print(f"  {tag} {r['name']} ({r['domain']}, {r['cost']}) - {r['idea']}")
+        if r.get("detail"):
+            print(f"        {r['detail']}")
+        if r.get("note"):
+            print(f"        {r['note']}")
+        if r.get("plaintext"):
+            print(f"        plaintext: {r['plaintext'][:80]!r}")
+    print_section_header(f"Gap list ({len(result['gaps'])} entries)")
+    for g in result["gaps"]:
+        print(f"  - {g['name']} - {g['idea']}")
+        print(f"      missing: {'; '.join(g.get('missing', [])[:3])}")
+    return 0
+
+
+def cmd_lab(args):
+    """Generate the workbench scaffold (start here for challenges no template covers)"""
+    from .lab import write_workbench
+    from .hypothesis import params_from_ctx, evaluate
+
+    results = analyze_all(args.target, skip_encoding=args.no_encoding)
+    params = params_from_ctx(results.get("_ctx") or {})
+    hypotheses = evaluate(params, budget="full" if args.deep else "list")
+    path = write_workbench(results, out_dir=args.out, params=params,
+                           hypotheses=hypotheses)
+    print_success(f"workbench script: {path}")
+    print_info("open it: parameters are already extracted, applicable hypotheses and gaps "
+               "are written in comments, and the starting moves are ready to call")
+    if args.run:
+        import subprocess
+        proc = subprocess.run([sys.executable, path], capture_output=True,
+                              text=True, timeout=180)
+        print(proc.stdout.rstrip() or "(no output)")
+        if proc.returncode != 0 and proc.stderr.strip():
+            print_warning(proc.stderr.strip()[-400:])
+    return 0
+
+
+def cmd_list(args):
+    from .core.analysis import probe_optional_deps
+    print_section_header("Analyzers (built-in + plugins)")
+    for name in ("encoding", "classical", "rsa", "symmetric", "numbertheory", "lattice"):
+        print(f"  {name}")
+    for name in list_analyzers():
+        print(f"  {name}  (plugin)")
+    print_section_header("solve templates (lower priority runs first)")
+    for name, prio in list_solvers() or [("(not registered yet, loaded on first generation)", "-")]:
+        print(f"  {prio:>4}  {name}")
+    print_section_header("optional extras (core is dependency-free; missing ones are harmless)")
+    for mod, info in probe_optional_deps().items():
+        mark = "installed" if info["available"] else "missing"
+        print(f"  {mod:<8} {mark}  {info['use']}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="cryptoexp - cryptography CTF helper")
+    sub = parser.add_subparsers(dest="command")
+
+    p = sub.add_parser("analyze", help="analyze a challenge (file/directory/challenge text)")
+    p.add_argument("target", nargs="?", help="challenge file, directory, or raw challenge text")
+    p.add_argument("--dir", help="batch-analyze every file in a directory")
+    p.add_argument("--json", action="store_true", help="JSON output (schema v1.0)")
+    p.add_argument("--solve", action="store_true", help="generate a solve script")
+    p.add_argument("--run", action="store_true", help="generate and run the solve script")
+    p.add_argument("--out", default="solves",
+                   help="output directory for solve scripts (default solves/)")
+    p.add_argument("--only", help="only allow the solve template with this exact name")
+    p.add_argument("--no-encoding", action="store_true",
+                   help="skip encoding/XOR analysis (faster)")
+    p.add_argument("--effort", choices=["fast", "normal", "max"], default="normal",
+                   help="effort level: fast = cheap checks only / max = attempt everything")
+    p.add_argument("--flag-prefix", action="append", metavar="PREFIX",
+                   help="expected flag prefix, repeatable (e.g. --flag-prefix DH). "
+                        "Defaults to CRYPTOEXP_FLAG_PREFIXES, else the built-in "
+                        "CTF event list")
+    p.add_argument("--flag-regex", metavar="REGEX",
+                   help="a regex that replaces the prefix list entirely, for marker "
+                        "formats that are not PREFIX{...}")
+
+    sub.add_parser("list", help="list analyzers and solve templates")
+
+    p = sub.add_parser("hypotheses",
+                       help="run the hypothesis engine end to end (attack surface + gaps)")
+    p.add_argument("target", help="challenge file/directory/challenge text")
+    p.add_argument("--json", action="store_true", help="JSON output")
+
+    p = sub.add_parser("lab",
+                       help="generate a workbench scaffold (start here for long-tail challenges)")
+    p.add_argument("target", help="challenge file/directory/challenge text")
+    p.add_argument("--out", default="lab", help="output directory (default lab/)")
+    p.add_argument("--deep", action="store_true",
+                   help="try every hypothesis while generating (slow)")
+    p.add_argument("--run", action="store_true", help="run it once right after generating")
+    p.add_argument("--no-encoding", action="store_true", help="skip encoding/XOR analysis")
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 1
+    if not getattr(args, "json", False):
+        print_banner()
+    match args.command:
+        case "analyze":
+            return cmd_analyze(args)
+        case "hypotheses":
+            return cmd_hypotheses(args)
+        case "lab":
+            return cmd_lab(args)
+        case "list":
+            return cmd_list(args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())