cyberfw 2.0.0__py3-none-any.whl

cyberfw/__init__.py

@@ -0,0 +1,21 @@
+"""cyberfw — Integrated Cybersecurity Framework.
+
+A console orchestrator for offensive-security tools with the "Zero-Friction
+Installation" paradigm: every external binary is fetched precompiled from
+GitHub Releases, so the user only needs Python, Git and curl/wget.
+
+Everything is reachable through the ``cyberfw`` CLI (see :mod:`cyberfw.cli`).
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "2.0.0"
+
+# A library's records go where its caller's logging sends them: the CLI sets up
+# its handlers, a script that sets up none gets nothing — not Python's
+# last-resort handler printing warnings to stderr.
+logging.getLogger("cyberfw").addHandler(logging.NullHandler())
+
+__all__ = ["__version__"]

cyberfw/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m cyberfw` — the same app as the `cyberfw` command."""
+
+from cyberfw.cli import app
+
+app()

cyberfw/api.py

@@ -0,0 +1,426 @@
+"""cyberfw's Python API: run a pipeline or one tool, plan a pipeline, read and compare saved runs.
+
+Stable within a major version: the functions, types and errors in ``__all__``.
+``cyberfw.core`` and ``cyberfw.cli`` are internal. Nothing here prints, prompts
+or calls ``sys.exit``: results come back as data, progress goes to an optional
+:class:`RunObserver`, and logging is the caller's to set up. The calls are
+synchronous and run their own event loop — call them from plain code, not from
+inside a running asyncio loop.
+
+Example::
+
+    from cyberfw import api
+
+    outcome = api.run_pipeline("recon-to-vuln", "example.com", save=False)
+    print(outcome.succeeded, len(outcome.result.records), outcome.exit_code())
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from cyberfw.config import Settings, load_settings
+from cyberfw.core.events import (
+    MailSummary,
+    Note,
+    RunObserver,
+    StepEvent,
+    StepName,
+    StepSummary,
+    Stream,
+    TakeoverSummary,
+    TlsSummary,
+    VtSummary,
+)
+from cyberfw.core.finish import finalize, run_info
+from cyberfw.core.scan import (
+    Blocker,
+    Plan,
+    PlanStage,
+    choose_wordlist,
+    execute_pipeline,
+    plan_of,
+    prepare_pipeline,
+)
+from cyberfw.core.sessions import checked_session, open_session
+from cyberfw.core.steps import post_scan
+from cyberfw.core.tool_run import check_tool, keep_tool_run, run_tool_once
+from cyberfw.core.workspace import open_manager
+from cyberfw.exceptions import (
+    CyberfwError,
+    PreflightError,
+    RegistryError,
+    ReportError,
+    ToolNotFoundError,
+)
+from cyberfw.manager.plugins import PluginInfo, load_plugins
+from cyberfw.pipeline.engine import NodeResult, PipelineResult, StageEvent
+from cyberfw.pipeline.schemas import ToolRecord
+from cyberfw.report import diff as rundiff
+from cyberfw.report.csv_report import to_csv
+from cyberfw.report.diff import RunDiff
+from cyberfw.report.run_info import RunInfo
+from cyberfw.report.sarif import to_sarif
+from cyberfw.threatintel import IntelSummary
+
+__all__ = [
+    "Blocker",
+    "CyberfwError",
+    "IntelSummary",
+    "MailSummary",
+    "NodeResult",
+    "Note",
+    "PipelineResult",
+    "Plan",
+    "PlanStage",
+    "PluginInfo",
+    "PreflightError",
+    "RegistryError",
+    "ReportError",
+    "RunDiff",
+    "RunInfo",
+    "RunObserver",
+    "RunOutcome",
+    "SavedRun",
+    "Settings",
+    "StageEvent",
+    "StepEvent",
+    "StepName",
+    "StepSummary",
+    "Stream",
+    "TakeoverSummary",
+    "TlsSummary",
+    "ToolNotFoundError",
+    "ToolRecord",
+    "VtSummary",
+    "compare_runs",
+    "export_csv",
+    "export_sarif",
+    "list_plugins",
+    "load_run",
+    "plan_pipeline",
+    "run_pipeline",
+    "run_tool",
+]
+
+
+@dataclass
+class RunOutcome:
+    """What a run produced: its result, its facts, where it was kept, what changed."""
+
+    #: The stages, their records and timing; hosts kept out of scope in ``excluded``.
+    result: PipelineResult
+    run: RunInfo
+    session_id: str
+    session_dir: Path
+    #: The reports written, by format (``json``, ``html``); empty when the run was not saved.
+    reports: dict[str, Path]
+    #: What changed since the earlier run it was compared with, if it was.
+    changes: RunDiff | None
+    #: Every note the run sent, in order.
+    notes: list[Note] = field(default_factory=list)
+
+    @property
+    def succeeded(self) -> bool:
+        """Every stage ran and finished cleanly."""
+        return self.result.succeeded()
+
+    def alert_hits(self, severity: str = "low") -> int:
+        """New findings at ``severity`` or worse since the earlier run; 0 without a comparison."""
+        _check_severity(severity)
+        return self.changes.new_findings_at_least(severity) if self.changes is not None else 0
+
+    def exit_code(self, alert_severity: str | None = None) -> int:
+        """The CLI's exit code for this run: 1 when it failed — a broken scan is
+        reported as broken, never as "nothing new" — 3 when ``alert_severity`` is
+        given and there are new findings at it or worse, else 0."""
+        if not self.succeeded:
+            return 1
+        if alert_severity is not None and self.alert_hits(alert_severity):
+            return 3
+        return 0
+
+
+@dataclass(frozen=True)
+class SavedRun:
+    """A saved run: its ``report.json`` and what it holds."""
+
+    path: Path
+    payload: dict[str, Any]
+
+
+def _check_list(name: str, values: Sequence[str] | None) -> None:
+    # A bare str is a Sequence[str] too, of one-character items: as `exclude` its "*"
+    # would take every host out of scope, as `inputs` it would scan single letters.
+    if isinstance(values, str):
+        raise TypeError(f"{name} takes a list of strings, e.g. [{values!r}], not a bare str")
+
+
+def _check_severity(severity: str) -> None:
+    if severity not in rundiff.REAL:
+        raise ValueError(f"severity must be one of {', '.join(rundiff.REAL)}, got {severity!r}")
+
+
+def _scan_control_overrides(
+    *, severity: str, tags: str, rate_limit: int | None, exclude: list[str]
+) -> dict[str, object]:
+    """The ``Settings`` fields to override for this run — only the controls the
+    caller actually set, so an unset flag leaves the env/YAML/default in place."""
+    overrides: dict[str, object] = {}
+    if severity:
+        overrides["severity"] = severity
+    if tags:
+        overrides["tags"] = tags
+    if rate_limit is not None:
+        overrides["rate_limit"] = rate_limit
+    if exclude:
+        overrides["exclude"] = exclude
+    return overrides
+
+
+def _settings(
+    settings: Settings | None,
+    *,
+    severity: str = "",
+    tags: str = "",
+    rate_limit: int | None = None,
+    exclude: Sequence[str] = (),
+) -> Settings:
+    """The settings for one call: as given, else loaded the way the CLI loads them;
+    the scan controls the caller set override them for this call only, checked as
+    the settings check them (a rate limit below 1 is a :class:`ValueError`)."""
+    _check_list("exclude", exclude)
+    settings = settings if settings is not None else load_settings()
+    overrides = _scan_control_overrides(severity=severity, tags=tags, rate_limit=rate_limit, exclude=list(exclude))
+    if overrides:
+        settings = settings.model_copy()
+        for key, value in overrides.items():
+            setattr(settings, key, value)  # Settings validates every assignment
+    settings.ensure_dirs()
+    return settings
+
+
+class _Relay(RunObserver):
+    """Passes every event on to the caller's observer and keeps the notes for the outcome."""
+
+    def __init__(self, observer: RunObserver | None) -> None:
+        self._observer = observer if observer is not None else RunObserver()
+        self.notes: list[Note] = []
+
+    def on_plan(self, plan: Plan) -> None:
+        self._observer.on_plan(plan)
+
+    def on_stage(self, event: StageEvent) -> None:
+        self._observer.on_stage(event)
+
+    def on_record(self, record: ToolRecord) -> None:
+        self._observer.on_record(record)
+
+    def on_output(self, line: str, stream: Stream) -> None:
+        self._observer.on_output(line, stream)
+
+    def on_step(self, event: StepEvent) -> None:
+        self._observer.on_step(event)
+
+    def on_note(self, note: Note) -> None:
+        self.notes.append(note)
+        self._observer.on_note(note)
+
+
+def run_pipeline(
+    name: str,
+    target: str,
+    *,
+    settings: Settings | None = None,
+    ffuf: bool = False,
+    wordlist: str | None = None,
+    gowitness: bool | None = None,
+    max_httpx: int = 0,
+    severity: str = "",
+    tags: str = "",
+    rate_limit: int | None = None,
+    exclude: Sequence[str] = (),
+    mail: bool = True,
+    takeover: bool = True,
+    intel: bool = True,
+    vt_key: str | None = None,
+    vt_limit: int = 20,
+    baseline: str | None = None,
+    compare: bool = True,
+    session: str | None = None,
+    save: bool | Callable[[], bool] = True,
+    force_start: bool = False,
+    observer: RunObserver | None = None,
+) -> RunOutcome:
+    """Run a pipeline against ``target`` and finish it: the checks after the scan,
+    triage, the comparison with an earlier run, and the reports.
+
+    ``settings`` default to the CLI's (env, ``config.local.yaml``); ``severity``,
+    ``tags``, ``rate_limit`` and ``exclude`` override them for this call only.
+    VirusTotal runs only with ``vt_key`` — the API never looks for a key or asks.
+    ``baseline`` names the earlier run to compare with (else the newest of the same
+    pipeline and seed); ``compare=False`` skips the comparison. ``save`` keeps the
+    reports; a callable is asked after the comparison, before anything is written.
+    A session this call made is removed when the run is not saved.
+
+    Raises :class:`ValueError` (no target; a session that is not a plain name; a
+    rate limit below 1), :class:`TypeError` (``exclude`` as one bare str),
+    :class:`RegistryError` (an unknown pipeline, or a tool it names),
+    :class:`PreflightError` (stages cannot run and ``force_start`` is not set),
+    :class:`ReportError` (the reports cannot be written) and
+    :class:`CyberfwError` (the engine itself failed).
+    """
+    if not target:
+        raise ValueError("a pipeline needs a target")
+    if session:
+        checked_session(session)
+    settings = _settings(settings, severity=severity, tags=tags, rate_limit=rate_limit, exclude=exclude)
+    relay = _Relay(observer)
+    manager = open_manager(settings)
+    try:
+        prepared = prepare_pipeline(
+            name, target, settings=settings, manager=manager, ffuf=ffuf, gowitness=gowitness, max_httpx=max_httpx
+        )
+        relay.on_plan(plan_of(prepared))
+        for warning in prepared.warnings:
+            relay.on_note(Note("warn", warning))
+        if prepared.blocking and not force_start:
+            raise PreflightError(prepared.blocking)
+        chosen = choose_wordlist(settings, wordlist, ffuf=ffuf, observer=relay)
+        run_session = open_session(settings.reports_dir, kind="pipeline", name=name, session=session, stream=True)
+    except BaseException:
+        manager.close()
+        raise
+    try:
+        result = execute_pipeline(prepared, session=run_session, wordlist=chosen, observer=relay)
+        post_scan(
+            result, seed=target, settings=settings, mail=mail, takeover=takeover, intel=intel,
+            vt_key=vt_key, vt_limit=vt_limit, observer=relay,
+        )
+        finished = finalize(
+            result, manager=manager, settings=settings, name=name, seed=target,
+            tools={node.tool for node in prepared.nodes}, session=run_session, compare=compare,
+            baseline=baseline, save=save, observer=relay,
+        )
+    except BaseException:
+        # The run never finished: release the records store (what streamed stays on disk).
+        if run_session.context is not None:
+            run_session.context.close()
+        raise
+    return RunOutcome(
+        result=result, run=finished.run, session_id=run_session.id, session_dir=run_session.dir,
+        reports=finished.reports, changes=finished.changes, notes=relay.notes,
+    )
+
+
+def plan_pipeline(
+    name: str,
+    target: str | None = None,
+    *,
+    settings: Settings | None = None,
+    ffuf: bool = False,
+    gowitness: bool | None = None,
+    max_httpx: int = 0,
+) -> Plan:
+    """What :func:`run_pipeline` would run, without running it: each stage, the
+    stage it reads, its tool's state, what blocks and what only weakens the run.
+    Raises :class:`RegistryError` for an unknown pipeline or a tool it names."""
+    settings = _settings(settings)
+    manager = open_manager(settings)
+    try:
+        return plan_of(prepare_pipeline(
+            name, target, settings=settings, manager=manager, ffuf=ffuf, gowitness=gowitness, max_httpx=max_httpx
+        ))
+    finally:
+        manager.close()
+
+
+def run_tool(
+    tool: str,
+    *,
+    target: str | None = None,
+    inputs: Sequence[str] | None = None,
+    wordlist: str | None = None,
+    settings: Settings | None = None,
+    severity: str = "",
+    tags: str = "",
+    rate_limit: int | None = None,
+    parse: bool = True,
+    session: str | None = None,
+    save: bool | Callable[[], bool] = False,
+    observer: RunObserver | None = None,
+) -> RunOutcome:
+    """Run one registered tool on its own against ``target`` and/or ``inputs`` (a
+    list of hosts). It needs one of them; an empty list leaves the tool nothing
+    to work on, so it finds nothing — what ``run --list <empty file>`` does. Without
+    ``parse`` every stdout line is a raw record. ``save=True`` streams the records
+    into ``reports/<session>/`` as they arrive and writes both reports; a callable
+    is asked after the run — only when it produced records — before anything is
+    written; ``False`` writes nothing.
+
+    Raises :class:`ValueError` (neither a target nor inputs; a target the tool
+    cannot take; a session that is not a plain name; a rate limit below 1),
+    :class:`TypeError` (``inputs`` as one bare str), :class:`RegistryError` (an
+    unknown tool) and :class:`ToolNotFoundError` (a tool that is not installed).
+    """
+    if not target and inputs is None:
+        raise ValueError("run_tool needs a target or inputs (a list of hosts)")
+    _check_list("inputs", inputs)
+    if session:
+        checked_session(session)
+    settings = _settings(settings, severity=severity, tags=tags, rate_limit=rate_limit)
+    relay = _Relay(observer)
+    manager = open_manager(settings)
+    try:
+        check_tool(manager, tool, target)
+    except BaseException:
+        manager.close()
+        raise
+    run_session = open_session(settings.reports_dir, kind="run", name=tool, session=session, stream=save is True)
+    ran = run_tool_once(
+        tool, settings=settings, manager=manager, target=target, inputs=inputs or (), wordlist=wordlist,
+        parse=parse, session=run_session, observer=relay,
+    )
+    keep = save if isinstance(save, bool) else bool(ran.records) and save()
+    reports = keep_tool_run(ran, settings=settings, manager=manager) if keep else {}
+    return RunOutcome(
+        result=ran.result,
+        run=run_info(manager, name=tool, seed=target, session_id=run_session.id, tools={tool}),
+        session_id=run_session.id, session_dir=run_session.dir, reports=reports, changes=None, notes=relay.notes,
+    )
+
+
+def load_run(ref: str | Path, *, settings: Settings | None = None) -> SavedRun:
+    """A saved run, by session id, its directory or its ``report.json`` (looked up
+    under ``reports/``). Raises :class:`FileNotFoundError` when there is none and
+    :class:`ValueError` when the file is not a cyberfw report."""
+    settings = settings if settings is not None else load_settings()
+    path = rundiff.resolve_report(str(ref), settings.reports_dir)
+    return SavedRun(path=path, payload=rundiff.load_report(path))
+
+
+def compare_runs(old: SavedRun, new: SavedRun) -> RunDiff:
+    """What changed from ``old`` to ``new``: findings, ports, subdomains, certificates, exploitation."""
+    return rundiff.compare(old.payload, new.payload)
+
+
+def export_sarif(run: SavedRun) -> dict[str, Any]:
+    """The run's findings as a SARIF 2.1.0 document (for CI / code scanning)."""
+    return to_sarif(run.payload)
+
+
+def export_csv(run: SavedRun) -> str:
+    """Every record of the run as CSV (for triage in a spreadsheet)."""
+    return to_csv(run.payload)
+
+
+def list_plugins(settings: Settings | None = None) -> list[PluginInfo]:
+    """Every plugin tool the installed packages declare — its package, version and
+    kind (``manifest`` / ``code``), its state and why, the extra environment
+    variables it asks for — and each package ``plugins.yaml`` enables that is missing.
+    Reads the packages' metadata; only enabled packages are loaded."""
+    settings = settings if settings is not None else load_settings()
+    return list(load_plugins(settings).infos)

