madaramaster 5.0.0__py3-none-any.whl

madaramaster/__init__.py

@@ -0,0 +1,3 @@
+"""MadaraMaster — secure file sanitization (NIST SP 800-88 / DoD 5220.22-M)."""
+
+__version__ = "5.0.0"

madaramaster/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m madaramaster``."""
+
+from .cli import main
+
+main()

madaramaster/audit.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+# Log de auditoría forense — formato JSON Lines
+# jaimefg1888
+
+import getpass
+import json
+import logging
+import os
+import socket
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Generator, Optional
+
+
+def default_log_path() -> Path:
+    """Return the per-user default location of the audit log.
+
+    The log records file names, so it is kept out of the working directory
+    (which may be the very directory being wiped) and in a private
+    per-user location instead:
+
+    * Linux/BSD: ``$XDG_STATE_HOME/madaramaster/audit.jsonl``
+      (default ``~/.local/state/madaramaster/audit.jsonl``)
+    * macOS: ``~/Library/Logs/MadaraMaster/audit.jsonl``
+    * Windows: ``%LOCALAPPDATA%\\MadaraMaster\\audit.jsonl``
+    """
+    home = Path.home()
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or home / "AppData" / "Local")
+        return base / "MadaraMaster" / "audit.jsonl"
+    if sys.platform == "darwin":
+        return home / "Library" / "Logs" / "MadaraMaster" / "audit.jsonl"
+    base = Path(os.environ.get("XDG_STATE_HOME") or home / ".local" / "state")
+    return base / "madaramaster" / "audit.jsonl"
+
+
+def _safe_username() -> str:
+    """Return the current username without raising in daemon / Docker environments.
+
+    ``os.getlogin()`` raises ``OSError`` when there is no controlling
+    terminal (typical in Docker, CI pipelines, or systemd services).
+    The function falls back to ``getpass.getuser()`` and finally to
+    well-known environment variables.
+    """
+    try:
+        return os.getlogin()
+    except OSError:
+        pass
+    try:
+        return getpass.getuser()
+    except Exception:
+        pass
+    return os.environ.get("USER", os.environ.get("USERNAME", "unknown"))
+
+
+class AuditLogger:
+    """Append-only forensic audit logger that writes JSON Lines records.
+
+    Each call to :meth:`log_wipe_operation` appends a single JSON object
+    terminated by a newline to the configured log file.  Reading is done
+    lazily via :meth:`get_logs` to avoid loading the entire file into RAM.
+
+    The file and its directory are created on first write with owner-only
+    permissions (``0600`` / ``0700`` on POSIX).
+
+    Args:
+        log_path: Destination file for the audit log.  Defaults to
+            :func:`default_log_path`.
+    """
+
+    def __init__(self, log_path: Optional[Path] = None) -> None:
+        self.log_path = Path(log_path) if log_path is not None else default_log_path()
+
+    def _append(self, line: str) -> None:
+        self.log_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        fd = os.open(self.log_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a", encoding="utf-8") as f:
+            f.write(line)
+
+    def log_wipe_operation(
+        self,
+        file_path: Path,
+        file_size: int,
+        sha256_before: Optional[str],
+        standard_used: str,
+        result: dict[str, Any],
+    ) -> None:
+        """Append one JSON record describing a completed wipe operation.
+
+        Args:
+            file_path: Absolute path of the file that was wiped.
+            file_size: Size of the file in bytes, captured before wiping.
+            sha256_before: Hex-encoded SHA-256 digest of the file contents
+                before the wipe started, or ``None`` when hashing was not
+                requested (``--hash``).  The digest lets anyone who has the
+                log confirm what the file contained, so it is opt-in.
+            standard_used: Sanitization standard identifier (e.g. ``"clear"``).
+            result: Dictionary returned by the wipe engine.  Expected keys:
+                ``passes_completed``, ``verified``, ``duration``,
+                ``success``, ``error``, ``strategy``.
+        """
+        try:
+            record: dict[str, Any] = {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "file": str(file_path.absolute()),
+                "size_bytes": file_size,
+                "sha256_before": sha256_before,
+                "standard": standard_used,
+                "passes": result.get("passes_completed", 0),
+                "verified": result.get("verified", False),
+                "duration_sec": result.get("duration", 0.0),
+                "user": _safe_username(),
+                "hostname": socket.gethostname(),
+                "success": result.get("success", False),
+                "error": result.get("error"),
+                "strategy": result.get("strategy", "Unknown"),
+                "final_path": result.get("final_path"),
+            }
+            self._append(json.dumps(record) + "\n")
+        except Exception as exc:
+            logging.error("Could not write to the audit log: %s", exc)
+
+    def get_logs(self) -> Generator[dict[str, Any], None, None]:
+        """Yield parsed log records one at a time.
+
+        Reads the log file lazily so arbitrarily large audit logs can be
+        processed without exhausting available memory.
+
+        Yields:
+            One dictionary per valid JSON line in the log file.
+        """
+        if not self.log_path.exists():
+            return
+        with open(self.log_path, "r", encoding="utf-8") as f:
+            for line in f:
+                try:
+                    yield json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+
+class NullAuditLogger(AuditLogger):
+    """Audit logger that records nothing (``--no-log``)."""
+
+    def __init__(self) -> None:
+        self.log_path = None  # type: ignore[assignment]
+
+    def log_wipe_operation(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+    def get_logs(self) -> Generator[dict[str, Any], None, None]:
+        return
+        yield

madaramaster/cli.py

@@ -0,0 +1,118 @@
+"""MadaraMaster command-line interface.
+
+Secure file sanitization with a live dashboard.  Bilingual (EN/ES).
+
+Usage::
+
+    madara                              # interactive session
+    madara wipe <PATH>                  # wipe a file or directory
+    madara wipe <PATH> --dry-run        # preview without touching anything
+    madara wipe-free-space <DIR>        # overwrite the free space of a filesystem
+    madara --lang es wipe <PATH>        # Spanish interface (or MADARA_LANG=es)
+
+``python -m madaramaster`` and ``python madara.py`` are equivalent.
+
+The implementation is split by responsibility; this module is the stable
+entry point (``madaramaster.cli:main``) and re-exports the names it used
+to define:
+
+* :mod:`madaramaster.i18n` — translations and the active language
+* :mod:`madaramaster.ui` — console, banner, prompts, summary, dashboard
+* :mod:`madaramaster.runner` — shared wipe flow used by every front end
+* :mod:`madaramaster.free_space` — free-space fill engine
+* :mod:`madaramaster.interactive` — interactive session
+* :mod:`madaramaster.commands` — Typer application and commands
+"""
+
+from .audit import default_log_path
+from .commands import (
+    Language,
+    Standard,
+    _context_menu_command,
+    _ensure_utf8_output,
+    _global_options,
+    app,
+    install_context_menu,
+    main,
+    version,
+    wipe,
+    wipe_free_space_cmd,
+)
+from .free_space import (
+    _FILL_CHUNK_LARGE,
+    _FILL_CHUNK_SMALL,
+    _ZEROS_LARGE,
+    _ZEROS_SMALL,
+    _async_wipe_free_space,
+)
+from .i18n import CONFIRM_YES, EXIT_KEYWORDS, LANG, T
+from .interactive import (
+    _confirm_interactive,
+    _parse_input_line,
+    _print_file_preview,
+    _print_session_hints,
+    _strip_quotes,
+    _target_size,
+    interactive_session,
+)
+from .runner import _FLASH_TYPES, _expand_targets, _remove_empty_dirs, async_wipe_logic
+from .trim import send_trim
+from .ui import (
+    BANNER,
+    SpeedTracker,
+    _build_dashboard,
+    _lsize,
+    _print_residue_warning,
+    confirm_action,
+    print_banner,
+    print_summary,
+    select_language,
+)
+
+__all__ = [
+    "BANNER",
+    "CONFIRM_YES",
+    "EXIT_KEYWORDS",
+    "LANG",
+    "Language",
+    "SpeedTracker",
+    "Standard",
+    "T",
+    "_FILL_CHUNK_LARGE",
+    "_FILL_CHUNK_SMALL",
+    "_FLASH_TYPES",
+    "_ZEROS_LARGE",
+    "_ZEROS_SMALL",
+    "_async_wipe_free_space",
+    "_build_dashboard",
+    "_confirm_interactive",
+    "_context_menu_command",
+    "_ensure_utf8_output",
+    "_expand_targets",
+    "_global_options",
+    "_lsize",
+    "_parse_input_line",
+    "_print_file_preview",
+    "_print_residue_warning",
+    "_print_session_hints",
+    "_remove_empty_dirs",
+    "_strip_quotes",
+    "_target_size",
+    "app",
+    "async_wipe_logic",
+    "confirm_action",
+    "default_log_path",
+    "install_context_menu",
+    "interactive_session",
+    "main",
+    "print_banner",
+    "print_summary",
+    "select_language",
+    "send_trim",
+    "version",
+    "wipe",
+    "wipe_free_space_cmd",
+]
+
+if __name__ == "__main__":
+    main()