K-Guard MCP

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

만드는 흐름은 끊지 않고, 출하는 대충 넘기지 않습니다.

K-Guard MCP es un auditor MCP local-first que revisa el sitio, la exposición de API, la gestión de datos y el riesgo operativo antes de enviar los resultados de vibecoding. Guardian distingue entre lo que no tiene problemas y lo que aún no se ha visto, y devuelve el veredicto 출하 가능 / 고치고 출하 / 검수 범위 부족 y las siguientes acciones en coreano.

K-Guard no es una garantía que reemplace el juicio empresarial humano ni la revisión legal. Automatiza las preguntas que un desarrollador senior hace antes del envío y las compuertas fail-closed.

5분 설치 · 설치·디자인 검증 · 사용 가이드 · GitHub 공개 안내 · 필수 qualification · 제품 북극성 · 전체 도그푸드 판정 · 2026 대회 출품 준비

Primeros 5 minutos: checkout del código fuente actual

Todavía no se asume la distribución en un índice público de paquetes. En la primera ejecución, instala el código fuente actual desde la raíz del repositorio y sigue las siguientes acciones que te muestra 안경선배.

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

auto busca Grok, Codex y Antigravity instalados, fusiona el MCP k-guard en el ámbito del usuario y, si existe tunnel-client de OpenAI, prepara un perfil local para ChatGPT. --workspace . fija el proyecto actual como un binding privado. A partir de entonces, aunque el MCP se inicie desde otro directorio de trabajo, inspeccionará este proyecto y rechazará las rutas fuera del límite con un HOLD alto. Para el doctor/run de ChatGPT, también se necesita CONTROL_PLANE_API_KEY con permisos de Tunnels Read + Use en el shell actual. Como ChatGPT deja pendientes tunnel-client run y la conexión de la app en modo desarrollador, el instalador no lo presenta como un éxito y devuelve 부분 연결 · 다음 단계 필요. Se conserva la configuración existente y se crea una copia de seguridad antes de cualquier cambio en JSON; las claves de evidencia del operador y el texto original del workspace se guardan solo en archivos exclusivos del usuario en ~/.k-guard. local-dev solo activa la sonda read-only de localhost y un pequeño conjunto fijo de rutas de profundización, manteniendo desactivadas las sondas externas y de sesión. Si solo se necesita análisis estático, usa --profile workspace.

La salida básica de instalación y diagnóstico tiene tres pasos: 연결 준비 → AI 클라이언트 → 다음 행동. Para automatización, usa install --json y doctor --json. Para la reproducción de la evaluación del concurso, la reproducción del release y la modificación de código, usa la ruta de verificación de evaluación y reproducción de la instalación de 5 minutos para instalar el build y el evidence lock con --require-hashes. Semgrep 1.174.0 y pip-audit 2.10.1 también se instalan en un venv aislado con el cierre completo de hashes de requirements-semgrep.lock y requirements-pip-audit.lock respectivamente, sin modificar el runtime auditado.

En el cliente 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 no es una inspección que se termina a la ligera en 5 segundos, sino una herramienta que recibe la auditoría completa del workspace. La primera respuesta es review_in_progress y no se emite un veredicto de envío hasta que continue_review se complete. También se inspeccionan los artefactos de texto de distribución en dist, build y .next; si el número de candidatos, el SHA-256 de las rutas y la finalización de la lectura no coinciden, se bloquea con severidad alta. El resultado final produce un review_receipt vinculado al SHA-256 del workspace y del árbol fuente. Si el código cambia, no se puede iniciar la revisión de envío con el review_id anterior y hay que completar check_my_app de nuevo.

Related MCP server: Secure Code Review MCP Server

Veredicto de 안경선배

Todos los resultados representativos proporcionan experience.presentation y el alias compatible experience.details.presentation, con el orden fijo verdict → why → next_actions → details. Guardian muestra el riesgo de la app como application_assurance y el estado de validación de la propia herramienta de auditoría como auditor_qualification, por separado. experience.verdict_code, experience.verdict_message y experience.summary son campos compatibles con informes existentes.

Qué examina

K-Guard combina:

• Escaneo estático: PII coreana, PII compuesta, identificadores de organizaciones coreanas (validación sintáctica de checksum de 사업자등록번호; reconocimiento sintáctico/contextual del anexo histórico de 법인등록번호 o del formato 4+2+7 posterior al 2025-01-31, no validación en registro en vivo), secretos

• Escaneo de configuración: riesgos de CORS/debug/source map/prefijo de entorno

• Escaneo senior de riesgo de app: sinks directos de request a SQL/comando/archivo/URL/HTML, mass assignment, open redirect, almacenamiento de tokens en navegador, cookies débiles, comparación de contraseñas en texto plano y JWT decode-sin-verify

• Escaneo de gobernanza de datos coreana: declaraciones de campos únicos/sensibles, evidencias de cifrado/control de acceso, registro de accesos, revisión de procesadores externos, retención y borrado

