feat(ack): add project knowledge guardrails

2026-07-31 21:09:36 +08:00
parent 7d1994cf93
commit ee66dbe9ce
32 changed files with 8353 additions and 139 deletions
@@ -0,0 +1,430 @@
+#!/usr/bin/env python3
+"""安全执行 knowledge.yaml 中已审查的 verificationRegistry 条目。
+
+本入口只接受 registry ID，不接受额外命令或参数。执行前只打开一次项目根目录
+fd，知识库、检查目标和子进程 cwd 都固定到该 fd；检查文件逐段以 O_NOFOLLOW
+打开后复制到匿名、尽可能 sealed 的稳定快照，再使用结构化 argv 和 shell=False
+启动，避免检查与执行之间被替换。
+
+退出码: 0..125 沿用检查结果 / 1 知识或执行失败 / 2 环境、路径或用法错误。
+"""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import os
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from validate_knowledge import (  # type: ignore
+    infer_project_root,
+    load_yaml_text,
+    validate_all,
+)
+
+MAX_KNOWLEDGE_BYTES = 16 * 1024 * 1024
+MAX_TARGET_BYTES = 16 * 1024 * 1024
+
+
+def _project_root(
+    value: str | None,
+    knowledge_path: Path,
+) -> tuple[Path | None, str | None]:
+    inferred = infer_project_root(knowledge_path)
+    if value is not None:
+        candidate = Path(value).expanduser()
+        if not candidate.is_dir():
+            return None, f"项目根目录不存在: {candidate}"
+        resolved = candidate.resolve(strict=True)
+        if inferred is not None and resolved != inferred:
+            return (
+                None,
+                f"--project-root {resolved} 与 knowledge.yaml 推断的项目根目录 "
+                f"{inferred} 不一致",
+            )
+        return resolved, None
+    if inferred is None:
+        return None, "无法从 knowledge.yaml 确定现有项目根目录"
+    return inferred, None
+
+
+def _validate_knowledge_location(
+    knowledge_path: Path,
+    project_root: Path,
+) -> str | None:
+    expected = project_root / "docs" / "ack" / "knowledge.yaml"
+    lexical = Path(os.path.abspath(knowledge_path.expanduser()))
+    if lexical != expected:
+        return (
+            "只允许执行项目权威知识库 "
+            f"{expected}，当前输入为 {lexical}"
+        )
+    return None
+
+
+def _open_regular_beneath(
+    project_root: Path | int,
+    relative_path: str,
+    *,
+    require_executable: bool,
+) -> tuple[int | None, str | None]:
+    """从根目录 fd 逐段打开目标，不允许任一段通过 symlink 跳转。"""
+    if not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_DIRECTORY"):
+        return None, "当前平台不支持安全的 O_NOFOLLOW/O_DIRECTORY 路径解析"
+    parts = PurePosixPath(relative_path).parts
+    if (
+        not parts
+        or PurePosixPath(relative_path).is_absolute()
+        or any(part in {"", ".", ".."} for part in parts)
+    ):
+        return None, "检查目标必须是规范的项目内相对路径"
+
+    directory_fds: list[int] = []
+    target_fd: int | None = None
+    try:
+        root_fd = (
+            os.dup(project_root)
+            if isinstance(project_root, int)
+            else os.open(
+                project_root,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+            )
+        )
+        directory_fds.append(root_fd)
+        current_fd = root_fd
+        for segment in parts[:-1]:
+            current_fd = os.open(
+                segment,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                dir_fd=current_fd,
+            )
+            directory_fds.append(current_fd)
+        target_fd = os.open(
+            parts[-1],
+            os.O_RDONLY | os.O_NOFOLLOW,
+            dir_fd=current_fd,
+        )
+        metadata = os.fstat(target_fd)
+        if not stat.S_ISREG(metadata.st_mode):
+            os.close(target_fd)
+            return None, "检查目标不是普通文件"
+        if require_executable and metadata.st_mode & 0o111 == 0:
+            os.close(target_fd)
+            return None, "检查目标不可执行"
+        return target_fd, None
+    except OSError as exc:
+        if target_fd is not None:
+            os.close(target_fd)
+        return None, f"检查目标不存在、不可访问或路径包含软链接: {exc}"
+    finally:
+        for directory_fd in reversed(directory_fds):
+            os.close(directory_fd)
+
+
+def _stable_metadata(before: os.stat_result, after: os.stat_result) -> bool:
+    fields = (
+        "st_dev",
+        "st_ino",
+        "st_mode",
+        "st_size",
+        "st_mtime_ns",
+        "st_ctime_ns",
+    )
+    return all(getattr(before, field) == getattr(after, field) for field in fields)
+
+
+def _read_stable_bytes(
+    source_fd: int,
+    *,
+    maximum: int,
+) -> tuple[bytes | None, str | None]:
+    before = os.fstat(source_fd)
+    if before.st_size > maximum:
+        return None, f"知识库超过大小上限 {maximum} bytes"
+    chunks: list[bytes] = []
+    total = 0
+    try:
+        os.lseek(source_fd, 0, os.SEEK_SET)
+        while True:
+            chunk = os.read(source_fd, min(1024 * 1024, maximum - total + 1))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            total += len(chunk)
+            if total > maximum:
+                return None, f"知识库超过大小上限 {maximum} bytes"
+    except OSError as exc:
+        return None, f"无法读取权威知识库快照: {exc}"
+    after = os.fstat(source_fd)
+    if not _stable_metadata(before, after):
+        return None, "权威知识库在读取期间发生变化，拒绝执行"
+    return b"".join(chunks), None
+
+
+def load_authoritative_knowledge(
+    project_root: Path | int,
+) -> tuple[dict[str, Any] | None, str | None]:
+    source_fd, open_error = _open_regular_beneath(
+        project_root,
+        "docs/ack/knowledge.yaml",
+        require_executable=False,
+    )
+    if open_error is not None or source_fd is None:
+        return None, open_error or "无法安全打开权威知识库"
+    try:
+        content, read_error = _read_stable_bytes(
+            source_fd,
+            maximum=MAX_KNOWLEDGE_BYTES,
+        )
+    finally:
+        os.close(source_fd)
+    if read_error is not None or content is None:
+        return None, read_error or "无法读取权威知识库"
+    try:
+        text = content.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return None, f"权威知识库不是有效 UTF-8: {exc}"
+    return load_yaml_text(text, "知识库"), None
+
+
+def _write_all(file_descriptor: int, chunk: bytes) -> None:
+    remaining = memoryview(chunk)
+    while remaining:
+        written = os.write(file_descriptor, remaining)
+        if written <= 0:
+            raise OSError("无法写入检查快照")
+        remaining = remaining[written:]
+
+
+def _snapshot_executable(source_fd: int) -> tuple[int | None, str | None]:
+    """复制到匿名快照；Linux 上进一步 seal，冻结本次执行内容。"""
+    before = os.fstat(source_fd)
+    if before.st_size > MAX_TARGET_BYTES:
+        return None, f"检查目标超过大小上限 {MAX_TARGET_BYTES} bytes"
+    snapshot_fd: int | None = None
+    seal_snapshot = all(
+        hasattr(owner, name)
+        for owner, name in (
+            (os, "memfd_create"),
+            (os, "MFD_ALLOW_SEALING"),
+            (os, "MFD_CLOEXEC"),
+            (fcntl, "F_ADD_SEALS"),
+            (fcntl, "F_SEAL_SEAL"),
+            (fcntl, "F_SEAL_SHRINK"),
+            (fcntl, "F_SEAL_GROW"),
+            (fcntl, "F_SEAL_WRITE"),
+        )
+    )
+    try:
+        if seal_snapshot:
+            snapshot_fd = os.memfd_create(  # type: ignore[attr-defined]
+                "ack-verification",
+                os.MFD_CLOEXEC | os.MFD_ALLOW_SEALING,  # type: ignore[attr-defined]
+            )
+        else:
+            snapshot_fd, snapshot_path = tempfile.mkstemp(
+                prefix="ack-verification-"
+            )
+            os.unlink(snapshot_path)
+
+        os.lseek(source_fd, 0, os.SEEK_SET)
+        total = 0
+        while True:
+            chunk = os.read(
+                source_fd,
+                min(1024 * 1024, MAX_TARGET_BYTES - total + 1),
+            )
+            if not chunk:
+                break
+            _write_all(snapshot_fd, chunk)
+            total += len(chunk)
+            if total > MAX_TARGET_BYTES:
+                os.close(snapshot_fd)
+                return None, f"检查目标超过大小上限 {MAX_TARGET_BYTES} bytes"
+        after = os.fstat(source_fd)
+        if not _stable_metadata(before, after):
+            os.close(snapshot_fd)
+            return None, "检查目标在创建执行快照期间发生变化，拒绝执行"
+
+        os.fchmod(snapshot_fd, before.st_mode & 0o777)
+        os.lseek(snapshot_fd, 0, os.SEEK_SET)
+        if seal_snapshot:
+            seals = (
+                fcntl.F_SEAL_SEAL
+                | fcntl.F_SEAL_SHRINK
+                | fcntl.F_SEAL_GROW
+                | fcntl.F_SEAL_WRITE
+            )
+            fcntl.fcntl(snapshot_fd, fcntl.F_ADD_SEALS, seals)
+        return snapshot_fd, None
+    except OSError as exc:
+        if snapshot_fd is not None:
+            os.close(snapshot_fd)
+        return None, f"无法创建稳定的检查执行快照: {exc}"
+
+
+def open_target(
+    data: dict[str, Any],
+    verification_ref: str,
+    project_root: Path | int,
+) -> tuple[int | None, list[str] | None, str | None]:
+    registry = data.get("verificationRegistry")
+    if not isinstance(registry, dict) or verification_ref not in registry:
+        return None, None, f"verification.ref {verification_ref!r} 未在 registry 注册"
+    target = registry.get(verification_ref)
+    if not isinstance(target, dict):
+        return None, None, f"verificationRegistry.{verification_ref} 不是对象"
+    relative_path = target.get("path")
+    args = target.get("args")
+    if not isinstance(relative_path, str) or not isinstance(args, list):
+        return None, None, f"verificationRegistry.{verification_ref} 结构无效"
+    if any(not isinstance(arg, str) for arg in args):
+        return (
+            None,
+            None,
+            f"verificationRegistry.{verification_ref}.args 必须是字符串数组",
+        )
+    source_fd, error = _open_regular_beneath(
+        project_root,
+        relative_path,
+        require_executable=True,
+    )
+    if error is not None or source_fd is None:
+        return None, None, error or "无法安全打开检查目标"
+    try:
+        target_fd, snapshot_error = _snapshot_executable(source_fd)
+    finally:
+        os.close(source_fd)
+    if snapshot_error is not None or target_fd is None:
+        return None, None, snapshot_error or "无法创建检查执行快照"
+    return target_fd, args, None
+
+
+def _fd_executable_path(target_fd: int) -> str | None:
+    for prefix in ("/proc/self/fd", "/dev/fd"):
+        candidate = f"{prefix}/{target_fd}"
+        if Path(candidate).exists():
+            return candidate
+    return None
+
+
+def _fd_directory_path(directory_fd: int) -> str | None:
+    for prefix in ("/proc/self/fd", "/dev/fd"):
+        candidate = f"{prefix}/{directory_fd}"
+        if Path(candidate).is_dir():
+            return candidate
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="执行 ACK verificationRegistry 中已审查的检查"
+    )
+    parser.add_argument("knowledge", help="knowledge.yaml 路径")
+    parser.add_argument("verification_ref", help="verificationRegistry 中的检查 ID")
+    parser.add_argument(
+        "--project-root",
+        help="项目根目录；默认从 knowledge.yaml 的 docs/ack 布局或 Git 推断",
+    )
+    args = parser.parse_args(argv)
+
+    knowledge_path = Path(args.knowledge)
+    project_root, root_error = _project_root(args.project_root, knowledge_path)
+    if project_root is None:
+        sys.stderr.write(f"{root_error or '无法确定现有项目根目录'}\n")
+        return 2
+    location_error = _validate_knowledge_location(knowledge_path, project_root)
+    if location_error is not None:
+        sys.stderr.write(f"{location_error}\n")
+        return 2
+
+    try:
+        project_root_fd = os.open(
+            project_root,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+        )
+    except OSError as exc:
+        sys.stderr.write(f"无法安全打开项目根目录: {exc}\n")
+        return 2
+
+    try:
+        stable_root_path = _fd_directory_path(project_root_fd)
+        if stable_root_path is None:
+            sys.stderr.write("当前平台无法固定项目根目录文件描述符\n")
+            return 2
+        data, knowledge_error = load_authoritative_knowledge(project_root_fd)
+        if knowledge_error is not None or data is None:
+            sys.stderr.write(f"{knowledge_error or '无法读取权威知识库'}\n")
+            return 2
+        schema_path = (
+            Path(__file__).resolve().parent.parent
+            / "templates"
+            / "knowledge.schema.json"
+        )
+        errors, mode = validate_all(
+            data,
+            schema_path,
+            project_root=Path(stable_root_path),
+        )
+        if errors:
+            sys.stderr.write(f"知识库校验失败（{mode}），拒绝执行：\n")
+            for error in errors:
+                sys.stderr.write(f"  - {error}\n")
+            return 1
+
+        target_fd, target_args, error = open_target(
+            data,
+            args.verification_ref,
+            project_root_fd,
+        )
+        if error is not None or target_fd is None or target_args is None:
+            sys.stderr.write(f"{error or '无法解析检查目标'}\n")
+            return 2
+
+        try:
+            executable_path = _fd_executable_path(target_fd)
+            if executable_path is None:
+                sys.stderr.write(
+                    "当前平台无法从已打开的文件描述符安全执行检查\n"
+                )
+                return 2
+            environment = os.environ.copy()
+            environment["ACK_PROJECT_ROOT"] = stable_root_path
+            environment["ACK_PROJECT_ROOT_DISPLAY"] = str(project_root)
+            environment["ACK_VERIFICATION_REF"] = args.verification_ref
+            registry = data.get("verificationRegistry")
+            target = (
+                registry.get(args.verification_ref)
+                if isinstance(registry, dict)
+                else None
+            )
+            if isinstance(target, dict) and isinstance(target.get("path"), str):
+                environment["ACK_VERIFICATION_PATH"] = target["path"]
+            try:
+                completed = subprocess.run(
+                    [executable_path, *target_args],
+                    cwd=stable_root_path,
+                    env=environment,
+                    shell=False,
+                    check=False,
+                    pass_fds=(project_root_fd, target_fd),
+                )
+            except OSError as exc:
+                sys.stderr.write(f"检查启动失败: {exc}\n")
+                return 1
+        finally:
+            os.close(target_fd)
+    finally:
+        os.close(project_root_fd)
+    if 0 <= completed.returncode <= 125:
+        return completed.returncode
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())