K-Guard MCP

안경선배 · 바이브코딩 선배

不打断创作流程，也不草率放行交付。

K-Guard MCP 是一个本地优先的 MCP 审计官，在交付 vibe coding 成果之前，对站点、API 暴露、数据管理、运营风险进行联合检查。Guardian 区分"没有问题"和"尚未检查到"，并以韩语返回 可交付 / 修复后交付 / 检查范围不足 的判定和后续行动。

K-Guard 不是替代人类商业判断或法律审查的保证书。它自动化了资深开发者在交付前会提出的问题，以及 fail-closed 门禁。

5分钟安装 · 安装·设计验证 · 使用指南 · GitHub 公开指南 · 必备 qualification · 产品北极星 · 完整 dogfood 判定 · 2026 大赛参赛准备

前5分钟：当前源码检出

目前尚不以公开包索引分发为前提。首次运行时，在仓库根目录安装当前源码，并按照 안경선배 展示的后续行动操作。

python -m pip install .
k-guard install --client auto --profile local-dev --workspace .
k-guard doctor --client auto

auto 会查找已安装的 Grok、Codex、Antigravity，将 k-guard MCP 合并到用户范围；如果存在 OpenAI tunnel-client，则准备用于 ChatGPT 的本地 profile。--workspace . 将当前项目固定为 private binding。此后即使 MCP 从其他工作目录启动，也会检查该项目，并拒绝边界之外的路径（high HOLD）。ChatGPT doctor/run 还需要当前 shell 中具有 Tunnels Read + Use 权限的 CONTROL_PLANE_API_KEY。ChatGPT 之后还会留下 tunnel-client run 和开发者模式应用连接，因此安装器不会粉饰成功，而是返回 部分连接 · 需要后续步骤。现有配置会被保留，JSON 变更前会创建备份；操作者 evidence key 和 workspace 原文仅存储在 ~/.k-guard 的用户专用文件中。local-dev 仅启用 localhost read-only probe 和少量固定深度检查路径，外部·会话 probe 保持关闭。如果只需要静态检查，请使用 --profile workspace。

安装和诊断的默认输出分为三个阶段：连接准备 → AI 客户端 → 后续行动。自动化使用 install --json、doctor --json。竞赛评审·发布复现和代码修改请使用5分钟安装的评审·复现验证路径，以 --require-hashes 安装 build·evidence lock。Semgrep 1.174.0 和 pip-audit 2.10.1 也分别将 requirements-semgrep.lock、requirements-pip-audit.lock 的完整 hash closure 安装到隔离 venv 中，不改变审计目标运行时。

在 MCP 客户端中：

안경선배로 이 앱을 끝까지 봐줘. check_my_app으로 전체 검수를 시작하고,
continue_review를 state=completed 또는 failed가 될 때까지 반복해줘.
완료 전에는 통과라고 말하지 마. 코드를 고쳤다면 check_my_app을 다시 완료해줘.
출하 전에는 실제 사업 목적과 범위를 확인한 뒤 최신 review_id로
start_review_before_ship을 실행하고 다시 continue_review로 Guardian 완료까지 기다려줘.
experience.presentation 순서대로 판정, 이유, 다음 행동 3개만 먼저 말해줘.

check_my_app 不是5秒内草草结束的检查，而是受理整个工作区审计的工具。首次响应为 review_in_progress，在 continue_review 完成之前不会做出交付判定。dist、build、.next 中的部署用文本产物也会被检查；如果候选数量·路径 SHA-256·读取完成度不一致，则以 high 阻断。完成结果会生成绑定 workspace 和 source tree SHA-256 的 review_receipt。代码变更后，无法用旧的 review_id 启动交付审查，必须重新完成 check_my_app。

Related MCP server: Secure Code Review MCP Server

안경선배 判定

所有代表结果都同时提供 experience.presentation 及其兼容别名 experience.details.presentation，顺序固定为 verdict → why → next_actions → details。Guardian 将应用风险显示为 application_assurance，将审计工具自身的验证状态显示为 auditor_qualification。experience.verdict_code、experience.verdict_message、experience.summary 是兼容现有报告的字段。

检查内容

K-Guard 结合了：

• 静态扫描：韩语 PII、复合 PII、韩语组织标识符（사업자등록번호 校验和语法验证；법인등록번호 历史 Annex 校验和或 2025-01-31 之后的 4+2+7 显式上下文/语法识别，不进行实时注册表验证）、密钥

• 配置扫描：CORS/debug/source map/env 前缀风险

• 资深应用风险扫描：直接 request-to-SQL/command/file/URL/HTML sink、mass assignment、开放重定向、浏览器 token 存储、弱 cookie、明文密码比较、以及 JWT 解码但不验证

• 韩语数据治理扫描：唯一/敏感字段声明、加密/访问控制证据、访问日志、外部处理者审查、保留期、删除

• MCP 原生威胁扫描：隐藏指令、工具投毒、外泄意图、以及跨直接文本加受限 Unicode/confusable、转义/百分号/HTML、Base64、分段碎片、三行滚动归一化的过度本地访问

• 结构化 MCP 配置审查：shell 包装器、可变包启动器、明文远程 HTTP、固定凭据、不安全链接/读取失败、以及跨 project/Codex/Grok/Antigravity 配置候选的 fail-closed 发现边界

• YARA-lite 本地规则包：prompt 注入标记、外泄命令标记、韩语批量 schema 提示

• 安全动态探测：localhost HTTP 检查、明确授权的外部源检查、可选的有界深度暴露检查、以及可选用户提供的只读会话头