• Escaneo de amenazas nativas de MCP: instrucciones ocultas, envenenamiento de herramientas, intención de exfiltración y acceso local excesivo en texto directo más normalización acotada Unicode/confusable, escapada/porcentaje/HTML, Base64, fragmentos divididos y de tres líneas rodantes

• Revisión estructurada de configuración MCP: wrappers de shell, lanzadores de paquetes mutables, HTTP remoto en claro, credenciales fijas, enlaces inseguros/fallos de lectura y límites de descubrimiento fail-closed en candidatos de configuración de proyecto/Codex/Grok/Antigravity

• Paquete de reglas locales YARA-lite: marcadores de prompt injection, marcadores de comandos de exfiltración, pistas de esquemas masivos coreanos

• Sonda dinámica segura: comprobaciones HTTP en localhost, comprobaciones de orígenes externos explícitamente autorizados, comprobaciones opcionales acotadas de exposición profunda, más cabeceras de sesión read-only opcionales proporcionadas por el usuario

• Mapa de riesgo de flujo de datos: grafo heurístico más análisis de taint source -> sink en AST de Python y JS/TS ligero, incluidos resúmenes de parámetro-a-sink de helpers de Python con import único y resúmenes limitados de IDOR de ruta-a-servicio en JS/TS

• Observador/Interceptor de runtime MCP: comprobaciones de eventos JSON/JSONL y listos para stream para instrucciones ocultas, flujo de PII a sinks agénticos/externos, más aplicación de bloqueo/redacción por lotes para flujos de eventos reenviados

• Adaptador profundo Semgrep: perfil offline de 40 reglas, prueba exacta del objetivo escaneado, identidad fijada 1.174.0, vinculación de instantánea de fuente y hallazgos fail-closed en JS/TS/Python/Java/Kotlin/Go/PHP/Ruby/C#

• Paquete de validación de nueve lenguajes: 90 casos fijados vulnerables/limpios en Python/JavaScript/TypeScript/Java/Kotlin/Go/PHP/Ruby/C#, puntuación TP/FN/FP/TN y reproducción exacta de huella en dos ejecuciones

• Análisis de composición de software: cobertura acotada de manifiestos y locks de Python/npm/Go con pip-audit, npm audit y govulncheck; el fallo parcial del motor, el lock, la salida o la deriva de fuente bloquea el release

• Proxy MCP HTTP streamable: mediación completa de POST/GET SSE/DELETE, ciclo de vida vinculado al principal, concesiones JIT/JEA de denegación por defecto, inventario de herramientas filtrado, streams acotados y registros de auditoría sin datos brutos encadenados con HMAC

• Controles de base de datos: allowlist AST de SQLGlot, RBAC de rol/base de datos/esquema/tabla/columna, EXPLAIN-antes-de-leer, autorizador de solo consulta SQLite, contención de rutas y presupuestos de fila/celda/resultado/tiempo

• Conectores de solo lectura: muestreo de almacenamiento local SQLite, log, JSON/CSV/TSV sin almacenamiento de valores brutos; las brechas de conectores se convierten en hallazgos high

• Revisión de retención/borrado: marca la falta de marcadores de retención/borrado cuando existen señales de datos personales

• Veredictos entre planos: correlaciona hallazgos de PII coreana con evidencias de sinks LLM/MCP/externos/en reposo

• Marcador FP/FN: recall del corpus de fixtures y tasa de falsos positivos. El FPR usa measurable_negative_count como denominador (negativos limpios sin expected_absent); negative_count son todos los negativos declarados y targeted_absence_case_count cubre ausencias de reglas seleccionadas que no entran en el denominador del FPR. Un denominador de negativos medibles cero se reporta como FPR 0.0.

• Salida SARIF/CI: falla el build según las severidades configuradas

• Perfil Guardian korean_senior: contrato fail-closed de cuatro dominios para seguridad del sitio, exposición de API, gestión de datos y riesgo operativo

• Herramientas MCP principales: check_my_app, continue_review, start_review_before_ship; motor canónico interno: Guardian high; prompt guiado: guided_review

• Herramientas MCP avanzadas: 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

Límites de instalación

Los usuarios que reciban requirements-evidence.lock distribuido junto con el wheel exacto creado por el workflow de release pueden reproducir el cierre de dependencias auditado sin el repositorio, como se muestra a continuación. k-guard, k-guard-dashboard, k-guard-mcp, python -m k_guard_mcp.cli y python -m k_guard_mcp.server son comandos del wheel instalado.

El release también incluye SHA256SUMS, el bundle de provenance SLSA firmado con OIDC de GitHub y el bundle de attestation SBOM CycloneDX. En línea, verifica el sujeto de construcción y el digest con gh attestation verify ./k_guard_mcp-0.1.0-py3-none-any.whl -R windmillstudio/k-guard-mcp antes de instalar. Si solo coincide el checksum pero la attestation no se verifica, no se trata como un artefacto de release oficial.

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

En PCs gestionados donde la política de control de aplicaciones de Windows bloquea el lanzador de consola k-guard.exe de pip, usa el punto de entrada de módulo del mismo wheel. El contrato de funcionalidad y veredicto es idéntico.

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

