dsh-calibguard 0.2.4 → 0.3.0

package/engine/calibguard/pipeline.py

@@ -0,0 +1,305 @@
+"""流水线编排：串联 T4~T10，产出单文件完整报告 dict。"""
+import datetime
+import hashlib
+import math
+import os
+import sys
+import uuid
+
+from calibguard import constants as C
+from calibguard.calibrator import PlattCalibrator
+from calibguard.config import AppConfig
+from calibguard.feature_extractor import evidence_to_prompt_text, extract_features
+from calibguard.gate import route
+from calibguard.llm_analyzer import LLMAnalyzer
+from calibguard.model import CodeBERTClassifier
+from calibguard.preprocessor import preprocess_file
+from calibguard.report import _evidence_to_dict, write_reports
+from calibguard.schemas import (
+    FeatureEvidence,
+    GateDecision,
+    LLMResult,
+    WindowInferenceStats,
+)
+
+
+class AuditPipeline:
+    """单文件/目录审计流水线。"""
+
+    def __init__(self, cfg: AppConfig):
+        self.cfg = cfg
+        # 1. 模型（加载失败抛 RuntimeError，由 CLI 转退出码 4）
+        self.classifier = CodeBERTClassifier(
+            cfg.model_path, cfg.max_length,
+            window_stride=cfg.window_stride, window_batch_size=cfg.window_batch_size)
+        # 2. 校准器（calibration_method 一律取实例的 .method 属性）
+        if cfg.calibration_params_path == "":
+            self.calibrator = PlattCalibrator.identity()
+        elif os.path.isfile(cfg.calibration_params_path):
+            self.calibrator = PlattCalibrator.load(cfg.calibration_params_path)
+        else:
+            raise FileNotFoundError(
+                "校准参数文件缺失，请先运行 scripts/calibrate.py，"
+                "或在 config.yaml 中将 calibration.params_path 设为空字符串")
+        # 3. 云端 LLM 分析器（属性名必须是 llm）
+        self.llm = LLMAnalyzer(
+            api_key=cfg.llm_api_key, base_url=cfg.llm_base_url, model=cfg.llm_model,
+            temperature=cfg.llm_temperature, max_tokens=cfg.llm_max_tokens,
+            timeout=cfg.llm_timeout, evidence_max_chars=cfg.evidence_max_chars)
+
+    def audit_file(self, path: str) -> dict:
+        """单文件 → 完整报告 dict。任何处理异常都降级为 manual_review，不向调用方抛出。"""
+        report = self._new_report(path)
+        try:
+            # 步骤 1：读前 1MB 字节，用于 sha256 与 size
+            with open(path, "rb") as handle:
+                head_bytes = handle.read(C.MAX_INPUT_BYTES)
+            report["file_sha256"] = hashlib.sha256(head_bytes).hexdigest()
+            report["file_size_bytes"] = len(head_bytes)
+
+            # 步骤 2：预处理
+            result = preprocess_file(path)
+            report["source_type"] = result.source_type
+            report["preprocess_truncated"] = result.truncated
+            report["archive_parts"] = result.parts
+
+            # 步骤 3：特征提取（全文，信息更全）
+            evidence = extract_features(result.text)
+            report["evidence"] = _evidence_to_dict(evidence)
+
+            # 步骤 4：滑窗推理与批间早停
+            agg_logit = -math.inf
+            stats = WindowInferenceStats()
+            for batch_logits in self.classifier.iter_window_batches(result.text):
+                stats.windows_evaluated += len(batch_logits)
+                batch_max = max(batch_logits)
+                agg_logit = max(agg_logit, batch_max)
+                # 批间早停：本批内任一窗口校准概率 > early_stop_threshold 即停
+                for window_logit in batch_logits:
+                    if (self.calibrator.predict_proba(window_logit)
+                            > self.cfg.early_stop_threshold):
+                        stats.early_stopped = True
+                        stats.early_stop_probability = self.calibrator.predict_proba(batch_max)
+                        break
+                if stats.early_stopped:
+                    # 生成器后续批次不再被消费，即"立即停止后续窗口"
+                    break
+            raw_logit = float(agg_logit)
+            report["raw_logit"] = raw_logit
+            report["windows_evaluated"] = stats.windows_evaluated
+            report["early_stopped"] = stats.early_stopped
+            report["early_stop_probability"] = stats.early_stop_probability
+
+            # 步骤 5：校准概率（早停时 p = early_stop_probability > block_threshold）
+            probability = self.calibrator.predict_proba(raw_logit)
+            report["calibrated_probability"] = probability
+
+            # 步骤 6：门控路由
+            gate = route(probability, self.cfg.allow_threshold, self.cfg.block_threshold)
+            report["gate_decision"] = gate.value
+
+            # 步骤 7：仅门控为 LLM_REVIEW 时才上云
+            #   内容源：精炼证据 / 文件原文；投递模式：截断 / 滑窗 / 一次性全部上传
+            #   多段时逐段调用，按风险严重度取最严重的一段（high > medium > low）
+            llm_result: LLMResult | None = None
+            llm_payloads: list[str] = []
+            if gate == GateDecision.LLM_REVIEW:
+                if not self.cfg.llm_enabled:
+                    # 用户关闭云端复核：灰区按本地模型自身能力 0.5 切（不改门控口径）
+                    llm_result = LLMResult(status="disabled")
+                    report["llm"] = {
+                        "status": "disabled",
+                        "risk": None,
+                        "reason": None,
+                        "action": None,
+                        "retries_used": 0,
+                    }
+                else:
+                    llm_payloads = self._build_llm_payloads(evidence, result.text)
+                    llm_result = self._review_with_llm(llm_payloads, probability)
+                    report["llm"] = {
+                        "status": llm_result.status,
+                        "risk": llm_result.risk,
+                        "reason": llm_result.reason,
+                        "action": llm_result.action,
+                        "retries_used": llm_result.retries_used,
+                    }
+                    report["consistency_warning"] = llm_result.consistency_warning
+                report["llm_calls"] = len(llm_payloads)
+
+            # 步骤 8：最终决策表
+            final_decision, manual_review_required = self._resolve_decision(
+                gate, llm_result, probability)
+            report["final_decision"] = final_decision
+            report["manual_review_required"] = manual_review_required
+        except Exception as exc:
+            # 安全降级：转人工 + 记录错误，继续处理下一个文件
+            print(f"[错误] 审计失败 {path}: {type(exc).__name__}: {exc}", file=sys.stderr)
+            report["final_decision"] = "manual_review"
+            report["manual_review_required"] = True
+            report["error"] = str(exc)
+
+        # 步骤 9：落盘并回填路径
+        try:
+            json_path, md_path = write_reports(report, self.cfg.report_output_dir)
+        except Exception as exc:
+            print(f"[错误] 报告写入失败 {path}: {type(exc).__name__}: {exc}", file=sys.stderr)
+            write_error = f"报告写入失败: {exc}"
+            report["error"] = (f"{report['error']} | {write_error}"
+                               if report["error"] else write_error)
+        else:
+            report["report_json_path"] = json_path
+            report["report_md_path"] = md_path
+        return report
+
+    def audit_path(self, path: str) -> list[dict]:
+        """文件或目录 → 报告列表。路径不存在抛 FileNotFoundError（CLI 转退出码 1）。"""
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"路径不存在: {path}")
+        if os.path.isfile(path):
+            return [self.audit_file(path)]
+        reports: list[dict] = []
+        for file_path in self._collect_files(path):
+            try:
+                reports.append(self.audit_file(file_path))
+            except Exception as exc:
+                # 兜底：单文件失败不得中断整体
+                print(f"[错误] 审计失败 {file_path}: {type(exc).__name__}: {exc}",
+                      file=sys.stderr)
+                fallback = self._new_report(file_path)
+                fallback["final_decision"] = "manual_review"
+                fallback["manual_review_required"] = True
+                fallback["error"] = str(exc)
+                reports.append(fallback)
+        return reports
+
+    def _collect_files(self, path: str) -> list[str]:
+        """os.walk 递归收集常规文件（非符号链接），按路径排序，跳过输出目录。"""
+        output_dir_abs = os.path.abspath(self.cfg.report_output_dir)
+        collected: list[str] = []
+        for root, _dir_names, file_names in os.walk(path):
+            for file_name in file_names:
+                full_path = os.path.join(root, file_name)
+                if not os.path.isfile(full_path):
+                    continue
+                if os.path.islink(full_path):
+                    continue
+                file_abs = os.path.abspath(full_path)
+                if file_abs == output_dir_abs or file_abs.startswith(output_dir_abs + os.sep):
+                    continue
+                collected.append(full_path)
+        collected.sort()
+        return collected
+
+    def _resolve_decision(self, gate: GateDecision, llm_result: LLMResult | None,
+                          probability: float) -> tuple[str, bool]:
+        """14.3 最终决策表（逐行照抄实现，禁止改动）。
+
+        唯一扩展（2026-10-05）：用户显式关闭云端复核时，灰区按本地模型 0.5 划分
+        （p > 0.5 → block，否则 allow），不再转人工。
+        """
+        if gate == GateDecision.ALLOW:
+            return "allow", False
+        if gate == GateDecision.BLOCK:
+            return "block", False
+        # gate == GateDecision.LLM_REVIEW
+        if llm_result is not None and llm_result.status == "disabled":
+            # 关闭云端复核：按模型自身能力在 0.5 处切
+            return ("block", False) if probability > 0.5 else ("allow", False)
+        if llm_result is None or llm_result.status != "ok":
+            # invalid_output / api_error
+            return "manual_review", True
+        if llm_result.risk == "high":
+            return "block", False
+        if llm_result.risk == "medium":
+            return "suspicious", bool(llm_result.consistency_warning)
+        if llm_result.risk == "low":
+            if llm_result.consistency_warning:
+                return "suspicious", True
+            return "allow", False
+        # risk 取值异常（理论上不可达）→ 铁律 5 安全降级为转人工
+        print(f"[错误] LLM 返回未知 risk={llm_result.risk!r}，安全降级为转人工", file=sys.stderr)
+        return "manual_review", True
+
+    # ==================== 云端 LLM 复核投递（2026-10-05） ====================
+
+    def _build_llm_payloads(self, evidence: FeatureEvidence, text: str) -> list[str]:
+        """按配置把待复核内容切成 1..N 段。
+
+        内容源（llm_content_source）：evidence=精炼证据（沿用 evidence_max_chars 上限）；
+        raw=预处理后的文件原文。投递模式（llm_delivery_mode）：truncate=取前 N 字符；
+        window=按 window_chars/overlap 分片；all=整段一次性上传。
+        """
+        if self.cfg.llm_content_source == "raw":
+            content = text or ""
+        else:
+            content = evidence_to_prompt_text(evidence, self.cfg.evidence_max_chars)
+
+        if self.cfg.llm_delivery_mode == "all":
+            return [content]
+        if self.cfg.llm_delivery_mode == "truncate":
+            return [content[:self.cfg.llm_truncate_chars]]
+
+        size = self.cfg.llm_window_chars
+        step = max(1, size - self.cfg.llm_window_overlap)
+        if len(content) <= size:
+            return [content]
+        chunks: list[str] = []
+        start = 0
+        while start < len(content):
+            chunks.append(content[start:start + size])
+            if start + size >= len(content):
+                break
+            start += step
+        return chunks
+
+    def _review_with_llm(self, payloads: list[str],
+                         probability: float) -> LLMResult:
+        """逐段调用云端 LLM，按风险严重度取最严重的一段（high > medium > low）。"""
+        results = [self.llm.analyze(payload, probability) for payload in payloads]
+        return self._merge_llm_results(results)
+
+    @staticmethod
+    def _merge_llm_results(results: list[LLMResult]) -> LLMResult:
+        """合并多段 LLM 结果：有成功段则取最严重；全失败则按 invalid_output/api_error 归类。"""
+        ok_results = [item for item in results if item.status == "ok"]
+        if not ok_results:
+            if any(item.status == "invalid_output" for item in results):
+                return LLMResult(status="invalid_output",
+                                 retries_used=max(item.retries_used for item in results))
+            return LLMResult(status="api_error")
+        severity = {"high": 3, "medium": 2, "low": 1}
+        best = max(ok_results, key=lambda item: severity.get(item.risk, 0))
+        return LLMResult(
+            status="ok", risk=best.risk, reason=best.reason, action=best.action,
+            consistency_warning=any(item.consistency_warning for item in results),
+            retries_used=0)
+
+    def _new_report(self, path: str) -> dict:
+        """报告骨架：含 13.2 规范的全部键（错误路径同样返回完整键集）。"""
+        return {
+            "report_id": uuid.uuid4().hex,
+            "timestamp": datetime.datetime.now().astimezone().isoformat(),
+            "file_path": os.path.abspath(path),
+            "file_sha256": "",
+            "file_size_bytes": 0,
+            "source_type": "",
+            "preprocess_truncated": False,
+            "archive_parts": 1,
+            "raw_logit": 0.0,
+            "calibrated_probability": 0.0,
+            "calibration_method": self.calibrator.method,
+            "windows_evaluated": 0,
+            "early_stopped": False,
+            "early_stop_probability": None,
+            "gate_decision": "",
+            "final_decision": "",
+            "manual_review_required": False,
+            "consistency_warning": False,
+            "llm": None,
+            "llm_calls": 0,
+            "evidence": _evidence_to_dict(FeatureEvidence()),
+            "report_json_path": "",
+            "report_md_path": "",
+            "error": None,
+        }