cyberfw/cli/__init__.py

@@ -0,0 +1,28 @@
+"""Typer CLI — the public face of cyberfw.
+
+Three commands, matching the acceptance criteria in the technical specification:
+
+* ``cyberfw init [tools...]`` — fetch precompiled binaries into ``tools_bin/``
+  (zero-friction: only Python, Git and curl/wget are required of the user).
+* ``cyberfw run <tool> -t <target> (-l <hosts>)`` — run a single registered tool
+  through its adapter and stream validated JSONL records.
+* ``cyberfw pipeline <name> -t <domain>`` — run a ready-made pipeline
+  (e.g. ``recon-to-vuln``) and render HTML + JSON reports.
+
+A crashed/failed child never aborts the CLI: :class:`PipelineEngine` converts
+stage failures into a ``NodeResult`` and the command exits with a helpful status.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from cyberfw.cli.app import app
+
+# Importing the command modules registers their commands on `app` in this
+# order — the order `cyberfw --help` lists them. The launcher comes last: it
+# adds the callback that opens the menu when no command is given.
+for _module in ('tools', 'plugins', 'reports', 'triage', 'scan', 'schedule', 'launcher'):
+    importlib.import_module(f"cyberfw.cli.{_module}")
+
+__all__ = ["app"]

cyberfw/cli/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m cyberfw.cli` — the same app as the `cyberfw` command."""
+
+from cyberfw.cli import app
+
+app()

