mxready 1.0.0__py3-none-any.whl

mxready/cli/scan_repository.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from uuid import NAMESPACE_URL, uuid5
+
+from mxready.config import Settings
+from mxready.errors import MxReadyError
+from mxready.models import ScanReport
+from mxready.reporting.badge import render_badge
+from mxready.reporting.comparison import new_blockers
+from mxready.reporting.markdown import render_markdown
+from mxready.reporting.sarif import render_sarif
+from mxready.reporting.terminal import render_terminal_summary
+from mxready.repository.identity import parse_repository_url
+from mxready.scanning.analyzer import ScanAnalyzer
+from mxready.scanning.rule_loader import load_rule_catalog
+
+_COMMIT_PATTERN = re.compile(r"^[0-9a-f]{40}$")
+_SCP_LIKE_REMOTE = re.compile(
+    r"^(?:[^@/:]+@)?(?P<host>[A-Za-z0-9._-]*\.[A-Za-z0-9-]+):(?P<path>[A-Za-z0-9._~/-]+)$"
+)
+_SSH_URL_REMOTE = re.compile(
+    r"^ssh://(?:[^@/]+@)?(?P<host>[A-Za-z0-9._-]+)/(?P<path>[A-Za-z0-9._~/-]+)$"
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = _build_parser().parse_args(argv)
+    try:
+        repository_root = _local_repository(arguments.local_path)
+        commit = _commit_sha(arguments.commit or _detect_commit(repository_root))
+        identity = parse_repository_url(
+            arguments.repo_url or _detect_repository_url(repository_root)
+        )
+        settings = Settings.from_env()
+        report = ScanAnalyzer(
+            load_rule_catalog(
+                settings.rules_dir,
+                extra_directory=settings.extra_rules_dir,
+            ),
+            enable_prefilter=settings.prefilter_enabled,
+        ).analyze(
+            repository_root,
+            repository_url=identity.clone_url,
+            commit=commit,
+            scan_id=uuid5(NAMESPACE_URL, f"{identity.clone_url}@{commit}"),
+            stage_callback=lambda status: None,
+        )
+        output_dir = Path(arguments.output)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        stem = f"{identity.name}-{commit[:12]}"
+        _write_outputs(output_dir, stem, report)
+        blockers = [f for f in report.findings if f.severity.value == "blocker"]
+        if arguments.fail_on == "new-blockers":
+            if arguments.baseline is None:
+                raise ValueError("--baseline is required with --fail-on new-blockers")
+            baseline_path = Path(arguments.baseline)
+            if baseline_path.stat().st_size > 20 * 1024 * 1024:
+                raise ValueError("Baseline exceeds 20 MiB")
+            baseline = ScanReport.model_validate_json(baseline_path.read_bytes())
+            blockers = new_blockers(baseline, report)
+            print(f"New or increased blocker groups: {len(blockers)}")
+        elif arguments.baseline is not None:
+            raise ValueError("--baseline requires --fail-on new-blockers")
+    except (MxReadyError, OSError, ValueError) as error:
+        print(f"MXReady scan error: {error}", file=sys.stderr)
+        return 1
+
+    print(
+        _terminal_summary(
+            report, output_note=f"{stem}.json / {stem}.md / {stem}.svg / {stem}.sarif"
+        )
+    )
+    return 2 if blockers else 0
+
+
+def _terminal_summary(report: ScanReport, *, output_note: str) -> str:
+    """按标准输出编码选取摘要语言；旧代码页无法编码中文时回退纯 ASCII。"""
+    summary = render_terminal_summary(report, output_note=output_note)
+    if _can_encode(summary):
+        return summary
+    summary = render_terminal_summary(report, output_note=output_note, english=True)
+    if _can_encode(summary):
+        return summary
+    encoding = getattr(sys.stdout, "encoding", None) or "ascii"
+    return summary.encode(encoding, errors="backslashreplace").decode(encoding)
+
+
+def _can_encode(text: str) -> bool:
+    encoding = getattr(sys.stdout, "encoding", None)
+    if not encoding:
+        return True
+    try:
+        text.encode(encoding)
+    except (LookupError, UnicodeEncodeError):
+        return False
+    return True
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mxready-scan",
+        description="Generate MXReady reports from a trusted local source directory.",
+    )
+    parser.add_argument("local_path", help="Local repository directory to inspect")
+    parser.add_argument(
+        "--repo-url",
+        help="Canonical public GitHub/Gitee URL; defaults to the local origin remote",
+    )
+    parser.add_argument(
+        "--commit",
+        help="Resolved 40-character Git commit SHA; defaults to the local HEAD",
+    )
+    parser.add_argument(
+        "--output", required=True, help="Directory for JSON, Markdown, SVG, and SARIF"
+    )
+    parser.add_argument("--baseline", type=Path, help="Trusted baseline report JSON")
+    parser.add_argument(
+        "--fail-on", choices=("all-blockers", "new-blockers"), default="all-blockers"
+    )
+    return parser
+
+
+def _local_repository(value: str) -> Path:
+    path = Path(value)
+    if not path.exists():
+        raise ValueError(f"Local repository directory does not exist: {path}")
+    if not path.is_dir():
+        raise ValueError(f"Local repository path is not a directory: {path}")
+    return path.resolve()
+
+
+def _commit_sha(value: str) -> str:
+    if not _COMMIT_PATTERN.fullmatch(value):
+        raise ValueError("Commit must be a 40-character lowercase hexadecimal SHA.")
+    return value
+
+
+def _run_git(repository_root: Path, *arguments: str) -> str:
+    """在只读模式下询问本地仓库；git 不可用或命令失败时返回空字符串。"""
+    try:
+        completed = subprocess.run(
+            ("git", "-C", str(repository_root), *arguments),
+            capture_output=True,
+            check=False,
+            encoding="utf-8",
+            errors="replace",
+            shell=False,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return completed.stdout.strip() if completed.returncode == 0 else ""
+
+
+def _detect_commit(repository_root: Path) -> str:
+    commit = _run_git(repository_root, "rev-parse", "HEAD")
+    if not commit:
+        raise ValueError(
+            "Cannot resolve the local HEAD (git rev-parse HEAD failed); "
+            "pass --commit with a 40-character commit SHA."
+        )
+    return commit
+
+
+def _detect_repository_url(repository_root: Path) -> str:
+    remote = _run_git(repository_root, "remote", "get-url", "origin")
+    normalized = _normalize_remote_url(remote)
+    if not normalized.startswith("https://"):
+        raise ValueError(
+            "Cannot resolve a public origin remote (git remote get-url origin failed); "
+            "pass --repo-url with a GitHub/Gitee HTTPS URL."
+        )
+    return normalized
+
+
+def _normalize_remote_url(value: str) -> str:
+    """把 SSH 形式的 origin 地址转成 parse_repository_url 接受的 HTTPS 形式。"""
+    candidate = value.strip()
+    if "://" in candidate:
+        match = _SSH_URL_REMOTE.fullmatch(candidate) if candidate.startswith("ssh://") else None
+    else:
+        match = _SCP_LIKE_REMOTE.fullmatch(candidate)
+    if match is None:
+        return candidate
+    return f"https://{match.group('host')}/{match.group('path')}"
+
+
+def _write_outputs(output_dir: Path, stem: str, report: ScanReport) -> None:
+    (output_dir / f"{stem}.sarif").write_text(render_sarif(report), encoding="utf-8")
+    (output_dir / f"{stem}.json").write_text(
+        report.model_dump_json(indent=2) + "\n",
+        encoding="utf-8",
+    )
+    (output_dir / f"{stem}.md").write_text(
+        render_markdown(report),
+        encoding="utf-8",
+    )
+    (output_dir / f"{stem}.svg").write_text(
+        render_badge(report),
+        encoding="utf-8",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mxready/cli/serve.py

@@ -0,0 +1,55 @@
+"""Start the installed Web application with persistent per-user data."""
+
+import argparse
+import os
+import shutil
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+import uvicorn
+
+from mxready.app import create_app
+from mxready.config import Settings
+
+
+def default_data_directory() -> Path:
+    if sys.platform == "win32":
+        return Path(os.getenv("LOCALAPPDATA", str(Path.home() / "AppData" / "Local"))) / "MXReady"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "MXReady"
+    return Path(os.getenv("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))) / "mxready"
+
+
+def _port(value: str) -> int:
+    number = int(value)
+    if not 1 <= number <= 65535:
+        raise argparse.ArgumentTypeError("Port must be between 1 and 65535")
+    return number
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=_port, default=8000)
+    parser.add_argument("--data-dir", type=Path)
+    args = parser.parse_args(argv)
+    if not shutil.which("git"):
+        print(
+            "Git is required. Install Git and add it to PATH before starting MXReady.",
+            file=sys.stderr,
+        )
+        return 1
+    settings = Settings.from_env()
+    data_dir = args.data_dir or Path(os.getenv("MXREADY_DATA_DIR", str(default_data_directory())))
+    settings = replace(
+        settings,
+        data_dir=data_dir,
+        temp_dir=Path(os.getenv("MXREADY_TEMP_DIR", str(data_dir / "tmp"))),
+    )
+    uvicorn.run(create_app(settings), host=args.host, port=args.port)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mxready/config.py

@@ -0,0 +1,117 @@
+"""应用配置：默认值 + 环境变量注入（12-factor）。
+
+所有可配置项均支持通过 `MXREADY_*` 环境变量覆盖，未设置时使用内置默认值。
+参见仓库根目录 `.env.example` 与 `docs/deployment.md`。
+"""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from mxready.resources import default_frontend_directory, default_rules_directory
+
+_ENV_PREFIX = "MXREADY_"
+
+
+def _path_env(name: str, default: str) -> Path:
+    return Path(os.getenv(_ENV_PREFIX + name, default))
+
+
+def _optional_path_env(name: str) -> Path | None:
+    raw = os.getenv(_ENV_PREFIX + name)
+    if raw is None or not raw.strip():
+        return None
+    return Path(raw.strip())
+
+
+def _int_env(name: str, default: int) -> int:
+    try:
+        return int(os.getenv(_ENV_PREFIX + name, str(default)))
+    except ValueError:
+        return default
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    raw = os.getenv(_ENV_PREFIX + name)
+    if raw is None:
+        return default
+    return raw.strip().casefold() in {"1", "true", "yes", "on"}
+
+
+def _hosts_env(name: str, default: tuple[str, ...]) -> tuple[str, ...]:
+    raw = os.getenv(_ENV_PREFIX + name)
+    if raw is None or not raw.strip():
+        return default
+    return tuple(host.strip() for host in raw.split(",") if host.strip())
+
+
+# 预过滤开关的合法取值：auto 为默认启用，off 为应急止血（回退全量扫描，
+# 结果集完全不变，只影响耗时）。
+_PREFILTER_MODES = ("auto", "off")
+
+
+def _prefilter_mode_env(name: str, default: str = "auto") -> str:
+    """取值非法时回退默认值：拼错不该让服务起不来，也不该静默关掉优化。"""
+    raw = os.getenv(_ENV_PREFIX + name)
+    if raw is None or not raw.strip():
+        return default
+    mode = raw.strip().casefold()
+    return mode if mode in _PREFILTER_MODES else default
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    # 路径
+    data_dir: Path = Path("data")
+    rules_dir: Path = default_rules_directory()
+    extra_rules_dir: Path | None = None
+    temp_dir: Path = Path("data/tmp")
+    frontend_dist: Path = field(default_factory=default_frontend_directory)
+    # 日志
+    log_level: str = "INFO"
+    # 托管平台白名单（保持安全默认值）
+    allowed_hosts: tuple[str, ...] = ("github.com", "gitee.com")
+    # 数据保留（0 = 不自动清理，默认关闭以保护申报证据）
+    scan_retention_days: int = 0
+    # 防护（默认关闭限流，公网部署时按需开启）
+    rate_limit_enabled: bool = False
+    rate_limit_per_minute: int = 20
+    max_concurrent_scans: int = 2
+    max_request_bytes: int = 1_048_576
+    scan_worker_threads: int = 2
+    task_lease_seconds: int = 120
+    # 规则正则的必需字面量预过滤：auto 启用；off 关闭（应急止血，结论不变）
+    prefilter_mode: str = "auto"
+
+    def __post_init__(self) -> None:
+        if self.scan_worker_threads < 1 or self.task_lease_seconds < 3:
+            raise ValueError("Worker threads must be positive and task leases at least 3 seconds")
+        if self.max_concurrent_scans < 0 or self.max_request_bytes < 1:
+            raise ValueError("Invalid scan concurrency or request size limit")
+        if self.prefilter_mode not in _PREFILTER_MODES:
+            raise ValueError("prefilter_mode must be 'auto' or 'off'")
+
+    @property
+    def prefilter_enabled(self) -> bool:
+        return self.prefilter_mode != "off"
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        """读取 `MXREADY_*` 环境变量构造配置，未设置项使用默认值。"""
+        return cls(
+            data_dir=_path_env("DATA_DIR", "data"),
+            rules_dir=_path_env("RULES_DIR", str(default_rules_directory())),
+            extra_rules_dir=_optional_path_env("EXTRA_RULES_DIR"),
+            temp_dir=_path_env("TEMP_DIR", "data/tmp"),
+            frontend_dist=_path_env("FRONTEND_DIR", str(default_frontend_directory())),
+            log_level=os.getenv(_ENV_PREFIX + "LOG_LEVEL", "INFO"),
+            allowed_hosts=_hosts_env("ALLOWED_HOSTS", ("github.com", "gitee.com")),
+            scan_retention_days=_int_env("SCAN_RETENTION_DAYS", 0),
+            rate_limit_enabled=_bool_env("RATE_LIMIT_ENABLED", False),
+            rate_limit_per_minute=_int_env("RATE_LIMIT_PER_MINUTE", 20),
+            max_concurrent_scans=_int_env("MAX_CONCURRENT_SCANS", 2),
+            max_request_bytes=_int_env("MAX_REQUEST_BYTES", 1_048_576),
+            scan_worker_threads=_int_env("SCAN_WORKER_THREADS", 2),
+            task_lease_seconds=_int_env("TASK_LEASE_SECONDS", 120),
+            prefilter_mode=_prefilter_mode_env("PREFILTER_MODE"),
+        )

mxready/errors.py

@@ -0,0 +1,11 @@
+class MxReadyError(Exception):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or {}

mxready/logging_setup.py

@@ -0,0 +1,88 @@
+"""统一日志配置：JSON 结构化输出 + 敏感信息脱敏。
+
+只配置 `mxready` 命名空间的 logger；uvicorn 自身与访问日志保持默认，
+避免重复输出与格式不一致。脱敏规则与 `src/mxready_runner/redact.py` 对齐。
+"""
+
+import json
+import logging
+import re
+import sys
+from datetime import UTC, datetime
+from typing import Any, Final
+
+_LOGGER_NAME: Final = "mxready"
+
+# stdlib LogRecord 自带的属性不进 JSON 字段
+_SKIP_ATTRS: Final = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "taskName",
+        "message",
+        "asctime",
+    }
+)
+
+_URL_CREDENTIALS = re.compile(r"(://[^/@\s:]+):([^/@\s]+)@")
+_SENSITIVE_NAME = r"[A-Z0-9_]*(?:TOKEN|PASSWORD|SECRET|KEY|AUTHORIZATION)"
+_ASSIGNMENT = re.compile(rf"(?i)(\b{_SENSITIVE_NAME}\b\s*[:=]\s*)([^\s,;]+)")
+_UNIX_HOME = re.compile(r"(?i)(/(?:home|Users)/)[^/\s]+")
+_WINDOWS_HOME = re.compile(r"(?i)([A-Z]:\\Users\\)[^\\\s]+")
+_TOKEN_PREFIX = re.compile(r"(?i)\b(?:ghp|gho|ghu|glpat|github_pat|hf_)[A-Za-z0-9_\-]{6,}")
+
+
+def _redact_message(message: str) -> str:
+    redacted = _URL_CREDENTIALS.sub(r"\1:***@", message)
+    redacted = _ASSIGNMENT.sub(r"\1[REDACTED]", redacted)
+    redacted = _UNIX_HOME.sub(r"\1[USER]", redacted)
+    redacted = _WINDOWS_HOME.sub(r"\1[USER]", redacted)
+    return _TOKEN_PREFIX.sub("[REDACTED]", redacted)
+
+
+class _JsonFormatter(logging.Formatter):
+    """输出单行 JSON：{ts, level, logger, message} + 自定义 extra 字段。"""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": _redact_message(record.getMessage()),
+        }
+        for key, value in record.__dict__.items():
+            if key not in _SKIP_ATTRS and not key.startswith("_"):
+                payload[key] = value
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+def setup_logging(log_level: str = "INFO") -> None:
+    """为 `mxready` logger 配置 JSON 结构化输出（幂等，可重复调用）。"""
+    logger = logging.getLogger(_LOGGER_NAME)
+    if logger.handlers:
+        return
+
+    level = getattr(logging, str(log_level).upper(), logging.INFO)
+    logger.setLevel(level)
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(_JsonFormatter())
+    logger.addHandler(handler)
+    logger.propagate = False

mxready/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Optional Model Context Protocol front end for MXReady.
+
+Importing this package does not require the ``mcp`` SDK; only
+:mod:`mxready.mcp.server` does.
+"""