K-Guard MCP

Senior Glasses · Vibe-coding Senior

We don't break the flow of building, and we don't gloss over shipping.

K-Guard MCP is a local-first MCP auditor that reviews site, API exposure, data management, and operational risk together before shipping vibe-coding output. Guardian distinguishes between what is fine and what has not been seen yet, and returns a ship / fix and ship / insufficient review scope verdict along with next actions in Korean.

K-Guard is not a guarantee that replaces human business judgment or legal review. It automates the questions a senior developer asks before shipping and a fail-closed gate.

5-minute install · Installation and design validation · Usage guide · GitHub publication guide · Required qualification · Product north star · Full dogfood verdict · 2026 contest submission prep

First 5 minutes: current source checkout

We do not yet assume public package index distribution. On first run, install the current source from the repository root and follow the next actions shown by the Senior Glasses.

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

auto finds installed Grok, Codex, and Antigravity, merges the k-guard MCP into the user scope, and prepares a local profile for ChatGPT if the OpenAI tunnel-client is present. --workspace . pins the current project as a private binding. After that, even if the MCP starts from a different working directory, it inspects this project and rejects paths outside the boundary as high HOLD. For ChatGPT doctor/run, a CONTROL_PLANE_API_KEY with Tunnels Read + Use permission is also required in the current shell. Since ChatGPT still has tunnel-client run and developer-mode app connection remaining, the installer does not dress this up as a success and returns partial connection · next steps required. Existing settings are preserved, backups are made before JSON changes, and operator evidence keys and workspace originals are stored only in user-private files under ~/.k-guard. local-dev enables only localhost read-only probes and a small fixed deep path, keeping external and session probes off. If you only need static scanning, use --profile workspace.

The default output of install and diagnostics is three stages: connection ready → AI client → next actions. Automation uses install --json and doctor --json. For contest judging, release reproduction, and code fixes, use the judging and reproduction verification path in the 5-minute install to install build and evidence locks with --require-hashes. Semgrep 1.174.0 and pip-audit 2.10.1 are also installed with their full hash closures from requirements-semgrep.lock and requirements-pip-audit.lock into isolated venvs, so the audited runtime is not modified.

From the MCP client:

안경선배로 이 앱을 끝까지 봐줘. 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 is not a quick 5-second scan; it is a tool that accepts a full workspace audit. The first response is review_in_progress, and no ship verdict is issued until continue_review completes. Deployable text artifacts in dist, build, and .next are also inspected, and if the candidate count, path SHA-256, and read completion do not match, it blocks at high. The completion result produces a review_receipt bound to the workspace and source tree SHA-256. If the code changes, you cannot start a ship review with an old review_id; you must complete check_my_app again.

Related MCP server: Secure Code Review MCP Server

Senior Glasses verdicts

All representative results provide experience.details.presentation as a compatible alias of experience.presentation, with the order fixed as verdict → why → next_actions → details. Guardian shows app risk separately as application_assurance and the audit tool's own validation status as auditor_qualification. experience.verdict_code, experience.verdict_message, and experience.summary are existing report-compatible fields.

What it looks at

K-Guard combines:

• Static scan: Korean PII, composite PII, Korean organization identifiers (business registration number checksum syntax validation; corporate registration number historical Annex checksum or post-2025-01-31 4+2+7 explicit-context/syntax recognition, not live registry validation), secrets

• Config scan: CORS/debug/source map/env prefix risks

• Senior app-risk scan: direct request-to-SQL/command/file/URL/HTML sinks, mass assignment, open redirect, browser token storage, weak cookies, plaintext password comparison, and JWT decode-without-verify

• Korean data-governance scan: unique/sensitive field declarations, encryption/access-control evidence, access logging, external processor review, retention, and erasure

• MCP-native threat scan: hidden instructions, tool poisoning, exfiltration intent, and overbroad local access across direct text plus bounded Unicode/confusable, escaped/percent/HTML, Base64, split-fragment, and three-line rolling normalization

• Structured MCP config review: shell wrappers, mutable package launchers, plain remote HTTP, fixed credentials, unsafe links/read failures, and fail-closed discovery bounds across project/Codex/Grok/Antigravity config candidates

• YARA-lite local rule pack: prompt-injection markers, exfil command markers, Korean bulk schema hints

• Safe dynamic probe: localhost HTTP checks, explicitly authorized external-origin checks, optional bounded deep exposure checks, plus optional user-provided read-only session headers

