gyntoolkit 2.1.1__py3-none-any.whl

gyntoolkit/recon.py

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""Recon passivo e ativo: WHOIS, DNS, geo, TLS, fingerprint, breaches, traceroute."""
+
+import ipaddress
+import re
+import socket
+import ssl
+from datetime import datetime, timezone
+from typing import Any
+
+import dns.resolver
+import requests
+import whois
+from colorama import Fore, Style
+from scapy.all import IP, TCP, sr1
+
+from . import i18n
+from .core import PROMPT, log, sanitize_input
+
+
+def whois_lookup(domain: str):
+    """Consulta informações WHOIS"""
+    try:
+        domain = sanitize_input(domain, r"[A-Za-z0-9.-]")
+        return whois.whois(domain)
+    except Exception as e:
+        return i18n.t("recon.whois_err", err=e)
+
+def dns_lookup(domain: str,
+               record_type: str = "A",
+               nameserver: str = None,
+               timeout: int = 5) -> list[str]:
+    """
+    Consulta registros DNS de um domínio.
+    :param domain: domínio a ser consultado
+    :param record_type: tipo de registro (A, AAAA, MX, TXT, CNAME, NS, SOA, etc.)
+    :param nameserver: servidor DNS (ex: "8.8.8.8"); None para usar o default
+    :param timeout: tempo máximo de espera, em segundos
+    :return: lista de strings com os dados retornados
+    """
+    resolver = dns.resolver.Resolver()
+    resolver.lifetime = timeout
+    if nameserver:
+        resolver.nameservers = [nameserver]
+    try:
+        answers = resolver.resolve(domain, record_type)
+        return [rdata.to_text() for rdata in answers]
+    except dns.resolver.NoAnswer:
+        return [i18n.t("dns.no_record", t=record_type, d=domain)]
+    except dns.resolver.NXDOMAIN:
+        return [i18n.t("dns.nxdomain", d=domain)]
+    except Exception as e:
+        return [i18n.t("dns.error", err=e)]
+
+def geo_ip(target: str) -> dict[str, str]:
+    """Geolocalização de IP/host via ip-api.com (free tier, sem key)."""
+    try:
+        ip = socket.gethostbyname(target)
+    except socket.gaierror as e:
+        return {"erro": i18n.t("recon.resolve_fail", t=target, err=e)}
+
+    fields = "status,message,continent,country,regionName,city,zip,lat,lon,timezone,isp,org,as,reverse,mobile,proxy,hosting,query"
+    try:
+        response = requests.get(
+            f"http://ip-api.com/json/{ip}",
+            params={"fields": fields},
+            headers={"User-Agent": "gyntoolkit/2.0"},
+            timeout=10,
+        )
+        response.raise_for_status()
+        data = response.json()
+        if data.get("status") != "success":
+            return {"erro": data.get("message", i18n.t("recon.query_failed"))}
+        return data
+    except (requests.RequestException, ValueError) as e:
+        log.warning("geo_ip %s falhou: %s", target, e)
+        return {"erro": str(e)}
+
+
+def reverse_dns(ip: str) -> dict[str, Any]:
+    """PTR lookup via socket + dnspython fallback."""
+    try:
+        ipaddress.ip_address(ip)
+    except ValueError:
+        try:
+            ip = socket.gethostbyname(ip)
+        except socket.gaierror as e:
+            return {"erro": i18n.t("recon.resolve_fail", t=ip, err=e)}
+    try:
+        hostname, aliases, addrs = socket.gethostbyaddr(ip)
+        return {"ip": ip, "hostname": hostname, "aliases": aliases, "addrs": addrs}
+    except socket.herror as e:
+        log.debug("reverse_dns %s falhou: %s", ip, e)
+        return {"ip": ip, "erro": i18n.t("recon.no_ptr", err=e)}
+
+
+def subdomain_enum(domain: str, timeout: int = 30) -> list[str]:
+    """Enumeração de subdomínios via crt.sh Certificate Transparency."""
+    try:
+        response = requests.get(
+            f"https://crt.sh/?q=%.{domain}&output=json",
+            headers={"User-Agent": "gyntoolkit/2.0"},
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        entries = response.json()
+    except (requests.RequestException, ValueError) as e:
+        log.warning("crt.sh falhou para %s: %s", domain, e)
+        return []
+
+    subs = set()
+    for entry in entries:
+        name_value = entry.get("name_value", "")
+        for name in name_value.split("\n"):
+            name = name.strip().lstrip("*.").lower()
+            if name and name.endswith(domain.lower()):
+                subs.add(name)
+    return sorted(subs)
+
+
+def _parse_cert_der(der: bytes) -> dict[str, Any]:
+    """Parse cert DER usando cryptography (parseamento robusto sem depender de validação TLS)."""
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes as crypto_hashes
+
+    cert = x509.load_der_x509_certificate(der)
+
+    def _name_attr(name_obj, oid):
+        try:
+            attrs = name_obj.get_attributes_for_oid(oid)
+            return attrs[0].value if attrs else None
+        except Exception:
+            return None
+
+    subject_cn = _name_attr(cert.subject, x509.NameOID.COMMON_NAME)
+    subject_org = _name_attr(cert.subject, x509.NameOID.ORGANIZATION_NAME)
+    issuer_cn = _name_attr(cert.issuer, x509.NameOID.COMMON_NAME)
+
+    sans: list[str] = []
+    try:
+        san_ext = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName)
+        sans = [str(n.value) for n in san_ext.value]
+    except x509.ExtensionNotFound:
+        pass
+
+    not_before = cert.not_valid_before_utc
+    not_after = cert.not_valid_after_utc
+    days_left = (not_after - datetime.now(timezone.utc)).days
+
+    fingerprint = cert.fingerprint(crypto_hashes.SHA256()).hex()
+
+    return {
+        "subject_cn": subject_cn,
+        "issuer_cn": issuer_cn,
+        "org": subject_org,
+        "not_before": not_before.strftime("%Y-%m-%d %H:%M:%S UTC"),
+        "not_after": not_after.strftime("%Y-%m-%d %H:%M:%S UTC"),
+        "dias_para_expirar": days_left,
+        "sans": sans,
+        "sha256": fingerprint,
+        "serial": format(cert.serial_number, "x"),
+        "signature_algo": cert.signature_algorithm_oid._name,
+    }
+
+
+def ssl_inspect(host: str, port: int = 443, timeout: int = 8) -> dict[str, Any]:
+    """Inspeciona certificado SSL/TLS do alvo (aceita cert inválido, apenas inspeciona)."""
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    try:
+        with (
+            socket.create_connection((host, port), timeout=timeout) as sock,
+            ctx.wrap_socket(sock, server_hostname=host) as tls,
+        ):
+            der = tls.getpeercert(binary_form=True)
+            cipher = tls.cipher()
+            version = tls.version()
+    except (TimeoutError, socket.gaierror, ConnectionRefusedError, OSError, ssl.SSLError) as e:
+        return {"erro": i18n.t("recon.ssl_fail", h=host, p=port, err=e)}
+
+    if not der:
+        return {"erro": i18n.t("recon.no_cert")}
+
+    try:
+        parsed = _parse_cert_der(der)
+    except Exception as e:
+        log.warning("Falha ao parsear cert DER: %s", e)
+        return {"erro": i18n.t("recon.cert_parse_fail", err=e)}
+
+    parsed.update({
+        "host": host,
+        "porta": port,
+        "tls_version": version,
+        "cipher": cipher[0] if cipher else None,
+    })
+    return parsed
+
+
+TECH_SIGNATURES = [
+    ("nginx", r"nginx"),
+    ("Apache", r"Apache"),
+    ("IIS", r"Microsoft-IIS"),
+    ("Cloudflare", r"cloudflare"),
+    ("PHP", r"PHP/"),
+    ("Express", r"Express"),
+    ("Django", r"csrftoken|Django"),
+    ("Rails", r"_rails_|Phusion"),
+    ("WordPress", r"wp-content|wp-includes"),
+    ("Laravel", r"laravel_session"),
+    ("ASP.NET", r"ASP\.NET|AspNet"),
+    ("Node.js", r"X-Powered-By.*Express|Node"),
+]
+
+
+def http_fingerprint(url: str, timeout: int = 10) -> dict[str, Any]:
+    """Detecta tecnologias via headers HTTP + cookies + body snippet."""
+    try:
+        response = requests.get(
+            url,
+            headers={"User-Agent": "Mozilla/5.0 gyntoolkit/2.0"},
+            timeout=timeout,
+            allow_redirects=True,
+            verify=False,
+        )
+    except requests.RequestException as e:
+        return {"erro": i18n.t("recon.http_fail", err=e)}
+
+    headers = dict(response.headers)
+    body_snippet = response.text[:8192]
+    haystack = "\n".join([f"{k}: {v}" for k, v in headers.items()]) + "\n" + body_snippet
+
+    techs = [name for name, pattern in TECH_SIGNATURES if re.search(pattern, haystack, re.IGNORECASE)]
+
+    return {
+        "url": response.url,
+        "status": response.status_code,
+        "redirects": len(response.history),
+        "server": headers.get("Server"),
+        "x_powered_by": headers.get("X-Powered-By"),
+        "content_type": headers.get("Content-Type"),
+        "set_cookie": headers.get("Set-Cookie"),
+        "hsts": headers.get("Strict-Transport-Security"),
+        "csp": headers.get("Content-Security-Policy"),
+        "xfo": headers.get("X-Frame-Options"),
+        "tech": techs,
+    }
+
+
+def internetdb_lookup(ip: str, timeout: int = 10) -> dict[str, Any]:
+    """Consulta InternetDB (Shodan free tier, sem key)."""
+    try:
+        socket.inet_aton(ip)
+    except OSError:
+        try:
+            ip = socket.gethostbyname(ip)
+        except socket.gaierror as e:
+            return {"erro": i18n.t("recon.resolve_fail_simple", err=e)}
+    try:
+        response = requests.get(
+            f"https://internetdb.shodan.io/{ip}",
+            headers={"User-Agent": "gyntoolkit/2.0"},
+            timeout=timeout,
+        )
+        if response.status_code == 404:
+            return {"ip": ip, "info": i18n.t("recon.internetdb_nodata")}
+        response.raise_for_status()
+        return response.json()
+    except (requests.RequestException, ValueError) as e:
+        log.warning("InternetDB %s falhou: %s", ip, e)
+        return {"erro": str(e)}
+
+
+def hibp_breaches(domain: str, timeout: int = 10) -> list[dict[str, Any]]:
+    """Consulta HIBP breaches por domínio (endpoint público)."""
+    try:
+        response = requests.get(
+            "https://haveibeenpwned.com/api/v3/breaches",
+            params={"domain": domain},
+            headers={"User-Agent": "gyntoolkit-recon"},
+            timeout=timeout,
+        )
+        if response.status_code == 404:
+            return []
+        response.raise_for_status()
+        return response.json()
+    except (requests.RequestException, ValueError) as e:
+        log.warning("HIBP falhou para %s: %s", domain, e)
+        return [{"erro": str(e)}]
+
+
+def mac_vendor(mac: str, timeout: int = 6) -> str:
+    """Lookup fabricante via api.macvendors.com (free, no key)."""
+    mac = mac.strip().replace("-", ":").upper()
+    if not re.fullmatch(r"([0-9A-F]{2}:){5}[0-9A-F]{2}", mac):
+        return i18n.t("recon.mac_invalid", mac=mac)
+    try:
+        response = requests.get(f"https://api.macvendors.com/{mac}", timeout=timeout)
+        if response.status_code == 200:
+            return response.text.strip()
+        return i18n.t("recon.not_found_http", code=response.status_code)
+    except requests.RequestException as e:
+        return i18n.t("recon.error", err=e)
+
+
+def traceroute(target: str, max_hops: int = 20, timeout: int = 3, dport: int = 80) -> list[dict[str, Any]]:
+    """Traceroute TCP via scapy (requer privilégio)."""
+    try:
+        target_ip = socket.gethostbyname(target)
+    except socket.gaierror as e:
+        return [{"erro": i18n.t("recon.resolve_fail_simple", err=e)}]
+
+    hops = []
+    for ttl in range(1, max_hops + 1):
+        pkt = IP(dst=target_ip, ttl=ttl) / TCP(dport=dport, flags="S")
+        start = datetime.now(timezone.utc)
+        try:
+            reply = sr1(pkt, timeout=timeout, verbose=0)
+        except PermissionError:
+            return [{"erro": i18n.t("recon.traceroute_priv")}]
+        except OSError as e:
+            return [{"erro": i18n.t("recon.scapy_err", err=e)}]
+        rtt_ms = (datetime.now(timezone.utc) - start).total_seconds() * 1000
+
+        if reply is None:
+            hops.append({"ttl": ttl, "ip": "*", "rtt_ms": None})
+            continue
+
+        hops.append({"ttl": ttl, "ip": reply.src, "rtt_ms": round(rtt_ms, 2)})
+        if reply.haslayer(TCP) and reply.getlayer(TCP).flags & 0x12:
+            break
+        if reply.haslayer("ICMP") and reply.getlayer("ICMP").type == 3:
+            break
+    return hops
+
+
+# Tipos DNS oferecidos no menu (ordem fixa). As descrições são localizadas
+# em runtime via i18n.t('dns.desc.<tipo>'), não armazenadas aqui.
+DNS_TYPES = ["A", "AAAA", "MX", "NS", "CNAME", "TXT", "SOA"]
+
+def escolher_tipo_dns() -> str:
+    """Mostra menu e retorna o tipo DNS escolhido"""
+    print(f"\n{Fore.CYAN}{i18n.t('dns.select')}{Style.RESET_ALL}")
+    for idx, tipo in enumerate(DNS_TYPES, 1):
+        print(f" {Fore.YELLOW}[{idx}]{Style.RESET_ALL} {tipo} → {i18n.t(f'dns.desc.{tipo}')}")
+    print(f" {Fore.YELLOW}[0]{Style.RESET_ALL} {i18n.t('dns.back')}")
+
+    while True:
+        try:
+            choice = int(input(f"\n{PROMPT}"))
+            if choice == 0:
+                return None
+            elif 1 <= choice <= len(DNS_TYPES):
+                return DNS_TYPES[choice - 1]
+            else:
+                raise ValueError
+        except ValueError:
+            print(f"{Fore.RED}{i18n.t('dns.invalid')}{Style.RESET_ALL}")

gyntoolkit/scan.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Varredura avançada: port scan (SYN/connect), banner, CVE lookup, host discovery."""
+
+import asyncio
+import contextlib
+import ipaddress
+import os
+
+import requests
+from colorama import Fore, Style
+from scapy.all import ARP, IP, TCP, Ether, sr1, srp
+
+from . import i18n
+from .core import TOP_PORTS, is_admin_windows, log
+
+
+async def syn_scan(target: str, port: int) -> tuple[int, bool]:
+    """Varredura stealth SYN (requer admin/root).
+
+    Se o scapy não conseguir enviar (sem Npcap/interface indisponível), degrada
+    para ``connect_scan`` em vez de derrubar toda a varredura.
+    """
+    try:
+        pkt = IP(dst=target)/TCP(dport=port, flags="S")
+        response = sr1(pkt, timeout=2, verbose=0)
+        if response is None:
+            return (port, False)
+        return (port, response.haslayer(TCP) and response.getlayer(TCP).flags == 0x12)
+    except (OSError, PermissionError) as e:
+        log.warning("syn_scan %s:%s falhou: %s", target, port, e)
+        return (port, False)
+    except Exception as e:
+        # scapy indisponível (ex.: interface/Npcap ausente): usa connect scan.
+        log.warning("syn_scan indisponível em %s:%s (%s); fallback connect_scan", target, port, e)
+        return await connect_scan(target, port)
+
+async def connect_scan(target: str, port: int) -> tuple[int, bool]:
+    """Varredura TCP completa"""
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(target, port),
+            timeout=2
+        )
+        writer.close()
+        await writer.wait_closed()
+        return (port, True)
+    except (asyncio.TimeoutError, ConnectionRefusedError, OSError):
+        return (port, False)
+
+async def get_banner(target: str, port: int) -> tuple[int, str]:
+    """Obtém banner do serviço"""
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(target, port),
+            timeout=3
+        )
+        writer.write(b"GET / HTTP/1.1\r\n\r\n")
+        banner = await asyncio.wait_for(reader.read(512), timeout=2)
+        writer.close()
+        with contextlib.suppress(OSError):
+            await writer.wait_closed()
+        return (port, banner.decode(errors='ignore').strip())
+    except (asyncio.TimeoutError, ConnectionRefusedError, OSError) as e:
+        log.debug("banner %s:%s vazio: %s", target, port, e)
+        return (port, "")
+
+def check_vulnerabilities(service: str) -> list[str]:
+    """Consulta NVD API 2.0 por CVEs associados ao serviço."""
+    if not service or service.lower() in {"desconhecido", "unknown"}:
+        return []
+    try:
+        response = requests.get(
+            "https://services.nvd.nist.gov/rest/json/cves/2.0",
+            params={"keywordSearch": service, "resultsPerPage": 5},
+            headers={"User-Agent": "gyntoolkit/2.0"},
+            timeout=15,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return [item["cve"]["id"] for item in data.get("vulnerabilities", [])[:5]]
+    except (requests.RequestException, ValueError, KeyError) as e:
+        log.warning("NVD lookup falhou para '%s': %s", service, e)
+        return []
+
+def network_discovery(cidr: str, timeout: int = 2) -> list[str]:
+    """Descobre hosts ativos em rede via ARP scan (requer privilégio)."""
+    try:
+        ipaddress.ip_network(cidr, strict=False)
+    except ValueError as e:
+        log.error("CIDR inválido '%s': %s", cidr, e)
+        print(f"{Fore.RED}{i18n.t('scan.cidr_invalid', err=e)}{Style.RESET_ALL}")
+        return []
+
+    try:
+        arp = ARP(pdst=cidr)
+        ether = Ether(dst="ff:ff:ff:ff:ff:ff")
+        answered, _ = srp(ether / arp, timeout=timeout, verbose=0)
+        hosts = sorted({r.psrc for _, r in answered}, key=lambda ip: ipaddress.ip_address(ip))
+        return hosts
+    except PermissionError:
+        print(f"{Fore.RED}{i18n.t('scan.arp_priv')}{Style.RESET_ALL}")
+        return []
+    except OSError as e:
+        log.error("ARP scan falhou: %s", e)
+        print(f"{Fore.RED}{i18n.t('scan.arp_fail', err=e)}{Style.RESET_ALL}")
+        return []
+
+async def perform_scan(target: str, scan_type: str) -> dict[int, dict]:
+    """Executa varredura completa com análise de vulnerabilidades"""
+    # aceita canônico "fast" e legados pt ("rápido"/"rapido"); resto = full range
+    ports = TOP_PORTS if scan_type in ("fast", "rápido", "rapido") else range(1, 65536)
+    open_ports = []
+    results = {}
+
+    # Fase 1: Varredura de portas.
+    # Privilégio é constante durante o scan: decide SYN vs connect uma vez.
+    use_syn = os.geteuid() == 0 if os.name == 'posix' else is_admin_windows()
+    tasks = [
+        syn_scan(target, port) if use_syn else connect_scan(target, port)
+        for port in ports
+    ]
+
+    # Processar resultados
+    for future in asyncio.as_completed(tasks):
+        port, is_open = await future
+        if is_open:
+            open_ports.append(port)
+
+    # Fase 2: Obter banners
+    banner_tasks = [get_banner(target, port) for port in open_ports]
+    banners = {}
+    for future in asyncio.as_completed(banner_tasks):
+        port, banner = await future
+        banners[port] = banner
+
+    # Fase 3: Analisar vulnerabilidades
+    for port in open_ports:
+        service = banners[port].split()[0] if banners[port] else "unknown"
+        vulns = check_vulnerabilities(service)
+
+        # 'service' e 'risco' são tokens neutros (DATA); o display os localiza
+        # via i18n (scan.service_unknown / scan.risk_high / scan.risk_low).
+        results[port] = {
+            'service': service,
+            'banner': banners[port],
+            'vulnerabilidades': vulns,
+            'risco': "high" if vulns else "low"
+        }
+
+    return results

gyntoolkit/ui.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Camada de apresentação com ``rich`` (tabelas, painéis, spinners).
+
+Degrada graciosamente para ``colorama`` puro se ``rich`` não estiver instalado,
+então a CLI funciona igual sem a dependência.
+"""
+
+from collections.abc import Iterable, Sequence
+from contextlib import contextmanager
+from typing import Any
+
+from colorama import Fore, Style
+
+try:
+    from rich import box
+    from rich.console import Console
+    from rich.table import Table
+
+    RICH = True
+    console = Console()
+except ImportError:  # pragma: no cover - fallback sem rich
+    RICH = False
+    console = None
+
+
+def _fmt(value: Any) -> str:
+    if value is None:
+        return "—"
+    if isinstance(value, (list, tuple)):
+        return ", ".join(str(v) for v in value) if value else "—"
+    return str(value)
+
+
+def success(msg: str) -> None:
+    if RICH:
+        console.print(f"[bold green]{msg}[/]")
+    else:
+        print(f"{Fore.GREEN}{msg}{Style.RESET_ALL}")
+
+
+def error(msg: str) -> None:
+    if RICH:
+        console.print(f"[bold red]{msg}[/]")
+    else:
+        print(f"{Fore.RED}{msg}{Style.RESET_ALL}")
+
+
+def notice(msg: str) -> None:
+    if RICH:
+        console.print(f"[cyan]{msg}[/]")
+    else:
+        print(f"{Fore.CYAN}{msg}{Style.RESET_ALL}")
+
+
+def print_kv(
+    title: str,
+    mapping: dict[str, Any],
+    warn_keys: dict[str, Any] | None = None,
+) -> None:
+    """Renderiza um mapa chave/valor. ``warn_keys`` marca chaves cujo valor,
+    se satisfizer o predicado, deve aparecer em vermelho.
+
+    ``warn_keys`` mapeia chave -> callable(value) -> bool.
+    """
+    warn_keys = warn_keys or {}
+    if RICH:
+        table = Table(title=title, box=box.SIMPLE_HEAVY, title_style="bold green",
+                      show_header=False, expand=False)
+        table.add_column("campo", style="yellow", no_wrap=True)
+        table.add_column("valor", style="white")
+        for k, v in mapping.items():
+            predicate = warn_keys.get(k)
+            style = "bold red" if predicate and predicate(v) else "white"
+            table.add_row(str(k), f"[{style}]{_fmt(v)}[/]")
+        console.print(table)
+    else:
+        print(f"\n{Fore.GREEN}{title}{Style.RESET_ALL}")
+        for k, v in mapping.items():
+            predicate = warn_keys.get(k)
+            color = Fore.RED if predicate and predicate(v) else Fore.YELLOW
+            print(f" {color}{k}:{Style.RESET_ALL} {_fmt(v)}")
+
+
+def print_table(
+    title: str,
+    columns: Sequence[str],
+    rows: Iterable[Sequence[Any]],
+    row_styles: list[str | None] | None = None,
+) -> None:
+    """Renderiza uma tabela. ``row_styles`` opcional colore cada linha (rich)."""
+    rows = list(rows)
+    if RICH:
+        table = Table(title=title, box=box.ROUNDED, title_style="bold green",
+                      header_style="bold yellow")
+        for col in columns:
+            table.add_column(str(col))
+        for idx, row in enumerate(rows):
+            style = row_styles[idx] if row_styles and idx < len(row_styles) else None
+            table.add_row(*[_fmt(c) for c in row], style=style)
+        console.print(table)
+    else:
+        print(f"\n{Fore.GREEN}{title}{Style.RESET_ALL}")
+        print(f" {Fore.YELLOW}{'  '.join(str(c) for c in columns)}{Style.RESET_ALL}")
+        for row in rows:
+            print("  " + "  ".join(_fmt(c) for c in row))
+
+
+def print_list(title: str, items: Sequence[Any]) -> None:
+    if RICH:
+        console.print(f"[bold green]{title}[/]")
+        for it in items:
+            console.print(f"  • {_fmt(it)}")
+    else:
+        print(f"\n{Fore.GREEN}{title}{Style.RESET_ALL}")
+        for it in items:
+            print(f" - {_fmt(it)}")
+
+
+@contextmanager
+def status(message: str):
+    """Spinner enquanto um bloco roda (rich). Fallback imprime a mensagem."""
+    if RICH:
+        with console.status(f"[cyan]{message}[/]", spinner="dots"):
+            yield
+    else:
+        print(f"{Fore.CYAN}{message}{Style.RESET_ALL}")
+        yield
+
+
+def kv_pairs(mapping: dict[str, Any], labels: dict[str, str]) -> list[tuple[str, Any]]:
+    """Filtra/relabela um dict preservando a ordem de ``labels``."""
+    return [(labels[k], mapping[k]) for k in labels if k in mapping]