• 数据流风险图：启发式图加 Python AST 和轻量 JS/TS source → sink 污点分析，包括唯一导入 Python 辅助函数参数到 sink 摘要和有限 JS/TS 路由到服务 IDOR 摘要

• MCP 运行时观察器/拦截器：JSON/JSONL 和流式事件检查，用于隐藏指令、PII 到 agentic/外部 sink 流，以及对转发事件流的批量阻止/脱敏执行

• Semgrep 深度适配器：离线 40 规则 profile、精确扫描目标证明、固定 1.174.0 身份、源码快照绑定、以及 fail-closed JS/TS/Python/Java/Kotlin/Go/PHP/Ruby/C# 发现

• 九语言验证包：Python/JavaScript/TypeScript/Java/Kotlin/Go/PHP/Ruby/C# 90 个固定易受攻击/干净用例、TP/FN/FP/TN 评分、以及精确两次运行指纹复现

• 软件成分分析：使用 pip-audit、npm audit 和 govulncheck 对 Python/npm/Go manifest 和 lock 进行有界覆盖；部分引擎、lock、输出或源码漂移失败会阻断发布

• Streamable HTTP MCP 代理：POST/GET SSE/DELETE 完全中介、principal 绑定生命周期、默认拒绝 JIT/JEA 授权、过滤工具清单、有界流、以及 HMAC 链式无原始审计日志

• 数据库控制：SQLGlot AST 白名单、role/database/schema/table/column RBAC、读取前 EXPLAIN、SQLite 仅查询授权器、路径包含、以及行/单元格/结果/时间预算

• 只读连接器：本地 SQLite、日志、JSON/CSV/TSV 存储采样，不存储原始值；连接器缺口成为 high 发现

• 保留/删除审查：当存在个人数据信号时，标记缺失的保留/删除标记

• 跨平面判定：将韩语 PII 发现与 LLM/MCP/外部/静态数据 sink 证据关联

• FP/FN 记分板：fixture 语料召回率和误报率。FPR 使用 measurable_negative_count 作为分母（无 expected_absent 的干净负例）；negative_count 是所有声明的负例，targeted_absence_case_count 覆盖不进入 FPR 分母的选定规则缺失。零可测量负例分母报告为 FPR 0.0。

• SARIF/CI 输出：按配置的严重级别使构建失败

• korean_senior Guardian profile：站点安全、API 暴露、数据管理、运营风险四个领域的 fail-closed 契约

• 主要 MCP 工具：check_my_app、continue_review、start_review_before_ship；内部规范引擎：Guardian high；引导提示：guided_review

• 高级 MCP 工具：scan_workspace、deep_analyzer_audit、validate_multilang_pack、software_composition_audit、validate_policy_controls、validate_streamable_http_runtime、scan_text、scan_diff、scan_mcp_config、probe_http、build_flow_map、observe_mcp_events、enforce_mcp_events、observe_mcp_event、score_fixture_corpus、data_release_gate、create_field_campaign_template、field_campaign_status、create_guardian_manifest_template、guardian_audit、explain_rule、suggest_fix、security_gate

安装边界

收到 release workflow 生成的精确 wheel 以及随附 requirements-evidence.lock 的用户，可以在没有仓库的情况下按如下方式复现经过审计的 dependency closure。k-guard、k-guard-dashboard、k-guard-mcp、python -m k_guard_mcp.cli、python -m k_guard_mcp.server 是已安装 wheel 的命令。

release 还包含 SHA256SUMS、由 GitHub OIDC 签名的 SLSA provenance bundle、CycloneDX SBOM attestation bundle。在线时，先通过 gh attestation verify ./k_guard_mcp-0.1.0-py3-none-any.whl -R windmillstudio/k-guard-mcp 验证构建主体和 digest，然后安装。仅 checksum 匹配而 attestation 未验证的，不视为官方 release artifact。

python -m pip install --require-hashes -r ./requirements-evidence.lock
python -m pip install --no-deps ./k_guard_mcp-0.1.0-py3-none-any.whl
k-guard --help
k-guard install --client auto --profile local-dev --workspace .
k-guard doctor --client auto

在 Windows 应用程序控制策略阻止 pip 的 k-guard.exe 控制台启动器的受管 PC 上，使用同一 wheel 的模块入口点。功能和判定契约相同。

python -m k_guard_mcp.cli --help
python -m k_guard_mcp.cli install --client auto --profile local-dev --workspace .
python -m k_guard_mcp.cli doctor --client auto

仅安装 wheel 只提供运行时命令。release sdist 和仓库检出包含 scripts/...、tests/fixtures/...、验证模板。开发环境在仓库根目录以 --require-hashes 安装两个 lock 后，用 python -m pip install --no-build-isolation --no-deps -e . 准备。evidence lock 同时固定 release dependency closure 的版本和允许的 SHA-256，许可证·漏洞·SBOM·fresh-wheel smoke 使用同一文件。

안경선배 检查室

要在屏幕上查看受权站点，请运行本地仪表板。

k-guard-dashboard --port 8765

在浏览器中打开 http://127.0.0.1:8765/。屏幕顺序为 선배 判定 → 发现 → 检查日志 → 暴露地图，最终交付权限不在屏幕上，仅在 MCP 的 start_review_before_ship 中。品牌图片是为项目生成的原始资产，provenance 记录在 docs/brand-assets.md 中。

已安装 wheel CLI

以下命令中的 tests/fixtures/korean_fixture_corpus.json 是可在源码检出中直接运行的公开示例 corpus。仅安装 wheel 的用户请替换为相同 schema 的自有 fixture 路径。