cyberfw/cli/app.py

@@ -0,0 +1,13 @@
+"""The Typer application every command module registers its commands on."""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="cyberfw",
+    help="Integrated Cybersecurity Framework — orchestrates precompiled offensive tools.",
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    add_completion=False,
+)

cyberfw/cli/common.py

@@ -0,0 +1,167 @@
+"""Plumbing the commands share: bootstrap, registry and lock paths, prompts, terminal and screen helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any, TextIO
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.prompt import Confirm as _RichConfirm
+from rich.prompt import Prompt as _RichPrompt
+from rich.text import Text, TextType
+
+from cyberfw import completion
+from cyberfw.config import Settings, load_settings
+from cyberfw.core.sessions import checked_session
+from cyberfw.core.workspace import open_manager, tool_state
+from cyberfw.logging import console, get_logger, setup_logging
+from cyberfw.manager import ToolManager
+
+LOG = get_logger("cli")
+
+
+class Prompt(_RichPrompt):
+    """Every question asked the same way: ``» Target (domain, URL or host):``.
+
+    Callers still pass the plain wording (it comes from the adapters), so a
+    test that patches ``cyberfw.cli.Prompt.ask`` sees exactly that wording.
+    Questions go to the app's console unless told otherwise: Rich's global
+    console has no theme, and the lead-in's style would quietly drop.
+    A question asked inside :func:`completion.offering` reads its answer with
+    Tab completion when a person is at the terminal.
+    """
+
+    def __init__(self, prompt: TextType = "", *, console: Console | None = None, **kwargs: Any) -> None:
+        super().__init__(prompt, console=console or _app_console(), **kwargs)
+
+    def make_prompt(self, default: Any) -> Text:
+        return Text.assemble(("» ", "accent"), super().make_prompt(default))
+
+    @classmethod
+    def get_input(cls, console: Console, prompt: TextType, password: bool, stream: TextIO | None = None) -> str:
+        options = completion.offered()
+        if options and not password and stream is None and completion.available(console):
+            return completion.read_line(console, prompt, options)
+        return super().get_input(console, prompt, password, stream=stream)
+
+
+class Confirm(_RichConfirm):
+    """A yes/no question with the same ``» `` lead-in as :class:`Prompt`."""
+
+    def __init__(self, prompt: TextType = "", *, console: Console | None = None, **kwargs: Any) -> None:
+        super().__init__(prompt, console=console or _app_console(), **kwargs)
+
+    def make_prompt(self, default: Any) -> Text:
+        return Text.assemble(("» ", "accent"), super().make_prompt(default))
+
+
+def _app_console() -> Console:
+    """The themed console, looked up at call time (tests swap it)."""
+    return console
+
+
+# -- shared plumbing ------------------------------------------------------------
+#: ``-v/--verbose`` — raise this run's log level to DEBUG so the resolve /
+#: download / extract steps are traced. Shared by init/status/run/pipeline.
+VerboseOption = Annotated[
+    bool,
+    typer.Option(
+        "--verbose",
+        "-v",
+        help="Trace what runs under the hood at DEBUG (release resolution, downloads, extraction).",
+    ),
+]
+
+
+def _setup(*, verbose: bool = False) -> Settings:
+    """Load the settings, make sure their directories exist, wire logging.
+
+    ``verbose`` forces this process's log level to DEBUG regardless of the
+    configured ``log_level``, so ``-v`` surfaces the install/download trace
+    without a permanent config change.
+    """
+    settings = load_settings()
+    if verbose and settings.log_level != "DEBUG":
+        settings = settings.model_copy(update={"log_level": "DEBUG"})
+    settings.ensure_dirs()
+    setup_logging(level=settings.log_level, log_dir=settings.logs_dir, log_to_file=settings.log_to_file)
+    return settings
+
+
+def _bootstrap(*, verbose: bool = False) -> tuple[Settings, ToolManager]:
+    """:func:`_setup`, and a tool manager over the registry in use."""
+    settings = _setup(verbose=verbose)
+    return settings, open_manager(settings)
+
+
+def _is_interactive() -> bool:
+    """True when there is a user at the keyboard to answer a prompt.
+
+    A pipe, a CI job or a `< /dev/null` run must never block on a question.
+    """
+    return bool(console.is_interactive)
+
+
+def _wants_to_save(decided: bool | None, *, default: bool, what: str) -> bool:
+    """Whether to keep this run's artefacts: the flag if given, else ask, else default."""
+    if decided is not None:
+        return decided
+    if not _is_interactive():
+        return default
+    return bool(Confirm.ask(f"Save the {what} report?", default=default))
+
+
+def _after_live() -> None:
+    """``Live`` leaves its last frame on screen; on a pipe that frame ends
+    without a newline, and the next line would be glued to its last row."""
+    if not console.is_terminal:
+        console.line()
+
+
+def _live_fps(settings: Settings) -> int:
+    """Redraws per second for a live view: smooth when animating, else just current."""
+    return 12 if settings.animations else 4
+
+
+def _checked_session(session: str) -> str:
+    """``--session`` as a plain directory name under ``reports/``, else a usage error (exit 2)."""
+    try:
+        return checked_session(session)
+    except ValueError:
+        console.print(f"[err]--session must be a plain directory name under reports/, got {escape(repr(session))}.[/err]")
+        raise typer.Exit(2) from None
+
+
+def _tool_version(manager: ToolManager, name: str) -> str:
+    return str((manager.install_state(name) or {}).get("version", ""))
+
+
+def _tool_states(manager: ToolManager, tools_dir: Path) -> list[str]:
+    """One state per registered tool, in registry order."""
+    return [tool_state(manager, name, tools_dir) for name in manager.registry.names()]
+
+
+def _clear_screen() -> None:
+    """Clear the screen *and* the scrollback, so nothing is left to scroll back to.
+
+    ``console.clear()`` erases only the visible screen (CSI 2J) and homes the
+    cursor; the frame that was there stays in the terminal's scrollback. CSI 3J
+    erases that too, so the launcher reopens on a truly blank screen. It is sent
+    only to a real terminal — the same gate Rich's own ``clear`` uses — so a
+    dumb terminal gets neither code; a pipe/CI never reaches here (callers guard
+    on :func:`_is_interactive`)."""
+    console.clear()
+    if console.is_terminal and not console.is_dumb_terminal:
+        console.file.write("\x1b[3J")
+        console.file.flush()
+
+
+def _fresh_screen() -> None:
+    """Title the window and clear it — only for a person at a terminal; a pipe,
+    a log or a test keeps its plain transcript."""
+    if not _is_interactive():
+        return
+    console.set_window_title("CS-TOOL")
+    _clear_screen()