• Data Flow Risk Map: heuristic graph plus Python AST and lightweight JS/TS source -> sink taint analysis, including unique-import Python helper parameter-to-sink summaries and limited JS/TS route-to-service IDOR summaries

• MCP runtime observer/interceptor: JSON/JSONL and stream-ready event checks for hidden instruction, PII-to-agentic/external sink flow, plus batch block/redact enforcement for forwarded event streams

• Semgrep deep adapter: offline 40-rule profile, exact scanned-target proof, pinned 1.174.0 identity, source snapshot binding, and fail-closed JS/TS/Python/Java/Kotlin/Go/PHP/Ruby/C# findings

• Nine-language validation pack: Python/JavaScript/TypeScript/Java/Kotlin/Go/PHP/Ruby/C# 90 pinned vulnerable/clean cases, TP/FN/FP/TN scoring, and exact two-run fingerprint reproduction

• Software composition analysis: bounded Python/npm/Go manifest and lock coverage with pip-audit, npm audit, and govulncheck; partial engine, lock, output, or source-drift failure blocks release

• Streamable HTTP MCP proxy: POST/GET SSE/DELETE complete mediation, principal-bound lifecycle, default-deny JIT/JEA grants, filtered tool inventory, bounded streams, and HMAC-chained raw-free audit logs

• Database controls: SQLGlot AST allowlist, role/database/schema/table/column RBAC, EXPLAIN-before-read, SQLite query-only authorizer, path containment, and row/cell/result/time budgets

• Read-only connectors: local SQLite, log, JSON/CSV/TSV storage sampling without raw value storage; connector gaps become high findings

• Retention/deletion review: flags missing retention/deletion markers when personal-data signals exist

• Cross-plane verdicts: correlates Korean PII findings with LLM/MCP/external/data-at-rest sink evidence

• FP/FN scoreboard: fixture corpus recall and false-positive rate. FPR uses measurable_negative_count as denominator (clean negatives with no expected_absent); negative_count is all declared negatives and targeted_absence_case_count covers selected-rule absences that do not enter the FPR denominator. A zero measurable-negative denominator is reported as FPR 0.0.

• SARIF/CI output: fail builds on configured severities

• korean_senior Guardian profile: fail-closed four-domain contract for site security, API exposure, data management, and operational risk

• Primary MCP tools: check_my_app, continue_review, start_review_before_ship; internal canonical engine: Guardian high; guided prompt: guided_review

• Advanced MCP tools: 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

Installation boundary

Users who receive requirements-evidence.lock distributed with the exact wheel built by the release workflow can reproduce the audited dependency closure without the repository, as shown below. k-guard, k-guard-dashboard, k-guard-mcp, python -m k_guard_mcp.cli, and python -m k_guard_mcp.server are commands from the installed wheel.

The release also includes SHA256SUMS, a SLSA provenance bundle signed with GitHub OIDC, and a CycloneDX SBOM attestation bundle. Online, verify the build subject and digest with gh attestation verify ./k_guard_mcp-0.1.0-py3-none-any.whl -R windmillstudio/k-guard-mcp before installing. If only the checksum matches and the attestation is not verified, it is not treated as an official 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

On managed PCs where Windows application control policies block the k-guard.exe console launcher from pip, use the module entry point from the same wheel. The functionality and verdict contract are identical.

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

Installing only the wheel provides runtime commands only. The release sdist and repository checkout include scripts/..., tests/fixtures/..., and validation templates. For development environments, install both locks with --require-hashes from the repository root, then run python -m pip install --no-build-isolation --no-deps -e .. The evidence lock pins both the versions of the release dependency closure and the allowed SHA-256 hashes, and the license, vulnerability, SBOM, and fresh-wheel smoke checks all use the same file.

Senior Glasses review room

To view the authorized site on screen, run the local dashboard.

k-guard-dashboard --port 8765

Open http://127.0.0.1:8765/ in your browser. The screen order is senior verdict → findings → scan log → exposure map, and final ship authority lies not with the screen but only with the MCP's start_review_before_ship. Brand images are original assets created for the project, and provenance is recorded in docs/brand-assets.md.

Installed wheel CLI

Among the commands below, tests/fixtures/korean_fixture_corpus.json is a public example corpus that can be run directly from a source checkout. Users who installed only the wheel should replace it with their own fixture path using the same schema.

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 is short-lived and bound to one exact origin. Guardian only counts an authenticated comparison as complete when the asserted identity response also matches:

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