python -m k_guard_mcp.cli scan .
python -m k_guard_mcp.cli scan . --json report.json --markdown report.md
python -m k_guard_mcp.cli scan . --sarif k-guard.sarif --fail-on high
python -m k_guard_mcp.cli probe http://localhost:3000
python -m k_guard_mcp.cli probe http://localhost:3000 --deep-active
python -m k_guard_mcp.cli probe http://localhost:3000 --session-file session.headers.json --json
python -m k_guard_mcp.cli probe https://staging.example.com --allow-external --authorization-note "owned staging domain" --json
python -m k_guard_mcp.cli flow . --svg flow.svg --html flow.html
python -m k_guard_mcp.cli observe-mcp --events mcp-events.jsonl --json
python -m k_guard_mcp.cli mcp-proxy --report mcp-proxy-report.json --response-timeout 30 -- python -m your_upstream_mcp_server
python -m k_guard_mcp.cli mcp-http-proxy --upstream http://127.0.0.1:9000/mcp --port 8765 --report mcp-http-proxy.json --receipt-log mcp-http-proxy.receipts.jsonl
python -m k_guard_mcp.cli deep-analyze . --output deep-analyzer.json
python -m k_guard_mcp.cli language-validate --output language-validation.json
python -m k_guard_mcp.cli sca . --output sca.json
python -m k_guard_mcp.cli control-validate --output control-validation.json
python -m k_guard_mcp.cli runtime-validate --output runtime-validation.json
python -m k_guard_mcp.cli access-policy-template --output access-policy.json
python -m k_guard_mcp.cli agent-grant --policy access-policy.json --output agent.jwt --app-id APP --session-id SESSION --purpose RELEASE_REVIEW --subject AGENT --role release-reviewer --method tools/list --method tools/call --tool check_my_app --tool start_review_before_ship
python -m k_guard_mcp.cli score-corpus --corpus tests/fixtures/korean_fixture_corpus.json --output fixture-metrics.json --json
python -m k_guard_mcp.cli benchmark-template --output benchmarks/field-benchmark-template.csv
python -m k_guard_mcp.cli benchmark --manifest benchmarks/field-benchmark-template.csv --output field-benchmark.json --markdown field-benchmark.md --html field-benchmark.html
python -m k_guard_mcp.cli guardian-template --output benchmarks/guardian-targets.csv
python -m k_guard_mcp.cli suppression-template --output .k-guard/suppressions.csv
python -m k_guard_mcp.cli field-campaign-template --output benchmarks/field-app-roster.csv
python -m k_guard_mcp.cli field-campaign-status --roster benchmarks/field-app-roster.csv --output field-campaign-status.json
python -m k_guard_mcp.cli field-validation-template --ground-truth-output benchmarks/field-ground-truth.csv --review-output benchmarks/field-review.csv
python -m k_guard_mcp.cli field-validation-sign --ground-truth benchmarks/field-ground-truth.csv
python -m k_guard_mcp.cli field-validation-preregister --roster benchmarks/field-app-roster.csv --ground-truth benchmarks/field-ground-truth.csv --custodian-id split-custodian-a --output benchmarks/field-preregistration.json
python -m k_guard_mcp.cli guardian --manifest benchmarks/guardian-targets.csv --output guardian-report.json --markdown guardian-report.md --html guardian-report.html
python -m k_guard_mcp.cli guardian --manifest benchmarks/guardian-targets.csv --suppressions .k-guard/suppressions.csv --fail-on high --run-probes --run-sca --language-validation-report language-validation.json --mcp-http-proxy-report runtime-validation.json --control-validation-report control-validation.json --field-validation-report field-validation.json --output guardian-gate.json
python -m k_guard_mcp.cli field-validation-queue --guardian-report guardian-gate.json --output benchmarks/field-review.csv
python -m k_guard_mcp.cli field-validation-sign --review benchmarks/field-review.csv
python -m k_guard_mcp.cli field-validation-report --guardian-report guardian-gate.json --repeat-guardian-report guardian-gate-repeat.json --roster benchmarks/field-app-roster.csv --ground-truth benchmarks/field-ground-truth.csv --review benchmarks/field-review.csv --preregistration benchmarks/field-preregistration.json --profile field --output field-validation.json
python -m k_guard_mcp.cli mcp-intercept --events mcp-events.jsonl --forwarded-output forwarded.jsonl --report intercept-report.json --app-id YOUR_APP_ID --session-id RELEASE_SESSION_ID --guardian-report guardian-gate.json --fail-on-block
python -m k_guard_mcp.cli data-release-gate --guardian-report guardian-gate.json --guardian-manifest .k-guard/guardian-targets.csv --validation-source-guardian-report validation-source-guardian.json --validation-repeat-guardian-report validation-source-guardian-repeat.json --validation-report field-validation.json --validation-review benchmarks/field-review.csv --validation-ground-truth benchmarks/field-ground-truth.csv --validation-preregistration benchmarks/field-preregistration.json --validation-roster benchmarks/field-app-roster.csv --korean-fixture-corpus tests/fixtures/korean_fixture_corpus.json --korean-corpus-report fixture-metrics.json --mcp-intercept-report intercept-report.json --mcp-forwarded-output forwarded.jsonl --output data-release-gate.json

session.headers.json 是短生命周期的，且绑定到唯一精确 origin。Guardian 仅在断言身份响应也匹配时，才将认证比较视为完成：

{
  "origin": "http://localhost:3000",
  "expires_at": "2026-07-14T12:30:00+09:00",
  "headers": {"Cookie": "session=<local-test-session>"},
  "identity_assertion": {
    "path": "/api/me",
    "expected_status": 200,
    "expected_body_sha256": "<64 lowercase hex characters>"
  }
}