package/engine/calibguard/preprocessor.py

@@ -0,0 +1,218 @@
+"""预处理模块：任意输入文件 → 统一文本。
+
+只按内容判定类型（魔数 + 解码尝试），不按扩展名。压缩包一律在内存中解包，
+禁止 extractall / extract 落盘（因此不需要 tarfile 的 filter 参数）。
+"""
+import gzip
+import io
+import json
+import logging
+import re
+import tarfile
+import zipfile
+
+from calibguard import constants as C
+from calibguard.schemas import PreprocessResult
+
+logger = logging.getLogger(__name__)
+
+# 控制字符模式（仅用于 text/binary 判定；不含 \t \n \r）
+_CONTROL_CHARS_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f]")
+# 控制字符占比超过该值即判定为二进制（见 7.3 步骤 4）
+_CONTROL_CHAR_RATIO_MAX = 0.30
+# 二进制可打印串提取模式（最短连续长度取常量 PRINTABLE_MIN_RUN）
+_PRINTABLE_RE = re.compile(rb"[\x20-\x7e]{%d,}" % C.PRINTABLE_MIN_RUN)
+# 连续 3 个及以上空白字符（空格/制表符）压缩模式
+_BLANK_RUN_RE = re.compile(r"[ \t]{3,}")
+# 解包截断标记
+_ARCHIVE_TRUNCATED_MARK = "\n\n[ARCHIVE_PARTIALLY_EXTRACTED]"
+
+
+def preprocess_file(path: str) -> PreprocessResult:
+    """主流程：读入 → 判定压缩包 → 解包或解码 → JSON 规整 → 清洗。"""
+    data, read_truncated = _read_bytes(path)
+
+    # 步骤 2 + 步骤 3：压缩包走内存解包
+    if _detect_archive(data) is not None:
+        archive_text, parts, expand_truncated = _expand_archive(data, 0)
+        return PreprocessResult(
+            text=_clean_text(archive_text),
+            source_type="archive",
+            truncated=read_truncated or expand_truncated,
+            parts=parts,
+        )
+
+    # 步骤 4：非压缩包 → 解码或可打印串提取
+    text, source_type = _decode_text(data)
+
+    # 步骤 5：JSON 规整（仅 text 类；解析失败原样保留）
+    if source_type == "text":
+        stripped = text.strip()
+        if stripped.startswith("{") or stripped.startswith("["):
+            try:
+                parsed = json.loads(stripped)
+            except ValueError as exc:
+                logger.debug("JSON 解析失败，按原文保留: %s", exc)
+            else:
+                text = json.dumps(parsed, ensure_ascii=False, indent=2)
+
+    # 步骤 6 + 步骤 7
+    return PreprocessResult(
+        text=_clean_text(text),
+        source_type=source_type,
+        truncated=read_truncated,
+        parts=1,
+    )
+
+
+def _read_bytes(path: str) -> tuple[bytes, bool]:
+    """读入文件字节。(数据, 是否被读入截断)。不存在或不可读 → FileNotFoundError。"""
+    try:
+        with open(path, "rb") as handle:
+            data = handle.read(C.MAX_INPUT_BYTES + 1)
+    except FileNotFoundError:
+        raise
+    except OSError as exc:
+        # 不可读（权限等）按文档统一转为 FileNotFoundError
+        raise FileNotFoundError(f"文件不存在或不可读: {path}") from exc
+    if len(data) > C.MAX_INPUT_BYTES:
+        return data[:C.MAX_INPUT_BYTES], True
+    return data, False
+
+
+def _detect_archive(data: bytes) -> str | None:
+    """"zip" | "gzip" | "tar" | None（纯魔数判定）。"""
+    if data[:4] in (b"PK\x03\x04", b"PK\x05\x06"):
+        return "zip"
+    if data[:2] == b"\x1f\x8b":
+        return "gzip"
+    if data[257:262] == b"ustar":
+        return "tar"
+    return None
+
+
+def _expand_archive(data: bytes, depth: int) -> tuple[str, int, bool]:
+    """内存解包压缩包，返回 (拼接文本, 内部文件数, 是否被解包截断)。
+
+    只处理常规文件成员：zip 用 zf.read(info)，tar 用 tf.extractfile(m).read()；
+    目录、符号链接、硬链接、设备成员一律跳过（链接成员是 tar 的经典攻击面）。
+    """
+    archive_type = _detect_archive(data)
+    members: list[tuple[str, bytes]] = []
+    file_count = 0
+    total_bytes = 0
+    truncated = False
+
+    try:
+        if archive_type == "zip":
+            with zipfile.ZipFile(io.BytesIO(data)) as zf:
+                for info in zf.infolist():
+                    if info.is_dir():
+                        continue
+                    # 安全限制：读成员前先按其声明大小检查
+                    if (file_count + 1 > C.ARCHIVE_MAX_FILES
+                            or total_bytes + info.file_size > C.ARCHIVE_MAX_TOTAL_BYTES):
+                        truncated = True
+                        break
+                    blob = zf.read(info)
+                    members.append((info.filename, blob))
+                    file_count += 1
+                    total_bytes += len(blob)
+        elif archive_type == "tar":
+            with tarfile.open(fileobj=io.BytesIO(data), mode="r:*") as tf:
+                for member in tf:
+                    if not member.isreg():
+                        continue
+                    # 安全限制：读成员前先按其声明大小检查
+                    if (file_count + 1 > C.ARCHIVE_MAX_FILES
+                            or total_bytes + member.size > C.ARCHIVE_MAX_TOTAL_BYTES):
+                        truncated = True
+                        break
+                    extracted = tf.extractfile(member)
+                    if extracted is None:
+                        # 声明为常规文件却取不到内容：跳过该成员并记录
+                        logger.warning("tar 成员无法读取，已跳过: %s", member.name)
+                        continue
+                    blob = extracted.read()
+                    members.append((member.name, blob))
+                    file_count += 1
+                    total_bytes += len(blob)
+        elif archive_type == "gzip":
+            inner = gzip.decompress(data)
+            if _detect_archive(inner) == "tar":
+                # tar.gz 两步走：属同一压缩层级，深度不递增
+                return _expand_archive(inner, depth)
+            members.append(("", inner))
+            file_count = 1
+            total_bytes = len(inner)
+        else:
+            # 魔数判定为压缩包却无法识别类型：按二进制处理
+            return _extract_printable(data), 1, False
+    except Exception as exc:
+        # 损坏的压缩包 → 视为二进制，走可打印串提取（不吞异常：记录并明确返回）
+        logger.warning("压缩包解析失败，按二进制处理: %s: %s", type(exc).__name__, exc)
+        return _extract_printable(data), 1, False
+
+    # 第二遍：嵌套压缩包递归（深度 +1），其余解码为文本
+    collected: list[tuple[str, str]] = []
+    for name, blob in members:
+        if _detect_archive(blob) is not None:
+            if depth + 1 > C.ARCHIVE_MAX_DEPTH:
+                continue  # 超出递归深度上限，跳过该内部文件
+            inner_text, inner_parts, inner_truncated = _expand_archive(blob, depth + 1)
+            file_count += inner_parts
+            truncated = truncated or inner_truncated
+            collected.append((name, inner_text))
+        else:
+            member_text, _member_type = _decode_text(blob)
+            collected.append((name, member_text))
+
+    # 全部文本按文件名排序后用 "\n\n" 连接（不加任何标记）
+    collected.sort(key=lambda item: item[0])
+    joined = "\n\n".join(entry_text for _name, entry_text in collected)
+    if truncated:
+        joined += _ARCHIVE_TRUNCATED_MARK
+    return joined, file_count, truncated
+
+
+def _decode_text(data: bytes) -> tuple[str, str]:
+    """(文本, "text"|"binary")：先 utf-8 再 gbk，均严格模式。"""
+    text: str | None = None
+    for encoding in ("utf-8", "gbk"):
+        try:
+            text = data.decode(encoding)
+            break  # 解码成功，结束尝试
+        except UnicodeDecodeError as exc:
+            # 该编码不适用：记录原因后继续尝试下一种编码
+            logger.debug("按 %s 解码失败，尝试下一种编码: %s", encoding, exc)
+    if text is None:
+        # 两种解码都失败 → 二进制
+        return _extract_printable(data), "binary"
+    if text == "":
+        return text, "text"  # 空字符串直接判 text，不做除法
+    control_ratio = len(_CONTROL_CHARS_RE.findall(text)) / len(text)
+    if control_ratio > _CONTROL_CHAR_RATIO_MAX:
+        return _extract_printable(data), "binary"
+    return text, "text"
+
+
+def _extract_printable(data: bytes) -> str:
+    """提取二进制中的可打印 ASCII 串，各段用 "\\n" 连接。"""
+    runs = _PRINTABLE_RE.findall(data)
+    return b"\n".join(runs).decode("ascii")
+
+
+def _clean_text(text: str) -> str:
+    """a 删控制字符 → b 压缩连续空白 → c 单行截断 → d 总长截断。"""
+    text = re.sub(C.CONTROL_CHARS_PATTERN, "", text)
+    text = _BLANK_RUN_RE.sub(" ", text)
+    lines = text.split("\n")
+    clipped_lines: list[str] = []
+    for line in lines:
+        if len(line) > C.LINE_TRUNCATE_THRESHOLD:
+            line = line[:C.LINE_TRUNCATE_THRESHOLD] + "…[LINE_TRUNCATED]"
+        clipped_lines.append(line)
+    text = "\n".join(clipped_lines)
+    if len(text) > C.MAX_TEXT_CHARS:
+        text = text[:C.MAX_TEXT_CHARS] + "\n…[TEXT_TRUNCATED]"
+    return text

