ecdat 0.2.0__py3-none-any.whl

ecdat/__init__.py

@@ -0,0 +1,10 @@
+"""ECDAT — Enterprise Cryptographic Discovery & Analysis Tool."""
+
+import importlib.metadata
+
+DIST_NAME = "ecdat"
+
+try:
+    __version__ = importlib.metadata.version(DIST_NAME)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0+unknown"

ecdat/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m ecdat` to run the CLI."""
+
+from ecdat.cli import main
+
+raise SystemExit(main())

ecdat/cli/__init__.py

@@ -0,0 +1,203 @@
+"""ECDAT CLI — entry point and command dispatch.
+
+:func:`main` is the single guard rail for the whole CLI: it converts known
+user errors (:class:`~ecdat.services.scanner.ScanError`), interrupts, and
+broken pipes into clean exit codes, and turns genuinely unexpected exceptions
+into a crash-log entry instead of a bare traceback.
+
+Importing this module stays cheap — Rich, the scanner engine, and the crash
+logger are all imported lazily.  ``textual`` is never imported here (the TUI
+is loaded by its own command, later).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+from ecdat.cli.parser import COMMANDS, build_parser
+
+__all__ = ["main"]
+
+
+def main(argv: Optional[list] = None) -> int:
+    """Run the ECDAT CLI and return a process exit code.
+
+    Args:
+        argv: Argument list; defaults to ``sys.argv[1:]``.
+
+    Returns:
+        ``0`` on success, ``1`` when ``--fail-on`` is tripped, ``2`` on
+        usage/validation errors, ``3`` on unexpected errors, ``130`` on
+        ``Ctrl-C``.
+    """
+    if argv is None:
+        argv = list(sys.argv[1:])
+
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # argparse handles --help (0) and usage errors (2) itself.
+        return _system_exit_code(exc)
+
+    try:
+        if getattr(args, "version", False):
+            _print_version()
+            return 0
+
+        command = getattr(args, "command", None)
+        if not command:
+            return _run_bare(args)
+
+        module = COMMANDS.get(command)
+        if module is None:
+            _print_error(args, f"Unknown command: {command}")
+            return 2
+        return module.run(args)
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        _silence_stdout()
+        return 0
+    except Exception as exc:  # noqa: BLE001 - top-level guard rail
+        return _handle_exception(exc, argv, args)
+
+
+# ---------------------------------------------------------------------------
+# Exit-code / error handling
+# ---------------------------------------------------------------------------
+
+
+def _system_exit_code(exc: SystemExit) -> int:
+    """Map an argparse :class:`SystemExit` to a plain integer exit code."""
+    code = exc.code
+    if code is None:
+        return 0
+    if isinstance(code, int):
+        return code
+    return 2
+
+
+def _handle_exception(exc: Exception, argv: list, args) -> int:
+    """Route an exception to the right handler; return the exit code."""
+    from ecdat.services.scanner import ScanError
+
+    if isinstance(exc, ScanError):
+        _print_scan_error(args, exc)
+        return exc.exit_code
+    return _handle_unexpected(exc, argv, args)
+
+
+def _handle_unexpected(exc: Exception, argv: list, args) -> int:
+    """Record an unexpected crash and report a friendly message; return 3."""
+    from ecdat.services.crashlog import write_crash_log
+    from rich.text import Text
+
+    log_path = write_crash_log(exc, argv)
+    details = str(log_path) if log_path is not None else "(crash log unavailable)"
+
+    console = _console(stderr=True, args=args)
+    console.print(
+        Text(
+            f"ECDAT hit an unexpected error. Details: {details}. "
+            f"Re-run with --debug for the traceback and attach "
+            f"`ecdat doctor` output to an issue.",
+            style="bold red",
+        )
+    )
+
+    if _is_debug(args):
+        import traceback
+
+        traceback.print_exception(type(exc), exc, exc.__traceback__)
+
+    return 3
+
+
+def _print_scan_error(args, exc) -> None:
+    """Print a known :class:`ScanError` (plus optional hint) to stderr."""
+    from rich.text import Text
+
+    console = _console(stderr=True, args=args)
+    console.print(Text(f"Error: {exc.user_message}", style="bold red"))
+    if exc.hint:
+        console.print(Text(f"Hint: {exc.hint}", style="dim"))
+
+
+def _print_error(args, message: str) -> None:
+    """Print a plain error line to stderr."""
+    from rich.text import Text
+
+    _console(stderr=True, args=args).print(Text(f"Error: {message}", style="bold red"))
+
+
+def _print_version() -> None:
+    """Write ``ecdat <version>`` to stdout."""
+    from ecdat import __version__
+
+    sys.stdout.write(f"ecdat {__version__}\n")
+
+
+# ---------------------------------------------------------------------------
+# Bare invocation
+# ---------------------------------------------------------------------------
+
+
+def _run_bare(args) -> int:
+    """Print the banner and example commands (no subcommand given)."""
+    from rich.text import Text
+
+    from ecdat import __version__
+    from ecdat.ui.banner import render_banner
+
+    console = _console(args=args)
+    console.print(render_banner(version=__version__))
+    console.print(Text(""))
+    console.print(Text("Try one of these:", style="bold"))
+    for example in ("ecdat demo", "ecdat scan .", "ecdat about", "ecdat help"):
+        console.print(Text(f"  {example}"))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Small utilities
+# ---------------------------------------------------------------------------
+
+
+def _is_debug(args) -> bool:
+    """Return ``True`` when ``--debug`` or ``ECDAT_DEBUG=1`` is set."""
+    if args is not None and getattr(args, "debug", False):
+        return True
+    return os.environ.get("ECDAT_DEBUG", "").strip() == "1"
+
+
+def _console(*, stderr: bool = False, args=None):
+    """Create a themed Rich console via the sanctioned factory."""
+    from ecdat.ui.console import make_console
+
+    no_color = None
+    if args is not None and getattr(args, "no_color", False):
+        no_color = True
+    return make_console(stderr=stderr, no_color=no_color)
+
+
+def _silence_stdout() -> None:
+    """Redirect the real stdout fd to ``/dev/null`` after a broken pipe.
+
+    Prevents Python's interpreter-shutdown flush from re-raising on a pipe
+    that a downstream reader (e.g. ``head``) already closed.  Best-effort.
+    """
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        try:
+            os.dup2(devnull, sys.stdout.fileno())
+        finally:
+            os.close(devnull)
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

ecdat/cli/commands/about.py

@@ -0,0 +1,130 @@
+"""``ecdat about`` — credits, project links, and the animated globe.
+
+The globe is decorative, so it is strictly opt-in: it only animates when the
+output is an interactive terminal, motion is enabled
+(:func:`ecdat.ui.motion.animations_enabled`), ``--no-anim`` is absent, and
+``--spin`` is positive.  When any of those is false, exactly one static frame
+is printed — no cursor movement, no escape codes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+NAME = "about"
+
+_DESCRIPTION = (
+    "ECDAT discovers cryptographic artefacts in source code and dependency "
+    "manifests, scores their post-quantum risk with Mosca's inequality, and "
+    "exports a CycloneDX 1.6 Cryptography Bill of Materials."
+)
+_LICENSE_LINE = "MIT \u00b7 https://github.com/profm0r14rty/ecdat"
+_BUILT_WITH = "Built with Rich"
+
+_FPS = 14.0
+_GLOBE_MAX_WIDTH = 56
+_GLOBE_MAX_HEIGHT = 22
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    """Attach the ``about`` subcommand to *subparsers*."""
+    parser = subparsers.add_parser(
+        "about",
+        help="About ECDAT \u2014 credits and a spinning globe",
+        description=(
+            "Show the ECDAT banner, a short description, and (on an "
+            "interactive terminal) an animated 3D globe."
+        ),
+    )
+    parser.add_argument(
+        "--spin",
+        type=float,
+        default=3.0,
+        metavar="SECONDS",
+        help="Seconds to animate the globe (default: 3; 0 disables)",
+    )
+    parser.add_argument(
+        "--no-anim",
+        action="store_true",
+        help="Never animate; print a single static frame",
+    )
+
+
+def run(args) -> int:
+    """Print credits and optionally animate the globe; return 0."""
+    from rich.style import Style
+    from rich.text import Text
+
+    from ecdat import __version__
+    from ecdat.ui.banner import render_banner
+    from ecdat.ui.console import make_console
+    from ecdat.ui.motion import animations_enabled
+    from ecdat.ui.theme import PALETTE
+
+    no_color = True if getattr(args, "no_color", False) else None
+    console = make_console(no_color=no_color)
+
+    console.print(render_banner(version=__version__))
+    console.print(Text(_DESCRIPTION))
+    console.print(Text(_LICENSE_LINE, style=Style(color=PALETTE.muted)))
+    console.print(Text(_BUILT_WITH, style=Style(color=PALETTE.muted)))
+    console.print(Text())
+
+    width, height = _globe_size(console)
+    spin = max(0.0, float(getattr(args, "spin", 0.0)))
+    animate = (
+        not getattr(args, "no_anim", False)
+        and spin > 0.0
+        and console.is_terminal
+        and animations_enabled()
+    )
+
+    if animate:
+        _animate(console, width, height, spin)
+    else:
+        console.print(_frame_text(0.0, width, height))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _globe_size(console) -> tuple[int, int]:
+    """Return the globe frame size: terminal size capped at 56x22."""
+    size = console.size
+    return (
+        max(1, min(size.width, _GLOBE_MAX_WIDTH)),
+        max(1, min(size.height, _GLOBE_MAX_HEIGHT)),
+    )
+
+
+def _frame_text(elapsed: float, width: int, height: int):
+    """Render one globe frame as gradient-coloured Rich Text."""
+    from ecdat.ui.art3d import render_globe
+    from ecdat.ui.art_text import frame_to_text
+
+    return frame_to_text(render_globe(elapsed, width, height))
+
+
+def _animate(console, width: int, height: int, seconds: float) -> None:
+    """Animate the globe for *seconds* using real elapsed wall-clock time.
+
+    Uses :class:`rich.live.Live` with ``transient=False`` so the final frame
+    stays on screen.  ``Ctrl-C`` propagates out (the Live context restores the
+    terminal, and the CLI maps it to exit code 130).
+    """
+    from rich.live import Live
+
+    interval = 1.0 / _FPS
+    start = time.monotonic()
+
+    with Live(console=console, refresh_per_second=int(_FPS), transient=False) as live:
+        elapsed = 0.0
+        while elapsed < seconds:
+            elapsed = time.monotonic() - start
+            live.update(_frame_text(elapsed, width, height))
+            time.sleep(min(interval, max(0.0, seconds - elapsed)))
+        live.update(_frame_text(seconds, width, height))

ecdat/cli/commands/demo.py

@@ -0,0 +1,116 @@
+"""``ecdat demo`` — scan the bundled sample project.
+
+A zero-setup "try it now" command: copies the demo project shipped inside the
+package to a temporary directory, scans it through the same
+:func:`~ecdat.services.scanner.perform_scan` path as ``ecdat scan``, and
+renders the usual report.  ``--path`` instead materialises a persistent copy
+under ``ECDAT_HOME/demo`` and prints its location.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+NAME = "demo"
+
+_FORMATS = ("pretty", "json", "summary")
+
+_PRETTY_NOTE = "Bundled sample code \u2014 intentionally insecure, never run it."
+_LABEL = "demo project (bundled sample)"
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    """Attach the ``demo`` subcommand to *subparsers*."""
+    parser = subparsers.add_parser(
+        "demo",
+        help="Scan the bundled sample project (zero setup)",
+        description=(
+            "Scan ECDAT's bundled, deliberately-insecure sample project. "
+            "With --path, materialise a persistent copy under ECDAT_HOME/demo "
+            "instead of scanning."
+        ),
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=_FORMATS,
+        default="pretty",
+        help="Output format (default: pretty)",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=15,
+        metavar="N",
+        help="Maximum findings shown in the pretty table (default: 15)",
+    )
+    parser.add_argument(
+        "--path",
+        action="store_true",
+        help="Copy the sample under ECDAT_HOME/demo and print its path",
+    )
+
+
+def run(args) -> int:
+    """Run the demo scan (or materialise it); return the process exit code."""
+    from rich.style import Style
+    from rich.text import Text
+
+    from ecdat.services.paths import home_dir
+    from ecdat.ui.console import make_console
+    from ecdat.ui.theme import PALETTE
+
+    no_color = True if getattr(args, "no_color", False) else None
+    out_console = make_console(no_color=no_color)
+    err_console = make_console(stderr=True, no_color=no_color)
+
+    if getattr(args, "path", False):
+        from ecdat.services.demo import materialize_demo
+
+        destination = materialize_demo(home_dir() / "demo")
+        sys.stdout.write(str(destination) + "\n")
+        return 0
+
+    from ecdat.services.demo import demo_project
+    from ecdat.services.scanner import classify_target, perform_scan
+
+    with demo_project() as path:
+        target = classify_target(str(path))
+        outcome = perform_scan(target, label=_LABEL)
+        result = outcome.result
+        vm = outcome.vm
+
+        output_format = getattr(args, "format", "pretty")
+        if output_format == "json":
+            _emit_json(result.model_dump(mode="json"))
+        elif output_format == "summary":
+            from ecdat_core.cbom_export import export_summary
+
+            _emit_json(export_summary(result))
+        else:
+            _render_pretty(out_console, vm, limit=getattr(args, "limit", 15))
+
+    err_console.print(Text(_PRETTY_NOTE, style=Style(color=PALETTE.muted, dim=True)))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+
+def _emit_json(payload: dict) -> None:
+    """Write *payload* as pretty JSON to stdout — the ONLY thing on stdout."""
+    sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+
+
+def _render_pretty(console, vm, *, limit: int) -> None:
+    """Render the banner plus the standard scan report to stdout."""
+    from ecdat import __version__
+    from ecdat.ui.banner import render_banner
+    from ecdat.ui.render import scan_report
+
+    console.print(render_banner(version=__version__))
+    console.print(scan_report(vm, limit=limit))