Keep the file inside the invoked workspace, or beside the Guardian manifest. Files outside that boundary, links, expired sessions, mismatched origins, unsupported headers, and oversized files fail closed. The digest covers the exact bounded response bytes before UTF-8 decoding; raw session values and response bodies are not written to findings.

Source-checkout-only validation

The scripts/** and pytest below are not user commands included in the 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

The Coverage gate 90.00% for the full source regression is branch-inclusive combined coverage that counts statement and branch opportunity together. It does not mean branches alone are at 90%, and since it uses precision=2 and fail_under=90, 89.90% fails. The public_source_only scope in public repository CI excludes separate distribution evidence and native cases, so it applies the overall 88% and redaction.py 85% thresholds; the two figures are not interchangeable.

Source checkout release hygiene

Use the release hygiene check before CTO review or publish prep:

python scripts/release_hygiene.py --json

Default mode validates that a dirty release-candidate worktree is classified, free of visible runtime scratch output, and free of unresolved review-required artifacts. Use --strict-clean after the intended release commit; strict mode also compares every package build input byte with its Git index blob. Tagged publication additionally requires --expected-tag v{project.version}, and that exact tag must resolve to the checked-out HEAD commit. The release workflow waits for the reusable Windows/macOS/Linux CI matrix, creates attestations, and publishes the tag artifacts as a GitHub Release. Details are in docs/release-hygiene.md.

The Guardian Actions template currently installs the exact K-Guard source checkout selected by the workflow commit; it does not assume a PyPI package. Before copying it to another repository, vendor K-Guard at a commit-pinned path and set K_GUARD_SOURCE_PATH. After release artifacts exist, consumers should pin either an exact wheel plus its published SHA-256, or a full 40-character Git commit in a direct-reference requirement. Replace the placeholders only with an actual release location:

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.

Installation and connection are tailored to four clients: ChatGPT, Grok, Codex, and Antigravity. Detailed procedures are in docs/quickstart-ko.md and docs/mcp-client-install.md.

When preparing the contest result report and actual compatibility evidence, use docs/contest-2026-result-report-draft-ko.md and docs/client-interop-evidence-kit-ko.md. Actual compatibility completion is counted only for scopes that have all of the per-client install → restart → tool list → check_my_app → reconnect recording, unique SHA-256, and separate review.

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.

HTTP 행은 --run-probes가 전달되지 않으면 실행되지 않습니다. 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은 모든 면제를 app_id, audit_profile, 현재 소스 스냅샷 또는 검토 증거 해시, target_id, 발견 지문, 소유자, 이유 및 향후 만료에 바인딩하는 CSV를 생성합니다. 면제는 다른 앱이나 변경된 릴리스 스냅샷에 재생될 수 없습니다. 잘못되었거나 오래되었거나 만료된 행은 높은 심각도의 정책 발견 사항을 추가합니다. 억제는 Guardian 적용 범위 격차나 MCP 제어 실패 규칙을 지울 수 없습니다. field-validation-queue는 수정된 지문, 탐지기 하위 유형, 아티팩트 범위, 파일/본문/헤더 위치 종류 및 사용 가능한 응답 해시와 함께 모든 높음/치명적 후보를 내보냅니다. 엄격한 field-validation-report --profile field 주장은 12-20개의 소유/파트너 앱, 120개의 레이블이 지정된 사례, 50개의 양성, 40개의 음성, 5개의 치명적 사례, 3개의 계층, 최소 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 주장, 대상 증거 및 소스 스냅샷, 별도로 서명된 1차 및 반복 검증 소스 Guardian 원본, 정확한 ground-truth/검토자 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-coded 대량 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-to-에이전트/외부 판정 및 원시 없는 증거 그래프 검사와 결합합니다. 이 게이트는 필수 규칙 누락이 0이어야 하고, 예기치 않은 심층 프로브 규칙이 0이어야 하며, 음성 제어를 통과하고, 비어 있지 않은 흐름 그래프 노드/엣지가 있어야 하며, 직렬화된 보고서에 금지된 원시 마커가 없어야 합니다. 이는 제품 깊이 게이트이지 타사 사이트 취약점 발견의 증거가 아닙니다.

CI 워크플로는 푸시/풀 리퀘스트 시 전체 pytest 스위트와 24개 대상 내부 코어 게이트를 실행하여 모든 합성 시나리오를 한 번씩 다룹니다. 예약/수동 감사 워크플로는 500개 대상 내부 코어 게이트를 실행하고 JSON/Markdown/HTML 증거 팩을 업로드합니다. 저장소 자체 SARIF 스캔은 게이트가 아닌 증거로 업로드됩니다. 이 스캐너 저장소에는 의도적으로 K-Guard 발견 사항을 트리거해야 하는 탐지기 규칙, 픽스처 및 문서 예제가 포함되어 있기 때문입니다. 프로젝트별 기준선이 없는 한 K-Guard 자체의 픽스처가 많은 소스 트리가 아닌 감사 대상 제품에 대해 --fail-on을 사용하십시오.

scripts/passive_homepage_calibration.py는 CSV 매니페스트에서 GET / 전용 홈페이지 보정을 실행합니다. 10k 규모 분할 실행을 위해 --max-targets, --delay-ms, --checkpoint-jsonl 및 --resume을 지원합니다. 코호트, 순위 버킷, 결과 및 위생 계층 집계(예: 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위). Majestic Million 스타일 CSV도 --source-url로 제공할 수 있습니다.

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개 평가자 작성 홀드아웃을 별도 레인으로 보고합니다. 또한 5개의 작업 공간 계약, 4개의 공식 고유 식별자 개념, 사업자/법인 번호 경계 및 6개의 민감 어휘 표면을 확인합니다. 통합 혼동 행렬을 게시하지 않으며 블라인드, 인간 심의, 레지스트리, 파트너 또는 필드 정확도를 주장하지 않습니다.

• 공개 스코어카드는 현재 및 과거 레인을 별도로 유지합니다. --require-integrity-pass는 선택된 과거 아티팩트에 다이제스트 또는 바인딩 불일치가 있는 동안 의도적으로 실패합니다. 허용되지 않는 과거 결과가 자동으로 다시 쓰여지거나 삭제되는 대신 표시되도록 보고서를 계속 생성할 수 있습니다.

• 콘테스트 성능 프로필은 공개된 단일 호스트에서 정확한 합성 전부 양성 저신호 말뭉치를 측정합니다. 새 프로세스 콜드 및 지속 스캐너 웜 대기 시간, 10/50/100 MiB 확장, 프로세스 내 CPython 스레드 동시성 1/4/8, 최대 RSS, 완전한 후보 적용 범위 및 원시 없는 결과 불변성을 포함합니다. 발견 밀도 확장, 프로세스 수준 병렬 처리, 프로덕션 SLO, 필드 정확도, 하드웨어 정규화 비교 또는 타사 우월성을 측정하지 않습니다.

현재 한계

• Product hardening roadmap: docs/pre-release-auditor-hardening-plan-ko.md

• PDF/DOCX/HWP extraction is not included yet

• Dynamic checks are localhost-only unless explicitly allowlisted or attested by the operator for an owned, partner-approved, or bug-bounty scoped external target

• User-provided session headers are attached only to read-only GET requests and header values are not stored

• JS/TS taint is conservative and lightweight, with intra-file taint, limited route-to-service summaries, and framework-aware heuristics for common Next.js/Express/Supabase/Firebase boundary mistakes; Python AST taint is intra-procedural

• Runtime MCP observation and the MCP enforce_mcp_events tool remain advisory; mcp-proxy and mcp-http-proxy perform actual bidirectional enforcement for line-delimited stdio JSON-RPC and the tested Streamable HTTP lifecycle. Binary framing, nonstandard transports, and a universal drop-in proxy for every client remain outside the enforced boundary

• Remote DB/storage/backups and actual deletion execution are not verified yet

• Korean PII patterns are rule-based and need project-specific false-positive tuning

• Korean business registration numbers use checksum syntax validation on synthetic/vendor-authored fixtures. Historical corporate registration numbers (issued before 2025-01-31) may use the old Annex alternating 1,2 weighted checksum. Since 2025-01-31, current corporate numbers are 4 registry + 2 type + 7 serial digits with no checksum, so detection is explicit field-context/syntax recognition only. None of this is natural-person PII, live registry validation, or independent field validation. Context-only current values are unverified syntax/context recognition. Privacy-first ambiguity: a plausible Korean RRN/FRN wins over a corporate or business label, header, or split JSON key, and is never classified or redacted as an organization ID.

• The evaluator-authored 68-case Korean sensitive/org holdout (evidence/holdout/korean-sensitive-org-v1.cjson) is a post-implementation inspection of synthetic oracles, not a blind field-accuracy or registry-validation study. A case passes when every must_all rule is present, each must_any group has at least one matching rule, and no forbidden rule appears (per-case any-rule recall). After this pass the frozen manifest scores 68/68 with recall 1.0, specificity 1.0, and exact two-run repeat. That is not a claim of live field accuracy.