package/engine/calibguard/report.py

@@ -0,0 +1,132 @@
+"""审计报告模块：审计结果 dict → JSON 文件 + Markdown 文件。"""
+import json
+import os
+
+from calibguard.schemas import FeatureEvidence
+
+# 证据明细的七类标题（第八类"异常结构特征"由长行/随机标识符两行构成）
+_EVIDENCE_TITLES = [
+    ("【危险API调用】", "dangerous_apis"),
+    ("【网络行为】", "network_indicators"),
+    ("【凭据与敏感路径访问】", "credential_access"),
+    ("【编码与混淆】", "obfuscation_signals"),
+    ("【可疑文件操作】", "file_operations"),
+    ("【提示注入话术】", "injection_phrases"),
+    ("【高熵字符串】", "high_entropy_strings"),
+]
+# 证据全空时的固定文案
+_EMPTY_EVIDENCE_TEXT = "未发现明显可疑信号。"
+
+
+def write_reports(report: dict, output_dir: str) -> tuple[str, str]:
+    """生成 <output_dir>/<report_id>.json 与 <output_dir>/<report_id>.md，返回绝对路径。"""
+    os.makedirs(output_dir, exist_ok=True)
+    report_id = str(report["report_id"])
+    json_path = os.path.abspath(os.path.join(output_dir, report_id + ".json"))
+    md_path = os.path.abspath(os.path.join(output_dir, report_id + ".md"))
+    with open(json_path, "w", encoding="utf-8") as handle:
+        handle.write(json.dumps(report, ensure_ascii=False, indent=2))
+    with open(md_path, "w", encoding="utf-8") as handle:
+        handle.write(_to_markdown(report))
+    return json_path, md_path
+
+
+def _evidence_to_dict(ev: FeatureEvidence) -> dict:
+    """FeatureEvidence → 九个同名键的 dict。"""
+    return {
+        "dangerous_apis": list(ev.dangerous_apis),
+        "network_indicators": list(ev.network_indicators),
+        "credential_access": list(ev.credential_access),
+        "obfuscation_signals": list(ev.obfuscation_signals),
+        "file_operations": list(ev.file_operations),
+        "injection_phrases": list(ev.injection_phrases),
+        "high_entropy_strings": list(ev.high_entropy_strings),
+        "long_line_numbers": list(ev.long_line_numbers),
+        "random_identifier_count": ev.random_identifier_count,
+    }
+
+
+def _to_markdown(report: dict) -> str:
+    """按 13.3 固定模板渲染 Markdown 报告。"""
+    early_stopped = bool(report.get("early_stopped"))
+    if early_stopped:
+        early_stop_text = f"是，p={report.get('early_stop_probability')}"
+    else:
+        early_stop_text = "否"
+
+    lines: list[str] = [
+        "# CalibGuard 安全审计报告",
+        "",
+        f"- 报告编号：{report['report_id']}",
+        f"- 生成时间：{report['timestamp']}",
+        f"- 审计文件：{report['file_path']}",
+        f"- 文件 SHA256：{report['file_sha256']}",
+        f"- 文件大小：{report['file_size_bytes']} 字节",
+        f"- 来源类型：{report['source_type']}（内部文件数：{report['archive_parts']}）",
+        "",
+        "## 结论",
+        "",
+        "| 项目 | 结果 |",
+        "|---|---|",
+        f"| 原始 logit | {report['raw_logit']} |",
+        f"| 校准概率 | {report['calibrated_probability']} |",
+        f"| 校准方法 | {report['calibration_method']} |",
+        f"| 推理窗口数 | {report['windows_evaluated']} |",
+        f"| 滑窗早停 | {early_stop_text} |",
+        f"| 门控决策 | {report['gate_decision']} |",
+        f"| 最终决策 | **{report['final_decision']}** |",
+        f"| 需人工复核 | {report['manual_review_required']} |",
+        f"| 一致性告警 | {report['consistency_warning']} |",
+        "",
+        "## LLM 分析",
+        "",
+    ]
+
+    llm = report.get("llm")
+    if llm is None:
+        lines.append("（未提交云端分析）")
+    else:
+        lines.extend([
+            "| 字段 | 值 |",
+            "|---|---|",
+            f"| status | {llm.get('status')} |",
+            f"| risk | {llm.get('risk')} |",
+            f"| reason | {llm.get('reason')} |",
+            f"| action | {llm.get('action')} |",
+            f"| 重试次数 | {llm.get('retries_used')} |",
+        ])
+
+    lines.extend(["", "## 证据明细", ""])
+    lines.append(_render_evidence_section(report.get("evidence") or {}))
+
+    lines.extend(["", "## 错误信息", ""])
+    error = report.get("error")
+    lines.append(str(error) if error else "（无）")
+
+    return "\n".join(lines) + "\n"
+
+
+def _render_evidence_section(evidence: dict) -> str:
+    """按 8.4 的八类格式渲染证据明细；全空时返回固定文案。"""
+    blocks: list[str] = []
+    for title, key in _EVIDENCE_TITLES:
+        items = evidence.get(key) or []
+        if not items:
+            continue
+        block_lines = [title]
+        block_lines.extend(f"- {item}" for item in items)
+        blocks.append("\n".join(block_lines))
+
+    structural_lines: list[str] = []
+    long_line_numbers = evidence.get("long_line_numbers") or []
+    if long_line_numbers:
+        structural_lines.append(f"- 超长行行号: {long_line_numbers}")
+    random_identifier_count = evidence.get("random_identifier_count") or 0
+    if random_identifier_count > 0:
+        structural_lines.append(f"- 长随机标识符数量: {random_identifier_count}")
+    if structural_lines:
+        blocks.append("\n".join(["【异常结构特征】"] + structural_lines))
+
+    if not blocks:
+        return _EMPTY_EVIDENCE_TEXT
+    return "\n\n".join(blocks)