Guards and Integrity: tracking issue

[lpcox]

Overview

Tracking issue for the Guards and Integrity work in MCP Gateway. This covers the DIFC (Decentralized Information Flow Control) engine, WASM guard framework, GitHub Guard implementation, and end-to-end integration with the gh-aw compiler.

---

Specifications

gh-aw (compiler & platform)

Document	Description
MCP Gateway Configuration Reference	Canonical gateway config spec — server types, guard-policies schema, containerization requirements
MCP Gateway Config JSON Schema	Machine-readable schema for config validation
MCP Scripts Specification	MCP scripts spec (compiler input format)
gh-aw as MCP Server	gh-aw MCP server reference

gh-aw-mcpg (gateway)

Core DIFC rules:

Document	Description
DIFC_RULES.md	Secrecy/integrity labels, read/write flow rules, enforcement modes, testing guidelines
DIFC_INTEGRATION_PROPOSAL.md	Complete DIFC architecture and design decisions
GUARD_RESPONSE_LABELING.md	Response labeling mechanism and label lifecycle

GitHub Guard specs:

Document	Description
GitHub Guard README	Guard architecture, WASM entrypoints, AllowOnly operating modes, labeling tables
INTEGRITY_TAG_SPEC.md	Complete integrity hierarchy: merged > approved > unapproved > none
SECRECY_TAG_SPEC.md	Secrecy label rules, private/public repo labeling
GATEWAY_ALLOWONLY_INTEGRATION_SPEC.md	Guard policy JSON structure, scope validation, CLI arguments
LABELING.md	How DIFC labels are applied to GitHub operations
LABEL_AGENT_IMPLEMENTATION_PLAN.md	Label agent lifecycle and session handling
OVERVIEW.md	Guard features overview
IMPLEMENTATION.md	Technical implementation details
TESTING.md	Test information and coverage

Configuration examples:

Document	Description
config.example.toml	TOML config with guard-policies examples (lines 72–88)
agentic-workflow-policy.schema.json	JSON schema for agentic workflow policy frontmatter

---

Integrity Level Criteria

Hierarchy

merged > approved > unapproved > none (highest to lowest trust)

Labels are hierarchically expanded — each level includes all levels below it:

Assigned Level	Labels Generated
merged	none:<scope> + unapproved:<scope> + approved:<scope> + merged:<scope>
approved	none:<scope> + unapproved:<scope> + approved:<scope>
unapproved	none:<scope> + unapproved:<scope>
none	none:<scope>

All objects receive at least none:<scope> via ensure_integrity_baseline().

Authorship Rules

The author_association field from the GitHub API maps to an integrity floor:

author_association	Integrity Floor	Source
OWNER	approved	helpers.rs: author_association_floor_from_str
MEMBER	approved	same
COLLABORATOR	approved	same
CONTRIBUTOR	unapproved	same
FIRST_TIME_CONTRIBUTOR	unapproved	same
FIRST_TIMER	none	same
NONE / missing	none	same

Additional authorship modifiers:

Condition	Effect	Source
Bot author (login ends with [bot]/-bot, or exact match: dependabot, renovate, github-actions, copilot)	Treated as approved	helpers.rs: is_bot
Private repo	All authors elevated to at least approved	tool_rules.rs, helpers.rs: issue_integrity, pr_integrity, commit_integrity

Reachability Rules (Object-Specific)

Reachability affects commits, PRs, and file contents. The rules vary by object type:

Commits (helpers.rs: commit_integrity, tool_rules.rs):

Condition	Integrity
Default branch (main, master, HEAD, or empty)	merged
Feature branch, private repo	approved
Feature branch, public repo	none

Pull Requests (helpers.rs: pr_integrity):

Condition	Integrity
Merged (regardless of author or repo)	merged
Unmerged, private repo	approved
Unmerged, public repo, direct (same-repo)	approved
Unmerged, public repo, from fork	unapproved

File Contents (tool_rules.rs, response_items.rs, response_paths.rs):

Condition	Integrity
Default branch ref	merged
Other branch ref	approved

Per-Object Integrity