将文件保留在被调用的 workspace 内，或 Guardian manifest 旁边。边界之外的文件、链接、过期会话、origin 不匹配、不支持的 header、以及超大文件都会 fail closed。digest 覆盖 UTF-8 解码之前的精确有界响应字节；原始会话值和响应体不会写入 findings。

仅源码检出验证

以下 scripts/** 和 pytest 不是 wheel 中包含的用户命令。

python -m pytest -q
python scripts/site_scale_calibration.py
python scripts/deep_probe_synthetic_calibration.py --targets 500 --output tmp/deep-probe-synthetic-500.json --markdown tmp/deep-probe-synthetic-500.md --html tmp/deep-probe-synthetic-500.html
python scripts/inner_core_product_gate.py --targets 500 --output tmp/inner-core-product-gate-500.json --markdown tmp/inner-core-product-gate-500.md --html tmp/inner-core-product-gate-500.html
python scripts/mcp_evasion_calibration.py --output evidence/regression/mcp-evasion-normalization.json
python examples/contest-demo/v1/demo.py run
python scripts/contest_readiness.py --output contest-readiness-report.json --markdown contest-readiness-report.md
python scripts/build_top_domain_manifest.py --output datasets/tranco-passive-homepage-10k.csv --limit 10000
python scripts/passive_homepage_calibration.py --targets datasets/tranco-passive-homepage-10k.csv --output reports/passive-homepage-10k-summary.json --checkpoint-jsonl reports/passive-homepage-10k-checkpoint.jsonl --max-targets 10000 --delay-ms 500

整个源码回归的 Coverage 门禁 90.00% 是同时计算 statement 和 branch opportunity 的 branch-inclusive combined coverage。这并不意味着 branch 本身达到 90%；由于使用 precision=2 和 fail_under=90，89.90% 会失败。公开仓库 CI 的 public_source_only 范围排除单独分发证据·native case，因此应用整体 88%、redaction.py 85% 阈值，两者不可互换声称。

源码检出 Release Hygiene

在 CTO 审查或发布准备之前，请使用 release hygiene 检查：

python scripts/release_hygiene.py --json

默认模式验证脏的 release-candidate worktree 已被分类、没有可见的运行时临时输出、没有未解决的 review-required 工件。在预期的 release commit 之后使用 --strict-clean；严格模式还会将每个包构建输入字节与 Git index blob 进行比较。打标签发布额外要求 --expected-tag v{project.version}，且该精确标签必须解析到已检出的 HEAD commit。release workflow 等待可复用的 Windows/macOS/Linux CI 矩阵、创建 attestation、并将标签工件发布为 GitHub Release。详情见 docs/release-hygiene.md。

Guardian Actions 模板当前安装由 workflow commit 选择的精确 K-Guard 源码检出；它不假设 PyPI 包。在复制到其他仓库之前，请将 K-Guard 供应商到 commit 固定的路径，并设置 K_GUARD_SOURCE_PATH。release 工件存在后，消费者应固定精确 wheel 加其已发布 SHA-256，或在直接引用 requirement 中固定完整的 40 字符 Git commit。仅将占位符替换为实际 release 位置：

k-guard-mcp @ https://<artifact-host>/<exact-wheel>.whl#sha256=<published-sha256>
k-guard-mcp @ git+https://<repository-url>.git@<40-character-commit>

K-Guard 的主要许可证为 MIT。Apache-2.0 上游归属、经审查的修订、修改文件映射以及排除的许可证边界记录在 THIRD_PARTY_NOTICES.md 和 docs/upstream-adoption.md 中。

MCP

python -m pip install --require-hashes -r requirements-build.lock
python -m pip install --require-hashes -r requirements-evidence.lock
python -m pip install --no-build-isolation --no-deps .
k-guard-mcp

MCP probe_http 默认禁用。仅在受信任的审计会话中启用：

K_GUARD_MCP_ENABLE_PROBE=1 python -m k_guard_mcp.server

通过 MCP 进行经过身份验证的只读探测还需要 K_GUARD_MCP_ENABLE_SESSION_PROBE=1 以及一个短时、绑定来源的本地 session_file。标头值在本地读取，不会写入发现结果。仅凭标头永远不能证明登录状态：Guardian 要求可选的 identity_assertion 匹配后，经过身份验证的比较覆盖才能通过。

通过 MCP 进行有界深度主动探测还需要 K_GUARD_MCP_ENABLE_DEEP_ACTIVE_PROBE=1 和 probe_http(..., deep_active=true)。此模式检查一小部分固定的暴露环境变量/git/备份/调试路径，并且仍然避免登录尝试、变更、模糊测试和漏洞利用载荷。

通过 MCP 进行授权的外部探测还需要 K_GUARD_MCP_ENABLE_EXTERNAL_PROBE=1，以及 K_GUARD_MCP_EXTERNAL_ALLOWED_HOSTS=example.com,staging.example.com 或每次调用时使用 external_authorized=true 并附带 authorization_note。报告以 DYN_EXTERNAL_TARGET_AUTHORIZATION_AUDIT 记录授权依据。

安装与连接针对 ChatGPT、Grok、Codex、Antigravity 四个客户端进行了适配，详细步骤见 docs/quickstart-ko.md 和 docs/mcp-client-install.md。

准备竞赛结果报告和实际兼容性证据时，使用 docs/contest-2026-result-report-draft-ko.md 和 docs/client-interop-evidence-kit-ko.md。实际兼容完成仅统计同时具备各客户端 install → restart → tool list → check_my_app → reconnect 录屏、唯一 SHA-256 和独立审查的范围。

MCP 调用默认还强制执行参数和内联文本预算：

• K_GUARD_MCP_MAX_FILES=1000

• K_GUARD_MCP_MAX_MB=10

• K_GUARD_MCP_MAX_TEXT_MB=1

• K_GUARD_MCP_MAX_ARG_CHARS=4096

• K_GUARD_MCP_GUARDIAN_MAX_TARGETS=100

• K_GUARD_MCP_GUARDIAN_MAX_REQUESTS=200

Guardian MCP 调用会针对目标、过滤文件、字节和预计 HTTP 请求预算对整个清单进行预检。文件展开被限制在配置上限加一条检测记录，因此过大的目录树会在枚举整个目录树之前被拒绝。过大的多目标工作返回 Guardian 格式的失败关闭报告；对于有意更大的批次，请使用 CLI 或拆分清单。动态 HTTP 检查默认每个响应最多读取 1 MiB，并且每次探测运行在 16 MiB、80 个请求或 30 秒处停止。

安全默认值

• JSON/Markdown/MCP 输出通过集中式脱敏层

• SARIF 输出也通过相同的脱敏层，并存储无原始数据的证据

• 动态探测默认仅允许 localhost、127.0.0.1 和 ::1

• 外部动态探测需要明确的授权证据和选择加入，然后保持固定路径、只读、同源且不重定向。每个请求仅解析允许列表中的公共地址，并连接到选定的已验证 IP，同时保留原始 HTTP Host/TLS SNI。

• 动态探测不跟随到非允许列表主机的重定向

• 动态探测仅使用非破坏性 HTTP 方法

• --deep-active 是对常见暴露的 .env、.git/config、备份/转储以及调试/运行时路径的有界授权检查。它不是递归爬取、密码猜测、漏洞利用载荷或路径暴力破解字典。

• 动态探测使用超时并限制采样的响应体

• 不执行外部密钥有效性检查

严重性和置信度

严重性值集中验证：

• critical：凭据/私钥/数据库 URL 暴露、直接的高风险标识符或未经身份验证的敏感路由

• high：强识别组合、有风险的 localhost 暴露或敏感流程候选

• medium：独立的联系/位置/配置信号和加固发现

• low：弱启发式信号

• info：信息性观察

置信度值为 high、medium 和 low。

数据流和内核限制

流程映射明确标记为 EXPERIMENTAL，并标注为 heuristic+ast-taint+js-ts-taint，精度为 line-distance+python-intra-procedural-ast+js-ts-intra-file+limited-interprocedural-taint。 它是开发者的分诊辅助工具：支持 Python AST 污点分析，JS/TS 现在具有轻量级文件内污点分析、有限的路由到服务摘要，以及针对 Next.js 路由处理器/服务器操作、Express IDOR 形路由参数、Supabase service-role/RLS 边界提示和 Firebase Admin 认证边界提示的框架感知启发式。完整的 TypeScript 类型检查、别名完整的导入解析、中间件证明、已部署的 RLS/Firebase 规则证明以及完整的跨过程污点分析仍是路线图项目。 流程发现包括无原始数据的源/汇行哈希，以便在不回显敏感值的情况下使证据可复现。 流程可视化生成为本地 SVG/HTML，不依赖外部 JavaScript 或 CDN。相同的脱敏层保护 JSON、Markdown、SVG、HTML 和 MCP 响应。

运行时 MCP 观察通过 observe_mcp_events 摄取 JSONL/JSON 事件导出，也可以通过 observe_mcp_event(session_id=...) 一次评估一个事件。CLI mcp-intercept 在写入转发的 JSONL 之前，将那些 block 和 redact 决策应用于批量事件流。CLI mcp-proxy -- <upstream argv> 是行分隔 stdio JSON-RPC 的实时执行路径。CLI mcp-http-proxy --upstream <URL> 在 Streamable HTTP POST、GET SSE 和 DELETE 会话生命周期中执行相同的策略，并具有官方 Python MCP SDK 互操作性覆盖。两个代理都发出相同的无原始数据、事务关联的 HMAC 收据链，用于访问拒绝和内容允许/脱敏/阻止决策；配置的 sidecar 持久化在转发之前发生，并失败关闭。操作员密钥验证对于防篡改声明是必需的，因为 HMAC 是共享密钥标签，而非公钥签名。两个代理在无效帧、关联错误、大小或超时限制以及传输控制失败时均失败关闭。流式观察器状态具有有界的空闲/LRU 会话保留。MCP enforce_mcp_events 仍仅为报告模式。二进制帧、非标准传输以及适用于每个 MCP 客户端的通用即插即用代理仍是路线图工作。

只读连接器仅检查本地 SQLite/日志/存储文件。远程 Postgres/Supabase/Firebase/S3、备份和实际删除执行是路线图项目。

反馈漂移循环

k-guard feedback --type fn --rule PII_PHONE --text "missed sample" --output feedback.jsonl
k-guard feedback-export --input feedback.jsonl --output feedback-summary.json --reviewed

反馈文件在写入前经过清理，并在本地汇总用于语料库调优。假阴性片段使用额外的保守令牌掩码，因为检测器可能漏掉了敏感值。 feedback-export 需要 --reviewed 或 K_GUARD_FEEDBACK_EXPORT_REVIEWED=1，以便意外的自动导出失败关闭。在将 feedback-summary.json 共享到合作伙伴环境之外之前，请先审查；不要传输原始 feedback.jsonl。

现场基准测试

benchmark-template 创建 20/20/10 清单：

• 20 个通用基线站点或报告

• 20 个 vibe-coded 疑似站点或报告

• 10 个自有、合作伙伴批准或漏洞赏金范围内的目标

benchmark 聚合无原始数据的 K-Guard JSON 报告，并且仅在 --run-probes 时聚合标记为 mode=probe 的授权清单行。它按队列报告高/严重目标率、强标识符检测率、顶级规则和人工误报率。默认路径仅为报告模式，因此基准测试工作可以从仪表板导出开始，而无需接触外部站点。

相同的工作流可通过 MCP 以 create_benchmark_template 和 field_benchmark 使用。MCP 基准测试探测需要与 probe_http 相同的显式探测选择加入。

Guardian 模式

guardian-template 为持续产品守护创建授权目标清单。一行可以指向本地工作区、HTTP 来源、MCP 运行时 JSONL 导出或现有的无原始数据 K-Guard JSON 报告。guardian 将所有行聚合为一个无原始数据的报告，包含每个目标的门禁、新增/已解决发现漂移、顶级重复规则以及来自 suggest_fix 的修复方案。

Guardian 清单还携带无原始数据的业务意图和范围断言字段：business_purpose、data_classes、user_scope、public_endpoints、scope_basis 和 scope_proof_ref。K-Guard 不声称具有人类级别的业务理解或自行证明所有权；它记录这些断言是否存在，并且仅存储哈希引用。范围完成需要显式的 scope_proof_ref；定位器和遗留授权说明不被视为证明。数据发布门禁要求这些目标级契约和经过验证的操作员密钥证据包，其工件哈希与当前报告匹配，然后才将报告视为发布证据。

新模板设置 audit_profile=korean_senior。在此配置文件中，发布门禁不会仅仅因为发现零个阻止项而通过。它还需要一个实质性的工作区，其中至少包含一个受支持且成功解码的生产源文件、流程分析、完成的深度 HTTP 审查、声明的端点路径实际返回 2xx/3xx/401/403 而不仅仅是 404，以及明确的目的/数据/用户/范围断言。Guardian 在审计之前和之后立即对每个工作区进行内容哈希；不匹配会发出 GUARDIAN_SOURCE_CHANGED_DURING_AUDIT，阻止该目标，并将该运行排除在实质性覆盖之外。对于发布权限，请使用不可变的 CI 检出。报告为 site_security、api_exposure、data_management 和 operational_risk 暴露 review_contract.domains；当任何必需域不完整时，guardian_gate.passed 保持为 false。没有 audit_profile 的遗留清单保持在较窄的 standard 配置文件中，不得呈现为四域高级覆盖。

public_endpoints 是可执行的审查范围，而非装饰性元数据。Guardian 安全地将该字段中的有效同源路径添加到固定的 GET/OPTIONS 探测集（最多 50 个；不允许绝对 URL、父级遍历或模板化路径）。这使 API 审查能够覆盖应用特定的只读端点，同时保持探测有界。

当 HTTP 行包含 session_file 时，Guardian 运行相同的有限路径集两次：一次未认证，一次使用操作员提供的只读会话。这使公共暴露检查保持可见，而不是用仅认证视图替换它们。会话必须同时证明认证墙转换和声明的身份响应摘要。当任一证明缺失、探测产生请求或控制错误，或未达到有效的声明端点范围时，korean_senior 门禁会拒绝 HTTP 覆盖。

guardian --fail-on high 是规范的发布前门禁。当 K-Guard 应决定目标应用是否可以在配置的阈值下发布时，应使用此工作流。仅工作区的 scan --fail-on 和 MCP security_gate 是快速检查；它们不替代 Guardian 的清单、覆盖缺口、漂移和多目标执行契约。

默认情况下，guardian 写入报告并成功退出，以便团队可以审查发现结果而不会将其变成发布阻止项。当同一报告应作为 CI 门禁时，使用 --fail-on high；当存在阻止目标或新的阻止发现时，它以代码 3 退出。在没有 --previous 的首次运行时，报告是 initial_snapshot：当前的阻止项和覆盖缺口仍然可以使门禁失败，但 K-Guard 不会将每个当前发现标记为新的漂移。在门禁模式下，清单中的 HTTP 行必须通过 --run-probes 实际执行，否则它们将成为覆盖缺口而不是静默通过。

除非传入 --run-probes，否则不会执行 HTTP 行。CLI 路径面向受信任的本地操作员，并以显式 CLI 标志/清单行作为其选择加入机制。MCP 由代理中介且更为严格：guardian_audit(..., run_probes=true) 需要 K_GUARD_MCP_ENABLE_PROBE=1；请求外部、深度主动或会话探针的清单还分别需要 K_GUARD_MCP_ENABLE_EXTERNAL_PROBE=1、K_GUARD_MCP_ENABLE_DEEP_ACTIVE_PROBE=1 或 K_GUARD_MCP_ENABLE_SESSION_PROBE=1。Guardian 模式仍使用固定的安全 GET/OPTIONS 探针，不执行登录尝试、密码猜测、变异、漏洞利用载荷、递归爬取或跨主机重定向跟随。

MCP 客户端应向 guardian_audit 传入 fail_on="high"，以在 guardian_gate.passed 中获得规范的发布门禁判定；进程退出码仍属于 CLI 关注事项。使用 --previous previous-guardian-report.json 将报告转变为漂移监控器。仅当加载了先前报告时，新的阻塞性发现才会单独列出；当这些发现应阻止发布时，请将 --previous 与 --fail-on 结合使用。如果 MCP 控制检查在目标执行前停止 guardian，报告模式和门禁模式都会返回包含 execution_contract、summary 和 findings 的 guardian 形状响应；门禁模式还额外包含 guardian_gate.passed=false。报告包含 execution_contract 部分，使跳过、出错和已执行的目标在一处可见，包括 Markdown 和 HTML 导出。

MCP security_gate(path, fail_on) 是一个快速的工作区专用门禁。它现在在 MCP 控制失败时返回 security_gate.passed=false，例如无效阈值、参数预算、工作区预算限制或扫描异常，但它有意报告 coverage_model="workspace_only"。对于需要 HTTP 目标、MCP 运行时导出、先前报告或覆盖缺口核算的发布决策，请使用 Guardian。

抑制策略为失败关闭（fail-closed）。suppression-template 创建一个 CSV，将每个豁免绑定到 app_id、audit_profile、当前源快照或审查证据哈希、target_id、发现指纹、所有者、原因和未来到期时间。豁免不能针对其他应用或更改后的发布快照重放；无效、过期或已到期的行会添加高严重性策略发现。抑制不能清除 Guardian 覆盖缺口或 MCP 控制失败规则。field-validation-queue 导出每个高/严重候选，包含脱敏指纹、检测器子类型、工件范围、文件/正文/头部位置类型和可用的响应哈希。严格的 field-validation-report --profile field 声明保持关闭，直到 12-20 个自有/合作伙伴应用、120 个已标注案例、50 个阳性、40 个阴性、五个严重案例、三个分层、一个至少包含 70 个案例、35 个阳性、35 个阴性和 35 个候选的预注册保留集、角色分离的审查员/保管人签名，以及一次精确的第二次规范 Guardian 执行全部通过固定阈值。总体/保留集精确率、保留集高/严重召回率和保留集特异度必须同时通过点估计和 Wilson 95% 下限；严重保留集召回率保持恰好 1.0。每个候选必须恰好绑定到一个冻结的开发/保留集范围。候选 (false_positive + benign) / (true_positive + false_positive + benign) 报告为错误发现率；假阳性率仅对干净案例计算，为 FP / (FP + TN)。数据发布门禁更为严格：任何已知的假阴性或良性高/严重候选都会阻止发布。K_GUARD_FIELD_REVIEWER_HMAC_KEYS 和 K_GUARD_FIELD_CUSTODIAN_HMAC_KEY 必须与操作员证据密钥不同；这些本地 HMAC 分离角色，但不证明现实世界身份或密码学上独立的执行。旧版 validation-* 命令仅聚合候选标签，无法建立现场召回率。

公开的自动阻止资格合同与现场验证是分开的。release_blocker_actionability_v3 要求至少 100 个自动阻止器的预注册普查、0.90 的候选可操作性，以及 0.80 的 Wilson 95% 下限。它还要求至少 20 个应用中有自动阻止器。只有当应用中的每个自动阻止器都被标注为 true_positive 时，该应用才算完全可操作；其完全可操作应用率和 Wilson 下限都必须通过 0.90 和 0.80。这种应用级敏感性门禁防止一个仓库中数十个相关行产生虚假的统计置信度。人工审查和政策完整性保留仍为失败关闭，但被排除在自动阻止可操作性之外。

完整的证据层级、首次基线、标注和重复运行合同记录在 docs/field-validation-v2-ko.md 中。

data-release-gate 更为严格：它要求 K_GUARD_EVIDENCE_HMAC_KEY、原始 Guardian 清单、绑定到当前报告的规范 high Guardian 声明、目标证据和源快照、分别签名的初级和重复验证源 Guardian 原件、精确的地面真值/审查员 CSV、原始保管人预注册、韩语语料库证据，以及实际的 MCP 拦截器转发流。它从这些原件重新运行现场验证，重新验证审查员/保管人 HMAC，并要求重新计算的投影等于提交的报告。它还重新打开重复 Guardian，并独立检查内容、捆绑包、执行证明、工具链、清单、源/HTTP/MCP 输入和精确的候选多重集。设计合作伙伴验证有意独立于当前正在发布的单个应用；其候选应用/目标/发现引用必须与验证源 Guardian 报告匹配，不得伪装为发布应用覆盖。可复用的 GitHub Actions 模板位于 docs/templates/github-actions/guardian-release-gate.yml。

未认证的 JSON 按风险拆分。敏感/私有记录结构保持为高严重性的 DYN_UNAUTH_API_JSON；没有这些指标的 JSON 变为信息严重性的 DYN_PUBLIC_API_JSON_REVIEW，因此有意的公共 API 不会仅仅因为返回 JSON 而阻止发布。

scripts/site_scale_calibration.py 为大型通用 HTML 噪声、中型公共联系页面、小型 vibe 编码批量 JSON、有效的强标识符和银行账户 JSON 运行本地黑盒 HTTP 夹具。它不使用外部网络访问。

scripts/deep_probe_synthetic_calibration.py 通过相同的仪表板 scan_url(..., deep_active=True) 路径运行本地合成回环校准框架。默认证据运行在 24 个有界场景中使用 500 次回环调用；这不是 500 个真实网站，不是漏洞发现，也不是渗透测试。它涵盖 .env、.git/config、备份 SQL、调试端点、管理员/API 暴露、OpenAPI、源映射、CORS、重定向、PII/秘密响应层级，以及登录墙、SPA 外壳和 HTML 回退的假阳性控制。它还包括阴性对照，证明预期与观察评分器能够检测注入的缺失和意外规则。它不使用外部网络访问；真实的外部深度探针仍需要明确的目标授权。

scripts/inner_core_product_gate.py 为"内核心"审计声明运行更广泛的本地合成产品门禁。它将 500 目标回环深度探针校准与静态代码/配置/MCP 文本检查、Python AST 污点分析、MCP 运行时 JSONL 观察、只读 SQLite/日志/存储连接器、保留/删除审查、跨平面 PII 到代理/外部判定，以及无原始证据图检查相结合。此门禁必须具有零缺失必需规则、零意外深度探针规则、通过的阴性对照、非空的流图节点/边，以及序列化报告中无禁止的原始标记。它是产品深度门禁，不是第三方网站漏洞发现的证明。

CI 工作流在推送/拉取请求时运行完整的 pytest 套件以及 24 目标内核心门禁，该门禁覆盖每个合成场景一次。计划/手动审计工作流运行 500 目标内核心门禁并上传其 JSON/Markdown/HTML 证据包。仓库自 SARIF 扫描作为非门禁证据上传，因为此扫描器仓库有意包含应触发 K-Guard 发现的检测器规则、夹具和文档示例；请对正在审计的产品使用 --fail-on，而不是对 K-Guard 自身夹具繁重的源树使用，除非存在项目特定的基线。

scripts/passive_homepage_calibration.py 从 CSV 清单运行仅 GET / 的主页校准。它支持 --max-targets、--delay-ms、--checkpoint-jsonl 和 --resume，用于 10k 规模的分片运行。它报告队列、排名桶、结果和卫生层级聚合，例如 well_managed_quiet、hardening_gap、boundary_redirect 和 messy_or_risky_signal，因此嘈杂的管理良好的网站和混乱的长尾网站可以分别校准。它还发出一个 release_gate，包含对测量产出、高/严重率、强标识符率和边界重定向率的通过/警告/失败检查。它不请求 /admin、/api、.env、.git、OPTIONS 或递归路径。

scripts/build_top_domain_manifest.py 从公共顶级域 CSV 或 ZIP 源自动创建该被动校准清单。默认源是 Tranco 最新的 top-1m ZIP，因此操作员无需手动收集 10,000 个 URL。使用 --start-rank 构建长尾混乱候选队列，例如排名 900,001 到 910,000。也可以使用 --source-url 提供 Majestic Million 风格的 CSV。

仅 AI 竞赛 RC 证据

竞赛 RC 将开发证据保持在独立轨道中，而不是发布一个汇总的准确率数字：

python scripts/qualify_korean_privacy_ai_only.py --output evidence/qualification/korean-privacy-ai-only-v1.json
python scripts/ai_public_benchmark_scorecard.py --output evidence/qualification/ai-public-benchmark-scorecard-v1.json
python scripts/benchmark.py --profile contest --output benchmark-report.json

• 韩语资格报告将 117 个夹具案例和冻结的 68 个案例评估者撰写的保留集作为独立轨道。它还检查五个工作区合同、四个官方唯一标识符概念、企业/公司编号边界和六个敏感词汇表面。它不发布汇总的混淆矩阵，也不声称盲测、人工裁决、注册表、合作伙伴或现场准确率。

• 公共记分卡分别保留当前和历史轨道。当任何选定的历史工件存在摘要或绑定不匹配时，--require-integrity-pass 会故意失败；仍然可以生成报告，因此不可采信的历史结果保持可见，而不是被静默重写或丢弃。

• 竞赛性能配置文件在一个公开的主机上测量精确的合成全良性低信号语料库，包括新进程冷启动和持久扫描器热启动延迟、10/50/100 MiB 扩展、进程内 CPython 线程并发 1/4/8、峰值 RSS、完整候选覆盖和无原始结果不变性。它不测量发现密集扩展、进程级并行、生产 SLO、现场准确率、硬件归一化比较或第三方优越性。

当前限制

• 产品加固路线图：docs/pre-release-auditor-hardening-plan-ko.md

• PDF/DOCX/HWP 提取尚未包含

• 动态检查仅限 localhost，除非明确列入白名单，或由操作员对自有、合作伙伴批准或漏洞赏金范围内的外部目标进行认证

• 用户提供的会话头仅附加到只读 GET 请求，且头值不会被存储

• JS/TS 污点分析是保守且轻量的，包含文件内污点、有限的路由到服务摘要，以及针对常见 Next.js/Express/Supabase/Firebase 边界错误的框架感知启发式规则；Python AST 污点分析是过程内的

• 运行时 MCP 观察和 MCP enforce_mcp_events 工具仍为建议性质；mcp-proxy 和 mcp-http-proxy 对行分隔的 stdio JSON-RPC 和经过测试的 Streamable HTTP 生命周期执行实际的双向强制。二进制帧、非标准传输以及适用于每个客户端的通用即插即用代理仍不在强制边界之内

• 远程数据库/存储/备份和实际删除执行尚未验证

• 韩语 PII 模式基于规则，需要针对项目特定的误报调优

• 韩语企业注册号在合成/供应商编写的测试数据上使用校验和语法验证。历史企业注册号（2025-01-31 之前签发）可能使用旧的附件交替 1,2 加权校验和。自 2025-01-31 起，当前企业编号为 4 位注册机构 + 2 位类型 + 7 位序列号，无校验和，因此检测仅为显式字段上下文/语法识别。这些都不是自然人 PII、实时注册表验证或独立字段验证。仅上下文的当前值属于未经验证的语法/上下文识别。隐私优先的歧义处理：合理的韩语 RRN/FRN 优先于企业或商业标签、头部或拆分 JSON 键，且绝不会被分类或编辑为组织 ID。

• 评估者编写的 68 例韩语敏感/组织保留集（evidence/holdout/korean-sensitive-org-v1.cjson）是对合成预言机的实现后检查，而非盲测字段准确性或注册表验证研究。当每个 must_all 规则都存在、每个 must_any 组至少有一个匹配规则、且没有 forbidden 规则出现时（逐例任意规则召回），该案例即通过。通过此检查后，冻结的清单得分为 68/68，召回率 1.0，特异性 1.0，且两次运行完全重复。这并不代表实时字段准确性的声明。