Con solo instalar el wheel, solo se proporcionan los comandos de runtime. El sdist del release y el checkout del repositorio incluyen scripts/..., tests/fixtures/... y las plantillas de validación. El entorno de desarrollo se prepara instalando los dos locks con --require-hashes desde la raíz del repositorio y luego python -m pip install --no-build-isolation --no-deps -e .. El evidence lock fija juntos la versión del cierre de dependencias del release y los SHA-256 permitidos; la licencia, las vulnerabilidades, el SBOM y el smoke del wheel fresco usan el mismo archivo.

Sala de revisión de 안경선배

Para ver el sitio autorizado en pantalla, ejecuta el dashboard local.

k-guard-dashboard --port 8765

Abre http://127.0.0.1:8765/ en el navegador. La pantalla sigue el orden 선배 판정 → 발견 → 검사 로그 → 노출 지도, y la autoridad final de envío no está en la pantalla sino solo en start_review_before_ship del MCP. Las imágenes de marca son activos originales creados para el proyecto y su provenance se registra en docs/brand-assets.md.

CLI del wheel instalado

Entre los comandos siguientes, tests/fixtures/korean_fixture_corpus.json es un corpus de ejemplo público ejecutable directamente desde el checkout del código fuente. Los usuarios que solo instalaron el wheel deben reemplazarlo con la ruta de su propio fixture con el mismo esquema.

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 es de corta duración y está vinculado a un único origen exacto. Guardian solo considera completa una comparación autenticada cuando la respuesta de identidad afirmada también coincide:

{
  "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>"
  }
}

Mantén el archivo dentro del workspace invocado, o junto al manifiesto de Guardian. Los archivos fuera de ese límite, los enlaces, las sesiones caducadas, los orígenes no coincidentes, las cabeceras no soportadas y los archivos sobredimensionados fallan de forma cerrada. El digest cubre los bytes exactos de la respuesta acotada antes de la decodificación UTF-8; los valores brutos de sesión y los cuerpos de respuesta no se escriben en los hallazgos.

Validación exclusiva del checkout del código fuente