Object Type	Condition	Integrity	Source
Repository metadata	Any	approved	tool_rules.rs: writer_integrity
Commits	Default branch	merged	helpers.rs: commit_integrity
Commits	Feature branch (private)	approved	same
Commits	Feature branch (public)	none	same
Pull Requests	Merged	merged	helpers.rs: pr_integrity
Pull Requests	Unmerged, private repo	approved	same
Pull Requests	Unmerged, public, direct	approved	same
Pull Requests	Unmerged, public, from fork	unapproved	same
Issues / Comments	author_association floor (see above), private repo elevates to approved	varies	helpers.rs: issue_integrity
File contents	Default branch	merged	tool_rules.rs, response_items.rs
File contents	Feature branch	approved	same
Releases	Always (endorsed by maintainers)	merged	response_items.rs: merged_integrity
Tags	Always	approved	tool_rules.rs: writer_integrity
Branches	Always	approved	tool_rules.rs: writer_integrity
Security alerts	Code scanning, Dependabot, Secret scanning	approved	tool_rules.rs: writer_integrity
Actions / Workflows	Maintained by repo team	approved	tool_rules.rs: writer_integrity
User profiles / Search	GitHub official data	approved:github	helpers.rs: project_github_label → writer_integrity("github")
Gists	User content (public or private)	unapproved	response_items.rs: reader_integrity("user")
Notifications	User context	none	response_items.rs: none_integrity

Note: label_resource (pre-execution) and label_response (post-execution) may assign different integrity levels for the same tool. Response-level labeling refines resource-level labels with per-item context (e.g., merge status, author association). The table above reflects effective response-level integrity.

Secrecy Labels

