nodeprobe 0.1.3__py3-none-any.whl

nodeprobe/__init__.py

@@ -0,0 +1,3 @@
+"""Nodeprobe EVM RPC security scanner."""
+
+__version__ = "0.1.3"

nodeprobe/__main__.py

@@ -0,0 +1,4 @@
+from nodeprobe.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nodeprobe/chains.py

@@ -0,0 +1,87 @@
+"""EVM chain registry — any chain ID is accepted; names from Chainlist when known."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+
+
+@dataclass(frozen=True)
+class ChainInfo:
+    chain_id: int
+    name: str
+    short_name: str
+    is_testnet: bool = False
+    listed: bool = True
+
+
+# Backward-compatible alias used by older imports/tests.
+SUPPORTED_CHAINS: dict[int, ChainInfo] = {}
+
+
+class UnsupportedChainError(ValueError):
+    """Deprecated: scans no longer abort on unknown chains.
+
+    Kept so older callers that catch this exception continue to work.
+    """
+
+    def __init__(self, chain_id: int | None, message: str | None = None):
+        self.chain_id = chain_id
+        super().__init__(
+            message or f"Unsupported or unknown chain ID: {chain_id}."
+        )
+
+
+@lru_cache(maxsize=1)
+def _load_registry() -> dict[int, ChainInfo]:
+    text = resources.files("nodeprobe").joinpath("data/chains_mini.json").read_text(
+        encoding="utf-8"
+    )
+    raw = json.loads(text)
+    registry: dict[int, ChainInfo] = {}
+    for key, value in raw.items():
+        chain_id = int(key)
+        registry[chain_id] = ChainInfo(
+            chain_id=chain_id,
+            name=str(value["name"]),
+            short_name=str(value.get("short_name") or f"chain-{chain_id}"),
+            is_testnet=bool(value.get("is_testnet")),
+            listed=True,
+        )
+    # Populate alias for introspection / tests that inspect the map.
+    SUPPORTED_CHAINS.clear()
+    SUPPORTED_CHAINS.update(registry)
+    return registry
+
+
+def known_chains() -> dict[int, ChainInfo]:
+    return dict(_load_registry())
+
+
+def resolve_chain(chain_id: int) -> ChainInfo:
+    """Resolve any EVM chain ID. Unknown IDs get a generic name and continue scanning."""
+    if not isinstance(chain_id, int):
+        raise TypeError(f"chain_id must be int, got {type(chain_id)!r}")
+    if chain_id < 0:
+        raise ValueError(f"chain_id must be non-negative, got {chain_id}")
+    info = _load_registry().get(chain_id)
+    if info is not None:
+        return info
+    return ChainInfo(
+        chain_id=chain_id,
+        name=f"Chain {chain_id}",
+        short_name=f"chain-{chain_id}",
+        is_testnet=False,
+        listed=False,
+    )
+
+
+def parse_hex_or_int(value: str | int) -> int:
+    if isinstance(value, int):
+        return value
+    text = str(value).strip()
+    if text.startswith("0x") or text.startswith("0X"):
+        return int(text, 16)
+    return int(text)

nodeprobe/cli.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from nodeprobe.contract_engine import ContractScannerEngine
+from nodeprobe.engine import ScannerEngine
+from nodeprobe.multichain import MultichainRpcEngine
+from nodeprobe.multichain.aptos_engine import APTOS_RULE_CATALOG, AptosScannerEngine
+from nodeprobe.multichain.cosmos_engine import COSMOS_RULE_CATALOG, CosmosScannerEngine
+from nodeprobe.multichain.near_engine import NEAR_RULE_CATALOG, NearScannerEngine
+from nodeprobe.multichain.solana_engine import SOLANA_RULE_CATALOG, SolanaScannerEngine
+from nodeprobe.multichain.starknet_engine import STARKNET_RULE_CATALOG, StarknetScannerEngine
+from nodeprobe.multichain.substrate_engine import (
+    SUBSTRATE_RULE_CATALOG,
+    SubstrateScannerEngine,
+)
+from nodeprobe.multichain.sui_engine import SUI_RULE_CATALOG, SuiScannerEngine
+from nodeprobe.profiles import PROFILES
+from nodeprobe.report import format_html_report, format_human_report
+from nodeprobe.rules import all_rules
+from nodeprobe.rules.web import web_rules
+from nodeprobe.web_engine import WebScannerEngine
+
+CONTRACT_RULE_CATALOG = [
+    {"rule_id": "SC-IDENT-001", "title": "RPC chain ID mismatch", "category": "Identity"},
+    {"rule_id": "SC-IDENT-002", "title": "Chain not in local name registry", "category": "Identity"},
+    {"rule_id": "SC-CODE-001", "title": "Contract code presence", "category": "Code"},
+    {"rule_id": "SC-PROXY-001", "title": "Proxy pattern detection", "category": "Proxy"},
+    {"rule_id": "SC-BYTE-001", "title": "SELFDESTRUCT presence", "category": "Bytecode"},
+    {"rule_id": "SC-BYTE-002", "title": "DELEGATECALL presence", "category": "Bytecode"},
+    {"rule_id": "SC-SRC-001", "title": "Sourcify verification", "category": "Source"},
+    {"rule_id": "SC-IFACE-001", "title": "Interface hints", "category": "Interfaces"},
+    {"rule_id": "SC-IFACE-002", "title": "Ownable-style ownership surface", "category": "Access Control"},
+]
+
+
+_PROFILE_HELP = (
+    "Scan profile: Quick | Standard | Deep "
+    "(aliases: Free→Quick, Outbound→Standard, Authorized-Full→Deep; default: Standard)"
+)
+_FAMILY_HELP = (
+    "RPC family: auto | evm | solana | substrate | cosmos | aptos | sui | starknet | near "
+    "(default: auto)"
+)
+
+
+def _add_output_flags(parser: argparse.ArgumentParser) -> None:
+    fmt = parser.add_mutually_exclusive_group()
+    fmt.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit JSON instead of a human-readable report",
+    )
+    fmt.add_argument(
+        "--html",
+        action="store_true",
+        help="Emit a self-contained HTML report",
+    )
+    parser.add_argument(
+        "--pretty",
+        action="store_true",
+        help="With --json: indent JSON. Without --json: human report (default).",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="PATH",
+        help="Write the report to PATH instead of stdout",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Human report: include evidence and full detail for Low/Info findings",
+    )
+    color = parser.add_mutually_exclusive_group()
+    color.add_argument(
+        "--color",
+        action="store_true",
+        help="Force ANSI colors in the human report",
+    )
+    color.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI colors in the human report",
+    )
+
+
+def _add_rpc_flags(parser: argparse.ArgumentParser, *, include_family: bool = False) -> None:
+    parser.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    if include_family:
+        parser.add_argument("--family", default="auto", help=_FAMILY_HELP)
+    parser.add_argument(
+        "--block-providers",
+        action="store_true",
+        help="Block known third-party provider hostnames (EVM only)",
+    )
+    _add_output_flags(parser)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nodeprobe",
+        description=(
+            "Nodeprobe — website, multi-chain RPC, and EVM contract scanner"
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    rpc = sub.add_parser(
+        "rpc",
+        help="Scan an RPC endpoint (auto-detect family, or set --family)",
+    )
+    rpc.add_argument("url", help="HTTP(S) RPC endpoint URL")
+    _add_rpc_flags(rpc, include_family=True)
+
+    scan = sub.add_parser("scan", help="Scan an EVM JSON-RPC endpoint (alias of rpc --family evm)")
+    scan.add_argument("url", help="HTTP(S) JSON-RPC endpoint URL")
+    _add_rpc_flags(scan)
+
+    solana = sub.add_parser("solana", help="Scan a Solana JSON-RPC endpoint")
+    solana.add_argument("url", help="HTTP(S) Solana RPC URL")
+    solana.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(solana)
+
+    substrate = sub.add_parser(
+        "substrate",
+        help="Scan a Substrate / Polkadot JSON-RPC endpoint",
+    )
+    substrate.add_argument("url", help="HTTP(S) Substrate RPC URL")
+    substrate.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(substrate)
+
+    cosmos = sub.add_parser("cosmos", help="Scan a Cosmos / Tendermint RPC endpoint")
+    cosmos.add_argument("url", help="HTTP(S) Tendermint / Cosmos RPC URL")
+    cosmos.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(cosmos)
+
+    aptos = sub.add_parser("aptos", help="Scan an Aptos fullnode REST API (/v1)")
+    aptos.add_argument("url", help="HTTP(S) Aptos fullnode URL (with or without /v1)")
+    aptos.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(aptos)
+
+    sui = sub.add_parser("sui", help="Scan a Sui GraphQL RPC endpoint")
+    sui.add_argument("url", help="HTTP(S) Sui GraphQL RPC URL")
+    sui.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(sui)
+
+    starknet = sub.add_parser("starknet", help="Scan a Starknet JSON-RPC endpoint")
+    starknet.add_argument("url", help="HTTP(S) Starknet JSON-RPC URL")
+    starknet.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(starknet)
+
+    near = sub.add_parser("near", help="Scan a NEAR JSON-RPC endpoint")
+    near.add_argument("url", help="HTTP(S) NEAR JSON-RPC URL")
+    near.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(near)
+
+    web = sub.add_parser("web", help="Scan a website (HTTP/TLS surface)")
+    web.add_argument("url", help="HTTP(S) website URL")
+    web.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    _add_output_flags(web)
+
+    contract = sub.add_parser("contract", help="Scan an EVM smart contract via read-only RPC")
+    contract.add_argument("address", help="Contract address (0x…)")
+    contract.add_argument("--rpc", required=True, help="HTTP(S) JSON-RPC URL for the chain")
+    contract.add_argument("--chain", type=int, default=None, help="Expected chain ID")
+    contract.add_argument("--profile", default="Standard", help=_PROFILE_HELP)
+    contract.add_argument(
+        "--no-sourcify",
+        action="store_true",
+        help="Skip Sourcify verification lookup",
+    )
+    _add_output_flags(contract)
+
+    sub.add_parser("profiles", help="List scan profiles and budgets")
+    rules = sub.add_parser("rules", help="List registered rules")
+    rules.add_argument(
+        "--module",
+        choices=(
+            "rpc",
+            "evm",
+            "web",
+            "contract",
+            "solana",
+            "substrate",
+            "cosmos",
+            "aptos",
+            "sui",
+            "starknet",
+            "near",
+            "all",
+        ),
+        default="all",
+        help="Rule module to list (default: all)",
+    )
+
+    return parser
+
+
+def _color_flag(args: argparse.Namespace) -> bool | None:
+    if getattr(args, "no_color", False):
+        return False
+    if getattr(args, "color", False):
+        return True
+    return None
+
+
+def _print_result(
+    result,
+    *,
+    as_json: bool,
+    as_html: bool,
+    pretty: bool,
+    color: bool | None,
+    verbose: bool = False,
+    output: str | None = None,
+) -> int:
+    if as_json:
+        payload = json.dumps(result.to_dict(), indent=2 if pretty else None)
+    elif as_html:
+        payload = format_html_report(result)
+    else:
+        payload = format_human_report(result, color=color, verbose=verbose)
+
+    if output:
+        with open(output, "w", encoding="utf-8") as handle:
+            handle.write(payload if payload.endswith("\n") else payload + "\n")
+        print(f"Wrote report to {output}", file=sys.stderr)
+    else:
+        print(payload, end="" if payload.endswith("\n") else "\n")
+
+    if result.aborted and result.abort_reason in {
+        "unsafe_target",
+        "third_party_provider",
+        "kill_switch",
+        "invalid_address",
+        "unknown_family",
+    }:
+        return 2
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "profiles":
+        payload = {
+            name.value: {
+                "max_requests": limits.max_requests,
+                "max_rps": limits.max_rps,
+                "max_duration_seconds": limits.max_duration_seconds,
+                "allow_expensive_namespace_calls": limits.allow_expensive_namespace_calls,
+                "allow_rate_limit_stress": limits.allow_rate_limit_stress,
+            }
+            for name, limits in PROFILES.items()
+        }
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    if args.command == "rules":
+        module = args.module
+        payload = []
+        if module in {"rpc", "evm", "all"}:
+            payload.extend(
+                {
+                    "rule_id": r.meta.rule_id,
+                    "title": r.meta.title,
+                    "category": r.meta.category,
+                    "severity": r.meta.severity.value,
+                    "kind": r.meta.kind.value,
+                    "profiles": [p.value for p in r.meta.allowed_profiles],
+                    "module": "evm",
+                }
+                for r in all_rules()
+            )
+        if module in {"web", "all"}:
+            payload.extend(
+                {
+                    "rule_id": r.meta.rule_id,
+                    "title": r.meta.title,
+                    "category": r.meta.category,
+                    "severity": r.meta.severity.value,
+                    "kind": r.meta.kind.value,
+                    "profiles": [p.value for p in r.meta.allowed_profiles],
+                    "module": "web",
+                }
+                for r in web_rules()
+            )
+        if module in {"contract", "all"}:
+            payload.extend(
+                {
+                    **item,
+                    "severity": "varies",
+                    "kind": "finding",
+                    "profiles": ["Quick", "Standard", "Deep"],
+                    "module": "contract",
+                }
+                for item in CONTRACT_RULE_CATALOG
+            )
+        if module in {"solana", "rpc", "all"}:
+            payload.extend(
+                {**item, "severity": "varies", "kind": "finding", "profiles": ["Quick", "Standard", "Deep"], "module": "solana"}
+                for item in SOLANA_RULE_CATALOG
+            )
+        if module in {"substrate", "rpc", "all"}:
+            payload.extend(
+                {**item, "severity": "varies", "kind": "finding", "profiles": ["Quick", "Standard", "Deep"], "module": "substrate"}
+                for item in SUBSTRATE_RULE_CATALOG
+            )
+        if module in {"cosmos", "rpc", "all"}:
+            payload.extend(
+                {**item, "severity": "varies", "kind": "finding", "profiles": ["Quick", "Standard", "Deep"], "module": "cosmos"}
+                for item in COSMOS_RULE_CATALOG
+            )
+        if module in {"aptos", "rpc", "all"}:
+            payload.extend(
+                {
+                    **item,
+                    "severity": "varies",
+                    "kind": "finding",
+                    "profiles": ["Quick", "Standard", "Deep"],
+                    "module": "aptos",
+                }
+                for item in APTOS_RULE_CATALOG
+            )
+        if module in {"sui", "rpc", "all"}:
+            payload.extend(
+                {
+                    **item,
+                    "severity": "varies",
+                    "kind": "finding",
+                    "profiles": ["Quick", "Standard", "Deep"],
+                    "module": "sui",
+                }
+                for item in SUI_RULE_CATALOG
+            )
+        if module in {"starknet", "rpc", "all"}:
+            payload.extend(
+                {
+                    **item,
+                    "severity": "varies",
+                    "kind": "finding",
+                    "profiles": ["Quick", "Standard", "Deep"],
+                    "module": "starknet",
+                }
+                for item in STARKNET_RULE_CATALOG
+            )
+        if module in {"near", "rpc", "all"}:
+            payload.extend(
+                {
+                    **item,
+                    "severity": "varies",
+                    "kind": "finding",
+                    "profiles": ["Quick", "Standard", "Deep"],
+                    "module": "near",
+                }
+                for item in NEAR_RULE_CATALOG
+            )
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    color = _color_flag(args)
+    out_kwargs = {
+        "as_json": bool(getattr(args, "json", False)),
+        "as_html": bool(getattr(args, "html", False)),
+        "pretty": bool(getattr(args, "pretty", False)),
+        "color": color,
+        "verbose": bool(getattr(args, "verbose", False)),
+        "output": getattr(args, "output", None),
+    }
+
+    if args.command == "rpc":
+        result = MultichainRpcEngine(
+            args.url,
+            args.profile,
+            family=args.family,
+            block_providers=args.block_providers,
+        ).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "scan":
+        result = ScannerEngine(
+            args.url,
+            args.profile,
+            block_providers=args.block_providers,
+        ).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "solana":
+        result = SolanaScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "substrate":
+        result = SubstrateScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "cosmos":
+        result = CosmosScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "aptos":
+        result = AptosScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "sui":
+        result = SuiScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "starknet":
+        result = StarknetScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "near":
+        result = NearScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "web":
+        result = WebScannerEngine(args.url, args.profile).run()
+        return _print_result(result, **out_kwargs)
+
+    if args.command == "contract":
+        result = ContractScannerEngine(
+            args.address,
+            rpc_url=args.rpc,
+            chain_id=args.chain,
+            profile=args.profile,
+            fetch_verification=not args.no_sourcify,
+        ).run()
+        return _print_result(result, **out_kwargs)
+
+    parser.error(f"Unknown command: {args.command}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nodeprobe/contract/__init__.py

@@ -0,0 +1,18 @@
+from nodeprobe.contract.address import is_empty_code, normalize_address
+from nodeprobe.contract.bytecode import analyze_bytecode, extract_selectors
+from nodeprobe.contract.interfaces import interfaces_from_abi, interfaces_from_selectors
+from nodeprobe.contract.proxy import detect_eip1167, detect_proxies_from_slots
+from nodeprobe.contract.sourcify import SourcifyMatch, fetch_sourcify
+
+__all__ = [
+    "SourcifyMatch",
+    "analyze_bytecode",
+    "detect_eip1167",
+    "detect_proxies_from_slots",
+    "extract_selectors",
+    "fetch_sourcify",
+    "interfaces_from_abi",
+    "interfaces_from_selectors",
+    "is_empty_code",
+    "normalize_address",
+]

nodeprobe/contract/address.py

@@ -0,0 +1,21 @@
+"""Address helpers for contract scans."""
+
+from __future__ import annotations
+
+import re
+
+_ADDR_RE = re.compile(r"^0x[a-fA-F0-9]{40}$")
+
+
+def normalize_address(value: str) -> str:
+    text = (value or "").strip()
+    if not _ADDR_RE.match(text):
+        raise ValueError(f"Invalid EVM address: {value!r}")
+    return text.lower()
+
+
+def is_empty_code(code: str | None) -> bool:
+    if code is None:
+        return True
+    cleaned = code.strip().lower()
+    return cleaned in {"", "0x", "0x0"}

nodeprobe/contract/bytecode.py

@@ -0,0 +1,77 @@
+"""Bytecode opcode heuristics (presence-only, no symbolic execution)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OpcodeHit:
+    name: str
+    opcode: str
+    count: int
+
+
+# Single-byte opcodes of interest. Presence is informational / low-severity —
+# many legitimate contracts use DELEGATECALL (proxies) and rarely SELFDESTRUCT.
+_INTERESTING = {
+    "f4": "DELEGATECALL",
+    "ff": "SELFDESTRUCT",
+    "f1": "CALL",
+    "f2": "CALLCODE",
+    "55": "SSTORE",
+}
+
+
+def analyze_bytecode(code_hex: str) -> list[OpcodeHit]:
+    raw = code_hex.lower().removeprefix("0x")
+    if len(raw) % 2:
+        raw = raw[:-1]
+    counts: dict[str, int] = {k: 0 for k in _INTERESTING}
+    i = 0
+    while i < len(raw) - 1:
+        op = raw[i : i + 2]
+        # PUSH1..PUSH32 skip immediate data
+        try:
+            op_int = int(op, 16)
+        except ValueError:
+            i += 2
+            continue
+        if 0x60 <= op_int <= 0x7F:
+            n = op_int - 0x5F
+            i += 2 + (n * 2)
+            continue
+        if op in counts:
+            counts[op] += 1
+        i += 2
+    return [
+        OpcodeHit(name=_INTERESTING[op], opcode="0x" + op, count=count)
+        for op, count in counts.items()
+        if count > 0
+    ]
+
+
+def extract_selectors(code_hex: str) -> set[str]:
+    """Best-effort 4-byte selector harvest from PUSH4 immediates."""
+    raw = code_hex.lower().removeprefix("0x")
+    selectors: set[str] = set()
+    i = 0
+    while i < len(raw) - 1:
+        op = raw[i : i + 2]
+        try:
+            op_int = int(op, 16)
+        except ValueError:
+            i += 2
+            continue
+        if op_int == 0x63:  # PUSH4
+            sel = raw[i + 2 : i + 10]
+            if len(sel) == 8:
+                selectors.add("0x" + sel)
+            i += 10
+            continue
+        if 0x60 <= op_int <= 0x7F:
+            n = op_int - 0x5F
+            i += 2 + (n * 2)
+            continue
+        i += 2
+    return selectors