Los scripts/** y pytest siguientes no son comandos de usuario incluidos en el 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

El gate de cobertura 90.00% de la regresión completa del código fuente es una cobertura combinada inclusiva de ramas que calcula juntas las oportunidades de statement y branch. No significa que las ramas en sí sean 90%, y como usa precision=2 y fail_under=90, 89.90% falla. El alcance public_source_only del CI del repositorio público excluye las evidencias de distribución separadas y los casos nativos, por lo que aplica los umbrales de 88% total y 85% de redaction.py; no se intercambian las dos cifras entre sí.

Higiene de release del checkout del código fuente

Usa la comprobación de higiene de release antes de la revisión del CTO o la preparación de la publicación:

python scripts/release_hygiene.py --json

El modo predeterminado valida que un árbol de trabajo sucio de candidato a release esté clasificado, libre de salida de scratch de runtime visible y libre de artefactos sin resolver que requieran revisión. Usa --strict-clean después del commit de release previsto; el modo estricto también compara cada byte de entrada de construcción del paquete con su blob del índice de Git. La publicación etiquetada además requiere --expected-tag v{project.version}, y esa etiqueta exacta debe resolverse al commit HEAD verificado. El workflow de release espera la matriz CI reutilizable de Windows/macOS/Linux, crea las attestations y publica los artefactos de la etiqueta como GitHub Release. Los detalles están en docs/release-hygiene.md.

La plantilla de Guardian Actions actualmente instala el checkout exacto del código fuente de K-Guard seleccionado por el commit del workflow; no asume un paquete de PyPI. Antes de copiarla a otro repositorio, provee K-Guard en una ruta fijada por commit y establece K_GUARD_SOURCE_PATH. Cuando existan artefactos de release, los consumidores deben fijar o un wheel exacto con su SHA-256 publicado, o un commit de Git completo de 40 caracteres en un requisito de referencia directa. Reemplaza los placeholders solo con una ubicación de release real:

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's primary license is MIT. Apache-2.0 upstream attribution, reviewed revisions, modified-file mapping, and excluded license boundaries are recorded in THIRD_PARTY_NOTICES.md and 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 is disabled by default. Enable it only for trusted audit sessions:

K_GUARD_MCP_ENABLE_PROBE=1 python -m k_guard_mcp.server

Authenticated read-only probing through MCP also requires K_GUARD_MCP_ENABLE_SESSION_PROBE=1 and a short-lived, origin-bound local session_file. Header values are read locally and are not written to findings. A header alone never proves login: Guardian requires the optional identity_assertion to match before authenticated comparison coverage can pass.

Bounded deep active probing through MCP also requires K_GUARD_MCP_ENABLE_DEEP_ACTIVE_PROBE=1 and probe_http(..., deep_active=true). This mode checks a small fixed list of exposed env/git/backup/debug paths and still avoids login attempts, mutations, fuzzing, and exploit payloads.

Authorized external probing through MCP also requires K_GUARD_MCP_ENABLE_EXTERNAL_PROBE=1 plus either K_GUARD_MCP_EXTERNAL_ALLOWED_HOSTS=example.com,staging.example.com or a per-call external_authorized=true with an authorization_note. The report records the authorization basis with DYN_EXTERNAL_TARGET_AUTHORIZATION_AUDIT.

La instalación y la conexión están adaptadas a los cuatro clientes ChatGPT, Grok, Codex y Antigravity; los procedimientos detallados están en docs/quickstart-ko.md y docs/mcp-client-install.md.

Al preparar el informe de resultados del concurso y las pruebas reales de compatibilidad, utilice docs/contest-2026-result-report-draft-ko.md y docs/client-interop-evidence-kit-ko.md. La compatibilidad real completada solo se contabiliza en el ámbito que incluye la grabación install → restart → tool list → check_my_app → reconnect por cliente, el SHA-256 único y una revisión separada.

MCP calls also enforce argument and inline-text budgets by default:

• 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 calls preflight the whole manifest against the target, filtered-file, byte, and projected HTTP-request budgets. File expansion is bounded at the configured limit plus one detection entry, so an oversized tree is rejected without first enumerating the entire tree. Oversized multi-target work returns a Guardian-shaped fail-closed report; use the CLI or split the manifest for intentionally larger batches. Dynamic HTTP inspection reads at most 1 MiB per response by default and also stops at 16 MiB, 80 requests, or 30 seconds per probe run.

Safety Defaults

• JSON/Markdown/MCP outputs pass through a central redaction layer

• SARIF output also passes through the same redaction layer and stores raw-free evidence

• Dynamic probe only allows localhost, 127.0.0.1, and ::1 by default

• External dynamic probe requires explicit authorization evidence and opt-in, then remains fixed-path, read-only, same-origin, and no-redirect. Each request resolves only allowlisted public addresses and connects to the selected validated IP while preserving the original HTTP Host/TLS SNI.

• Dynamic probe does not follow redirects to non-allowlisted hosts

• Dynamic probe uses non-destructive HTTP methods only

• --deep-active is a bounded authorized check for common exposed .env, .git/config, backup/dump, and debug/runtime paths. It is not recursive crawling, password guessing, exploit payloading, or a path brute-force dictionary.

• Dynamic probe uses a timeout and caps sampled response bodies

• External secret validity checks are not performed

Severity and Confidence

Severity values are validated centrally:

• critical: credential/private-key/DB URL exposure, direct high-risk identifiers, or unauthenticated sensitive routes

• high: strongly identifying combinations, risky localhost exposure, or sensitive flow candidates

• medium: standalone contact/location/config signals and hardening findings

• low: weak heuristic signals

• info: informational observations

Confidence values are high, medium, and low.

Data Flow And Inner-Core Limits

The flow map is explicitly EXPERIMENTAL and marked as heuristic+ast-taint+js-ts-taint with line-distance+python-intra-procedural-ast+js-ts-intra-file+limited-interprocedural-taint precision. It is a developer triage aid: Python AST taint is supported, and JS/TS now has lightweight intra-file taint, limited route-to-service summaries, plus framework-aware heuristics for Next.js route handlers/server actions, Express IDOR-shaped route params, Supabase service-role/RLS boundary hints, and Firebase Admin auth-boundary hints. Full TypeScript type checking, alias-complete import resolution, middleware proof, deployed RLS/Firebase rule proof, and complete inter-procedural taint remain roadmap items. Flow findings include raw-free source/sink line hashes to make evidence reproducible without echoing sensitive values. Flow visualizations are generated as local SVG/HTML without external JavaScript or CDN dependencies. The same redaction layer protects JSON, Markdown, SVG, HTML, and MCP responses.

Runtime MCP observation ingests JSONL/JSON event exports through observe_mcp_events and can also evaluate one event at a time through observe_mcp_event(session_id=...). CLI mcp-intercept applies those block and redact decisions to a batch event stream before writing forwarded JSONL. CLI mcp-proxy -- <upstream argv> is the live enforcement path for line-delimited stdio JSON-RPC. CLI mcp-http-proxy --upstream <URL> enforces the same policy across Streamable HTTP POST, GET SSE, and DELETE session lifecycles, with official Python MCP SDK interoperability coverage. Both proxies emit the same raw-free, transaction-linked HMAC receipt chain for access deny and content allow/redact/block decisions; configured sidecar persistence happens before forwarding and fails closed. Operator-secret verification is required for tamper-resistance claims because HMAC is a shared-secret tag, not a public-key signature. Both proxies fail closed on invalid framing, correlation errors, size or timeout limits, and transport control failures. Streaming observer state has bounded idle/LRU session retention. MCP enforce_mcp_events remains report-only. Binary framing, nonstandard transports, and a universal drop-in proxy for every MCP client remain roadmap work.

Read-only connectors inspect local SQLite/log/storage files only. Remote Postgres/Supabase/Firebase/S3, backups, and actual deletion execution are roadmap items.

Feedback Drift Loop

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 files are sanitized before write and summarized locally for corpus tuning. False-negative snippets use extra conservative token masking because the detector may have missed the sensitive value. feedback-export requires --reviewed or K_GUARD_FEEDBACK_EXPORT_REVIEWED=1 so accidental automated exports fail closed. Review feedback-summary.json before sharing it outside the partner environment; do not transmit raw feedback.jsonl.

Field Benchmark

benchmark-template creates a 20/20/10 manifest:

• 20 general baseline sites or reports

• 20 vibe-coded suspected sites or reports

• 10 owned, partner-approved, or bug-bounty scoped targets

benchmark aggregates raw-free K-Guard JSON reports and, only with --run-probes, authorized manifest rows marked mode=probe. It reports high/critical target rate, strong-identifier detection rate, top rules, and manual false-positive rate by cohort. The default path is report-only so benchmark work can start from dashboard exports without touching external sites.

The same workflow is available through MCP as create_benchmark_template and field_benchmark. MCP benchmark probes require the same explicit probe opt-ins as probe_http.

Guardian Mode

guardian-template creates an authorized target manifest for continuous product guarding. A row can point to a local workspace, an HTTP origin, an MCP runtime JSONL export, or an existing raw-free K-Guard JSON report. guardian aggregates all rows into one raw-free report with per-target gates, new/resolved finding drift, top recurring rules, and fix recipes from suggest_fix.

Guardian manifests also carry raw-free business-intent and scope assertion fields: business_purpose, data_classes, user_scope, public_endpoints, scope_basis, and scope_proof_ref. K-Guard does not claim human-level business understanding or prove ownership by itself; it records whether those assertions exist and stores only hashed refs. Scope completion requires an explicit scope_proof_ref; locators and legacy authorization notes are not treated as proof. Data-release gating requires those target-level contracts and verified operator-keyed evidence bundles whose artifact hashes match the current report before treating a report as shipment evidence.

New templates set audit_profile=korean_senior. In this profile a release gate does not pass merely because it found zero blockers. It also requires a substantive workspace with at least one supported and successfully decoded production source file, flow analysis, a completed deep HTTP review, declared endpoint paths that actually return 2xx/3xx/401/403 rather than only 404, and explicit purpose/data/user/scope assertions. Guardian content-hashes each workspace immediately before and after its audit; a mismatch emits GUARDIAN_SOURCE_CHANGED_DURING_AUDIT, blocks the target, and excludes that run from substantive coverage. Use an immutable CI checkout for release authority. The report exposes review_contract.domains for site_security, api_exposure, data_management, and operational_risk; guardian_gate.passed remains false when any required domain is incomplete. Legacy manifests without audit_profile remain on the narrower standard profile and must not be presented as four-domain senior coverage.

public_endpoints is executable review scope, not decorative metadata. Guardian safely adds valid same-origin paths from that field to the fixed GET/OPTIONS probe set (maximum 50; no absolute URL, parent traversal, or templated path). This lets the API review cover app-specific read-only endpoints while keeping the probe bounded.

When an HTTP row includes session_file, Guardian runs the same bounded path set twice: once unauthenticated and once with the operator-provided read-only session. This keeps public exposure checks visible instead of replacing them with an authenticated-only view. The session must prove both an auth-wall transition and the declared identity response digest. A korean_senior gate rejects HTTP coverage when either proof is absent, when a probe produced request or control errors, or when no valid declared endpoint scope was reached.

guardian --fail-on high is the canonical pre-release gate. It is the workflow to use when K-Guard should decide whether a target app can ship under a configured threshold. Workspace-only scan --fail-on and MCP security_gate are quick checks; they do not replace Guardian's manifest, coverage-gap, drift, and multi-target execution contract.

By default, guardian writes a report and exits successfully so teams can review findings without turning it into a release blocker. Use --fail-on high when the same report should act as a CI gate; it exits with code 3 when blocking targets or new blocking findings are present. On the first run without --previous, the report is an initial_snapshot: current blockers and coverage gaps can still fail the gate, but K-Guard does not label every current finding as new drift. In gate mode, HTTP rows in the manifest must actually execute via --run-probes or they become coverage gaps instead of silent passes.

Las filas HTTP no se ejecutan a menos que se pase --run-probes. La ruta CLI está pensada para un operador local de confianza y utiliza banderas CLI explícitas/filas de manifiesto como su mecanismo de aceptación. MCP está mediado por agentes y es más estricto: guardian_audit(..., run_probes=true) requiere K_GUARD_MCP_ENABLE_PROBE=1; los manifiestos que solicitan sondas externas, de activación profunda o de sesión requieren adicionalmente K_GUARD_MCP_ENABLE_EXTERNAL_PROBE=1, K_GUARD_MCP_ENABLE_DEEP_ACTIVE_PROBE=1 o K_GUARD_MCP_ENABLE_SESSION_PROBE=1 respectivamente. El modo Guardian sigue utilizando sondas fijas y seguras de GET/OPTIONS y no realiza intentos de inicio de sesión, adivinación de contraseñas, mutaciones, cargas útiles de explotación, rastreo recursivo ni seguimiento de redirecciones entre hosts.

Los clientes MCP deben pasar fail_on="high" a guardian_audit para obtener el veredicto canónico de puerta de lanzamiento en guardian_gate.passed; los códigos de salida del proceso siguen siendo una preocupación de la CLI. Use --previous previous-guardian-report.json para convertir el informe en un monitor de deriva. Los nuevos hallazgos bloqueantes se listan por separado solo cuando se carga un informe anterior; combine --previous con --fail-on cuando esos hallazgos deban detener un lanzamiento. Si los controles MCP detienen a Guardian antes de la ejecución del objetivo, tanto el modo de informe como el modo de puerta devuelven una respuesta con forma de Guardian que incluye execution_contract, summary y findings; el modo de puerta además incluye guardian_gate.passed=false. El informe incluye una sección execution_contract para que los objetivos omitidos, con error y ejecutados sean visibles en un solo lugar, incluidas las exportaciones Markdown y HTML.

security_gate(path, fail_on) de MCP es una puerta rápida solo para el espacio de trabajo. Ahora devuelve security_gate.passed=false en fallos de control MCP como umbrales no válidos, presupuestos de argumentos, límites de presupuesto del espacio de trabajo o excepciones de escaneo, pero informa intencionalmente coverage_model="workspace_only". Use Guardian para decisiones de lanzamiento que necesiten objetivos HTTP, exportaciones de tiempo de ejecución MCP, informes anteriores o contabilidad de brechas de cobertura.

La política de supresión es de cierre ante fallo. suppression-template crea un CSV que vincula cada exención a app_id, audit_profile, la instantánea de fuente actual o el hash de evidencia de revisión, target_id, la huella del hallazgo, el propietario, el motivo y la expiración futura. Una exención no puede reproducirse contra otra aplicación o una instantánea de lanzamiento modificada; las filas no válidas, obsoletas o expiradas añaden un hallazgo de política de severidad alta. Las supresiones no pueden eliminar brechas de cobertura de Guardian ni reglas de fallo de control MCP. field-validation-queue exporta cada candidato de severidad alta/crítica con una huella redactada, subtipo de detector, alcance del artefacto, tipo de ubicación de archivo/cuerpo/cabecera y hash de respuesta disponible. La afirmación estricta de field-validation-report --profile field permanece cerrada hasta que 12-20 aplicaciones propias/de socios, 120 casos etiquetados, 50 positivos, 40 negativos, cinco casos críticos, tres estratos, un conjunto de retención preregistrado con al menos 70 casos, 35 positivos, 35 negativos y 35 candidatos, firmas de revisor/custodio con roles separados y una segunda pasada canónica exacta de Guardian superen todos los umbrales fijos. La precisión general/de retención, el recall de alta/crítica en retención y la especificidad en retención deben superar tanto la estimación puntual como el límite inferior de Wilson al 95%; el recall crítico en retención permanece exactamente en 1.0. Cada candidato debe vincularse a exactamente un alcance congelado de desarrollo/retención. El candidato (false_positive + benign) / (true_positive + false_positive + benign) se informa como tasa de falsos descubrimientos; la tasa de falsos positivos se calcula solo sobre casos limpios como FP / (FP + TN). La puerta de liberación de datos es más estricta: cualquier falso negativo conocido o candidato benigno de alta/crítica bloquea el lanzamiento. K_GUARD_FIELD_REVIEWER_HMAC_KEYS y K_GUARD_FIELD_CUSTODIAN_HMAC_KEY deben ser distintos de la clave de evidencia del operador; estos HMAC locales separan roles pero no prueban identidad del mundo real ni ejecución criptográficamente independiente. Los comandos heredados validation-* agregan solo etiquetas de candidatos y no pueden establecer el recall de campo.

El contrato público de calificación de bloqueo automático es independiente de la validación de campo. release_blocker_actionability_v3 requiere un censo preregistrado de al menos 100 bloqueadores automáticos, 0.90 de capacidad de acción de candidatos y un límite inferior de Wilson al 95% de 0.80. También requiere bloqueadores automáticos en al menos 20 aplicaciones. Una aplicación cuenta como totalmente accionable solo cuando cada bloqueador automático en esa aplicación está etiquetado como true_positive; tanto su tasa de aplicaciones totalmente accionables como su límite inferior de Wilson deben superar 0.90 y 0.80. Esta puerta de sensibilidad a nivel de aplicación evita que docenas de líneas correlacionadas en un repositorio creen una falsa confianza estadística. Las retenciones de revisión manual e integridad de políticas permanecen con cierre ante fallo pero se excluyen de la capacidad de acción de bloqueo automático.

El contrato completo de nivel de evidencia, primera línea base, etiquetado y ejecución repetida está documentado en docs/field-validation-v2-ko.md.

data-release-gate es más estricto: requiere K_GUARD_EVIDENCE_HMAC_KEY, el manifiesto original de Guardian, una afirmación canónica high de Guardian vinculada al informe actual, instantáneas de evidencia de objetivo y de fuente, originales de Guardian de validación de fuente primaria y repetida firmados por separado, los CSV exactos de verdad fundamental/revisor, la preregistración original del custodio, evidencia del corpus coreano y el flujo reenviado real del interceptor MCP. Vuelve a ejecutar la validación de campo a partir de esos originales, revalida los HMAC de revisor/custodio y requiere que la proyección recalculada sea igual al informe enviado. También reabre el Guardian repetido y verifica de forma independiente contenido, paquete, atestación de ejecución, cadena de herramientas, manifiesto, entradas de fuente/HTTP/MCP y el multiconjunto exacto de candidatos. La validación con socios de diseño es intencionalmente independiente de la aplicación única que se está lanzando actualmente; sus referencias de aplicación/objetivo/hallazgo candidatas deben coincidir con el informe Guardian de la fuente de validación, no hacerse pasar por cobertura de la aplicación en lanzamiento. Una plantilla reutilizable de GitHub Actions está en docs/templates/github-actions/guardian-release-gate.yml.

El JSON no autenticado se divide por riesgo. La estructura de registros sensibles/privados permanece como DYN_UNAUTH_API_JSON con severidad alta; el JSON sin esos indicadores se convierte en DYN_PUBLIC_API_JSON_REVIEW con severidad informativa para que una API pública intencional no bloquee el lanzamiento solo por devolver JSON.

scripts/site_scale_calibration.py ejecuta fixtures HTTP locales de caja negra para ruido HTML general a gran escala, páginas de contacto públicas medianas, JSON masivo generado por vibración a pequeña escala, identificadores fuertes válidos y JSON de cuentas bancarias. No utiliza acceso a red externa.

scripts/deep_probe_synthetic_calibration.py ejecuta un arnés de calibración sintético de bucle local a través de la misma ruta scan_url(..., deep_active=True) del panel. La ejecución de evidencia predeterminada utiliza 500 invocaciones de bucle local en 24 escenarios acotados; esto no son 500 sitios web reales, no es descubrimiento de vulnerabilidades y no es prueba de penetración. Cubre .env, .git/config, SQL de respaldo, endpoints de depuración, exposición de administración/API, OpenAPI, mapas de fuente, CORS, redirecciones, niveles de respuesta de PII/secretos y controles de falsos positivos para muros de inicio de sesión, carcasas SPA y respaldos HTML. También incluye controles negativos que demuestran que el puntuador esperado-vs-observado puede detectar reglas inyectadas faltantes e inesperadas. No utiliza acceso a red externa; las sondas profundas externas reales aún requieren autorización explícita del objetivo.

scripts/inner_core_product_gate.py ejecuta la puerta de producto sintética local más amplia para la afirmación de auditoría del "núcleo interno". Combina la calibración de sonda profunda de bucle local de 500 objetivos con verificaciones estáticas de código/config/texto MCP, análisis de flujo de datos AST de Python, observación JSONL de tiempo de ejecución MCP, conectores de solo lectura de SQLite/log/almacenamiento, revisión de retención/eliminación, veredictos de PII entre planos hacia agentes/externos y verificaciones de grafo de evidencia sin datos sin procesar. Esta puerta debe tener cero reglas requeridas faltantes, cero reglas de sonda profunda inesperadas, controles negativos superados, nodos/bordes de grafo de flujo no vacíos y sin marcadores sin procesar prohibidos en el informe serializado. Es una puerta de profundidad de producto, no una prueba de descubrimiento de vulnerabilidades en sitios de terceros.

El flujo de trabajo de CI ejecuta la suite completa de pytest más una puerta de núcleo interno de 24 objetivos en push/solicitud de extracción, que cubre cada escenario sintético una vez. El flujo de trabajo de auditoría programado/manual ejecuta la puerta de núcleo interno de 500 objetivos y sube su paquete de evidencia JSON/Markdown/HTML. El escaneo SARIF autoaplicado del repositorio se sube como evidencia no bloqueante porque este repositorio de escáner contiene intencionalmente reglas de detector, fixtures y ejemplos de documentación que deberían activar hallazgos de K-Guard; use --fail-on contra el producto que se audita, no contra el propio árbol de fuentes cargado de fixtures de K-Guard, a menos que exista una línea base específica del proyecto.

scripts/passive_homepage_calibration.py ejecuta calibración de página de inicio GET / solo pasiva desde un manifiesto CSV. Admite --max-targets, --delay-ms, --checkpoint-jsonl y --resume para ejecuciones fragmentadas a escala de 10k. Informa agregados de cohorte, cubo de rango, resultado y nivel de higiene como well_managed_quiet, hardening_gap, boundary_redirect y messy_or_risky_signal, de modo que los sitios ruidosos bien gestionados y los sitios desordenados de cola larga puedan calibrarse por separado. También emite un release_gate con verificaciones de aprobación/advertencia/fallo para rendimiento de medición, tasa de alta/crítica, tasa de identificadores fuertes y tasa de redirecciones de límite. No solicita /admin, /api, .env, .git, OPTIONS ni rutas recursivas.

scripts/build_top_domain_manifest.py crea ese manifiesto de calibración pasiva automáticamente desde una fuente CSV o ZIP de dominios públicos. La fuente predeterminada es el último ZIP top-1m de Tranco, por lo que los operadores no necesitan recopilar manualmente 10,000 URL. Use --start-rank para construir cohortes de candidatos desordenados de cola larga, por ejemplo, los rangos 900,001 a 910,000. También se pueden proporcionar CSV estilo Majestic Million con --source-url.

Evidencia RC del concurso solo IA

El RC del concurso mantiene la evidencia de desarrollo en carriles separados en lugar de publicar un único número de precisión combinado:

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

• El informe de calificación coreano reporta 117 casos de fixtures y un conjunto de retención congelado de 68 casos redactado por el evaluador como carriles separados. También verifica cinco contratos de espacio de trabajo, los cuatro conceptos oficiales de identificador único, los límites de números de negocio/corporativos y seis superficies de vocabulario sensible. No publica una matriz de confusión combinada ni afirma precisión ciega, adjudicada por humanos, de registro, de socios o de campo.

• La tarjeta de puntuación pública preserva los carriles actuales e históricos por separado. --require-integrity-pass falla deliberadamente mientras cualquier artefacto histórico seleccionado tenga una discrepancia de digesto o vinculación; aún se puede generar un informe para que un resultado histórico inadmisible permanezca visible en lugar de ser reescrito o eliminado silenciosamente.

• El perfil de rendimiento del concurso mide corpus sintéticos exactos de señal baja todos benignos en un host divulgado, incluida la latencia en frío de proceso nuevo y en caliente de escáner persistente, escalado de 10/50/100 MiB, concurrencia de subprocesos CPython en proceso 1/4/8, RSS máximo, cobertura completa de candidatos e invariancia de resultados sin datos sin procesar. No mide escalado denso en hallazgos, paralelismo a nivel de proceso, SLO de producción, precisión de campo, comparación normalizada por hardware ni superioridad de terceros.

Límites actuales

• Hoja de ruta de endurecimiento del producto: docs/pre-release-auditor-hardening-plan-ko.md

• La extracción de PDF/DOCX/HWP aún no está incluida

• Las comprobaciones dinámicas son solo para localhost, salvo que se incluyan explícitamente en la lista de permitidos o que el operador las atestigüe para un objetivo externo propio, aprobado por un socio o dentro del alcance de un programa de recompensas por errores

• Las cabeceras de sesión proporcionadas por el usuario solo se adjuntan a solicitudes GET de solo lectura y los valores de las cabeceras no se almacenan

• El análisis de flujo de datos (taint) JS/TS es conservador y ligero, con taint dentro del archivo, resúmenes limitados de ruta a servicio y heurísticas conscientes del framework para errores comunes de límites en Next.js/Express/Supabase/Firebase; el taint AST de Python es intraprocedimental

• La observación MCP en tiempo de ejecución y la herramienta MCP enforce_mcp_events siguen siendo consultivas; mcp-proxy y mcp-http-proxy realizan la aplicación bidireccional real para JSON-RPC stdio delimitado por líneas y el ciclo de vida Streamable HTTP probado. El enmarcado binario, los transportes no estándar y un proxy universal de sustitución para cada cliente permanecen fuera del límite aplicado

• La base de datos/almacenamiento/copias de seguridad remotas y la ejecución real de la eliminación aún no se verifican

• Los patrones de PII coreanos se basan en reglas y necesitan un ajuste de falsos positivos específico del proyecto

• Los números de registro de empresas coreanas utilizan validación de sintaxis de suma de verificación en fixtures sintéticos/creados por el proveedor. Los números de registro corporativo históricos (emitidos antes del 2025-01-31) pueden usar el antiguo anexo con suma de verificación ponderada alterna 1,2. Desde el 2025-01-31, los números corporativos actuales son 4 dígitos de registro + 2 de tipo + 7 de serie sin suma de verificación, por lo que la detección es solo reconocimiento explícito de contexto de campo/sintaxis. Nada de esto es PII de persona natural, validación de registro en vivo ni validación de campo independiente. Los valores actuales solo de contexto son reconocimiento de sintaxis/contexto no verificado. Ambigüedad prioritaria de privacidad: un RRN/FRN coreano plausible prevalece sobre una etiqueta corporativa o empresarial, cabecera o clave JSON dividida, y nunca se clasifica ni redacta como ID de organización.

• El conjunto de retención (holdout) coreano sensible/org de 68 casos creado por el evaluador (evidence/holdout/korean-sensitive-org-v1.cjson) es una inspección posterior a la implementación de oráculos sintéticos, no un estudio ciego de precisión de campo ni de validación de registro. Un caso pasa cuando cada regla must_all está presente, cada grupo must_any tiene al menos una regla coincidente y no aparece ninguna regla forbidden (recall de cualquier regla por caso). Tras esta pasada, el manifiesto congelado puntúa 68/68 con recall 1.0, especificidad 1.0 y repetición exacta de dos ejecuciones. Eso no es una afirmación de precisión de campo en vivo.