Condition	Secrecy Label	Source
Public repo	[] (empty — anyone can read)	tool_rules.rs
Private repo	private:<owner>/<repo>	helpers.rs: policy_private_scope_label
Secret scanning alerts	secret	tool_rules.rs: secret_label
Sensitive files (.env, .key, .pem, .p12, .pfx, id_rsa, id_dsa, id_ecdsa, id_ed25519)	secret	constants.rs: SENSITIVE_FILE_PATTERNS
Files with sensitive keywords (secret, credential, password, token in filename)	secret	constants.rs: SENSITIVE_FILE_KEYWORDS
Workflow files (.github/workflows/*)	secret (may contain tokens)	tool_rules.rs: check_file_secrecy
Action artifact downloads	secret	tool_rules.rs
Notifications	private:user	response_items.rs
Private gists	private:user	response_items.rs
Public gists	[] (empty)	response_items.rs

DIFC Flow Rules

Rule	Check
Read	Agent.secrecy ⊇ Data.secrecy AND Data.integrity ⊇ Agent.integrity
Write	Resource.secrecy ⊇ Agent.secrecy AND Agent.integrity ⊇ Resource.integrity

---

Work Completed

Core DIFC Engine (internal/difc/)

• Three enforcement modes: strict (deny violations), filter (remove disallowed items), propagate (auto-adjust agent labels)
• AgentLabels with thread-safe secrecy/integrity label management
• Evaluator with read/write flow rules based on secrecy and integrity subset checks
• Fine-grained PathLabels for JSONPath-based response labeling on collections
• ~6,000 LOC implementation + ~3,800 LOC tests

Guard Framework (internal/guard/)

• Abstract Guard interface with three WASM entrypoints: LabelAgent, LabelResource, LabelResponse
• WasmGuard implementation using wazero runtime with thread-safe mutex serialization
• NoopGuard fallback for unguarded sessions
• Per-server guard registry and factory

GitHub Guard (guards/github-guard/)

• Complete Rust-based WASM guard (~170KB compiled) with full GitHub MCP tool coverage
• Secrecy labeling: public repos (empty), private repos (private:owner/repo)
• Integrity hierarchy: none < unapproved < approved < merged
• Backend API integration for contributor verification
• Sensitive content detection (secrets, security issues)
• Baked into the gateway Docker image

Guard Policies (internal/config/guard_policy.go)

• AllowOnly policy model with flexible scope matching
• Repos field: "all", "public", exact match, wildcards (owner/*, owner/prefix*)
• MinIntegrity field: none, unapproved, approved, merged
• Support in both TOML and JSON configuration formats

CLI and Configuration

• 12 CLI flags for guards configuration (--enable-guards, --guards-mode, --guard-policy-json, etc.)
• Environment variable support (MCP_GATEWAY_ENABLE_GUARDS, MCP_GATEWAY_GUARDS_MODE, etc.)
• Config extensions for session-level secrecy/integrity labels
• Per-server guard-policies in both TOML and JSON stdin formats

User-Facing Nomenclature

• Renamed difc → guards in all user-facing flags, env vars, config keys, and docs
• Renamed reader → unapproved, writer → approved for integrity labels
• Renamed integrity → min-integrity in policy configuration
• Canonical policy key: allow-only (with backward compat for allowonly)

Testing

• ~8,500 LOC of unit tests across 12 test files (DIFC core, guards, config, CLI flags)
• Integration tests for DIFC config, environment variables, gateway startup
• Copilot CLI smoke tests in four operating modes (yolo, public-only, owner-only, repo-only)
• Manual end-to-end validation of all GitHub MCP read-only tools across all four modes

CI/CD

• WASM guard built in release workflow with Rust cross-compilation
• Guard baked into Docker image during build
• Cross-repo release publishing to lpcox/github-guard

---

Key PRs

• feat: Add GitHub DIFC enforcement with WASM guards, guard policies, and LabelAgent integration #1674 — Add GitHub DIFC enforcement with WASM guards, guard policies, and LabelAgent integration
• fix: routed URL host advertisement and allow-only key normalization #1683 — Fix routed URL host advertisement and allow-only key normalization
• github-guard: bake WASM into gateway image, align test/release workflows, and rename user-facing flags to "guards" #1693 — Bake WASM into gateway image, align test/release workflows, rename user-facing flags to "guards"
• Update copilot test expectations with proper behavior definitions and standardized report templates #1702 — Update copilot test expectations with behavior definitions and standardized report templates

---

Next Steps

• End-to-end integration tests with the gh-aw compiler — Validate that guard policies configured via gh-aw workflow specs compile correctly into gateway configurations and enforce the expected DIFC behavior at runtime
• Compiler-generated guard-policies validation (TOML and JSON output)
• Round-trip testing: workflow spec → compiler → gateway config → runtime enforcement
• Test all four operating modes (yolo, public-only, owner-only, repo-only) through the compiler pipeline

[github-actions]

🛡️ Guard Status Update — 2026-03-15

Codebase Snapshot

Component	Files	Lines	Tests
DIFC Engine (internal/difc/)	7	1,803	5,933 (9 files)
Guard Framework (internal/guard/)	6	1,461	2,421 (4 files)
Guard Config (guard_policy.go)	1	448	—
Rust GitHub Guard (rust-guard/src/)	10	5,806	—
Total	24	9,518	8,354 (13 files)

Recent Changes (first run — full 14-day window)

10 guard-related PRs merged Mar 13–15:

• feat: add Guard Status Tracker workflow for issue #1711 #1938 (2026-03-15) feat: add Guard Status Tracker workflow for issue Guards and Integrity: tracking issue #1711
• feat: add Rust Guard Improver daily workflow #1920 (2026-03-14) feat: add Rust Guard Improver daily workflow
• refactor: eliminate duplicate code patterns in internal/difc package #1916 (2026-03-14) refactor: eliminate duplicate code patterns in internal/difc
• chore: scope all workflows to github/gh-aw-mcpg with min-integrity unapproved #1906 (2026-03-14) chore: scope all workflows to this repo with min-integrity: unapproved
• [log] difc: add debug logging to path_labels.go #1888 (2026-03-14) [log] difc: add debug logging to path_labels.go
• feat: add wildcard accept ["*"] for write-sink guards #1868 (2026-03-13) feat: add wildcard ["*"] accept for write-sink guards
• [test] Add tests for difc package: getItems, AddIntegrityTags, Intersect, checkFlowHelper #1860 (2026-03-13) [test] Add tests for difc: getItems, AddIntegrityTags, Intersect, checkFlowHelper
• [log] cmd/flags_difc: add debug logging for DIFC policy and mode resolution #1856 (2026-03-13) [log] cmd/flags_difc: debug logging for DIFC policy and mode resolution
• refactor: extract duplicate code patterns into helpers #1855 (2026-03-13) refactor: extract duplicate helpers (checkFlowHelper, newEmptyEvaluationResult)
• fix: correct malformed WASM binary and stale test expectation in guard tests #1849 (2026-03-13) fix: correct malformed WASM binary and stale test expectation

Current Architecture

• Enforcement modes: strict (deny violations) · filter (remove denied tools) · propagate (auto-adjust labels)
• Guard types: WasmGuard (GitHub Rust guard, loaded from --wasm-guards-dir) · WriteSinkGuard (now supports ["*"] wildcard) · NoopGuard
• Policy model: AllowOnly with repos scope + min-integrity; sanitize: ["remove-hidden-comments"] opt-in
• Integrity hierarchy: none < unapproved < approved < merged
• WASM binary: Not pre-built in repo — loaded at runtime from filesystem via MCP_GATEWAY_WASM_GUARDS_DIR / --wasm-guards-dir

Notes

• This is the first automated run (no previous cache). Future updates will highlight deltas only.
• Rust Guard Improver workflow (feat: add Rust Guard Improver daily workflow #1920) and this Guard Status Tracker (feat: add Guard Status Tracker workflow for issue #1711 #1938) are now both live.
• Test coverage is strong: 8,354 test LOC across 13 test files for the guard/DIFC packages.

---

Auto-generated by Guard Status Tracker • §23099487858

Generated by Guard Status Tracker · ◷