From c7f18ee09835aa9220d387d9d658b0154a21cee3 Mon Sep 17 00:00:00 2001 From: Sage Hart - AI Date: Sat, 5 Sep 2026 13:04:21 -0500 Subject: [PATCH 1/3] docs: position FidusGate as Ed25519 receipts plus console Stop competing as a generic zero-trust platform; document the OpenFirma contrast and keep fail-closed as the community contract. Co-authored-by: Cursor --- .github/SECURITY.md | 4 +- .github/copilot-instructions.md | 24 ++ .github/skills/cedar-mcp-receipts/SKILL.md | 353 +++++++++++++++++++++ AGENTS.md | 82 ++--- README.md | 14 +- docs/DESIGN-PIVOT.md | 37 +++ docs/README.md | 6 +- docs/community/github-presentation.md | 4 +- docs/factory-overlay.md | 65 ++++ llms.txt | 26 ++ 10 files changed, 557 insertions(+), 58 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/skills/cedar-mcp-receipts/SKILL.md create mode 100644 docs/DESIGN-PIVOT.md create mode 100644 docs/factory-overlay.md create mode 100644 llms.txt diff --git a/.github/SECURITY.md b/.github/SECURITY.md index c8cf7d6..8f0016f 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,5 +1,7 @@ # Security Policy +FidusGate is a reference implementation of **signed Ed25519 receipts for MCP tool calls** plus an admin console. It is **not** a production-hardened security product. Reports that weaken fail-closed authorize, Cedar, or receipt-verification paths are still in scope. + ## Supported Versions Only the latest active release on `main` is supported for security updates: @@ -11,7 +13,7 @@ Only the latest active release on `main` is supported for security updates: ## Reporting a Vulnerability -FidusGate takes repository governance and AI sandbox containment security very seriously. If you discover a vulnerability, access-control bypass (e.g. in the Cedar policy logic), container jailbreak (e.g. escaping the gVisor sandbox), or a prompt-injection vulnerability: +If you discover a vulnerability, access-control bypass (e.g. in the Cedar policy logic), receipt forgery or verification bypass, container jailbreak (e.g. escaping the gVisor sandbox), or a prompt-injection vulnerability: 1. **Do not open a public GitHub issue.** 2. Report privately via **[GitHub Security Advisories](https://github.com/SafetyMP/FidusGate/security/advisories/new)** (preferred). diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..5f2cf9f --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,24 @@ +# Copilot instructions — FidusGate + +FidusGate is **signed Ed25519 receipts for MCP tool calls** plus a runnable admin console (ledger, Cedar simulator, verifier). It is a reference implementation — **not** a production-hardened security product and not a generic zero-trust agent governance platform. + +Read [`AGENTS.md`](../AGENTS.md) and [`docs/DESIGN-PIVOT.md`](../docs/DESIGN-PIVOT.md) before changing behavior. Factory/site overlay: [`docs/factory-overlay.md`](../docs/factory-overlay.md). + +## Do + +- Keep Cedar authorization and Ed25519 receipt issuance on the MCP tool-call path. +- Prefer changes that make the ledger, simulator, or verifier clearer and honest. +- Run `./scripts/harness/verify.sh` (or `./scripts/verify.sh`) before claiming done. +- Keep fail-closed authorize, kill-switch, PDP, principal-signature, and production-profile paths fail-closed. + +## Do not + +- Weaken fail-closed into fail-open, including “helpful” silent fallbacks from enforce to shadow. +- Compete with OpenFirma / Vectimus / Symbiont / Permit Cedar Agent by adding sidecar features. +- Claim originality of the Cedar skill material — `.github/skills/cedar-mcp-receipts/` is adapted from `scopeblind/scopeblind-gateway`. +- Treat this skill as a prompt-injection classifier. Use `cedar-mcp-receipts` only for tool gates, shadow-to-enforce rollout, and receipt verification. +- Rewrite Prisma schemas or Vitest majors unless the task explicitly asks for app code. + +## Key paths + +`policy.cedar`, `policy.cedarschema`, `protect-mcp.config.json`, `packages/cedar-daemon`, `apps/secure-gateway`, `packages/crypto-utils`, `apps/admin-dashboard`. diff --git a/.github/skills/cedar-mcp-receipts/SKILL.md b/.github/skills/cedar-mcp-receipts/SKILL.md new file mode 100644 index 0000000..1a2106e --- /dev/null +++ b/.github/skills/cedar-mcp-receipts/SKILL.md @@ -0,0 +1,353 @@ +--- +name: cedar-mcp-receipts +description: "Authorize MCP tool calls with Cedar policies and verify Ed25519 receipts. Use when adding or auditing agent tool gates, shadow-to-enforce rollout, or receipt verification — not for prompt-injection classifiers." +risk: safe +source: community +source_repo: scopeblind/scopeblind-gateway +source_type: official +date_added: "2026-04-05" +--- + +# Authorize MCP tool calls with Cedar and Ed25519 receipts + +Skill text is adapted from `scopeblind/scopeblind-gateway` (`protect-mcp`). This copy does not claim originality of that material. + +## Overview + +Guidance for governing AI agent tool calls using Cedar policies and Ed25519 signed receipts. This skill teaches how to write access-control policies for MCP servers, run them in shadow mode for observation, and verify the cryptographic audit trail. + +## When to Use This Skill + +- Use when adding or auditing agent tool gates +- Use when rolling out governance policies gradually (shadow mode first, then enforce) +- Use when authoring Cedar policies for MCP tool access control +- Use when verifying that a receipt or audit bundle has not been tampered with + +## Do Not Use This Skill + +- When you need a prompt-injection classifier (this skill is authorization and receipts, not classification) +- When you need general application security auditing (use `@security-auditor`) +- When you need to scan code for vulnerabilities (use `@security-audit`) +- When you need compliance framework guidance without agent-specific governance + +## How It Works + +protect-mcp intercepts MCP tool calls, evaluates them against Cedar policies (the same policy engine used by AWS Verified Permissions), and signs every decision as an Ed25519 receipt. The receipt is a cryptographic proof that a specific policy was evaluated against a specific tool call at a specific time. + +### July 2026 protocol notes (MCP `2026-07-28`) + +FidusGate’s gateway is **dual-era**: + +- **stdio** — legacy `initialize` handshake retained for Cursor/local clients (`2025-11-25` preferred; `2024-11-05` accepted). +- **HTTP** `POST /mcp` — stateless Streamable HTTP: require `MCP-Protocol-Version`, `Mcp-Method`, and (for named methods) `Mcp-Name`. Header/body disagreement is rejected **before** Cedar runs. +- Modern clients should call `server/discover` instead of relying on session init. +- Demo OAuth surface: `GET /.well-known/oauth-protected-resource` (RFC 9728); map residual risks via [OWASP MCP Top 10 ADR](../../../docs/adr/0001-owasp-mcp-top-10.md). +- Operator guide: [mcp-2026-07-28-migration.md](../../../docs/mcp-2026-07-28-migration.md). + +``` +Agent → protect-mcp → Cedar policy evaluation → MCP Server + ↓ + Ed25519 signed receipt +``` + +Three modes of operation: + +1. **Shadow mode** (default) — logs decisions without blocking. Use this to observe what your policies would do before enforcing them. +2. **Enforce mode** — blocks tool calls that violate policy. Use after shadow-mode validation. +3. **Hooks mode** — integrates with Claude Code hooks for pre/post tool-call governance. + +## Core Concepts + +### Cedar Policies + +Cedar is a policy language designed for authorization. Policies are evaluated locally via WASM — no network calls required. + +```cedar +// Allow read-only file operations +permit( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name in ["read_file", "list_directory", "search_files"] +}; + +// Deny destructive operations +forbid( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name in ["execute_command", "delete_file", "write_file"] + && resource has args + && resource.args.contains("rm -rf") +}; +``` + +### Risk-Tiered Development Governance + +To mitigate the four main latent development risks (Runaway Concurrency, Self-Authoring Rot, Yak-Shaving loops, and Micro-Auditing lockups), we map agentic tools to four explicit risk tiers: + +| Tier | Name | Development Tools Affected | Cedar Governance Mode | +|---|---|---|---| +| **Tier 1** | Low Risk | `read_file`, `list_directory`, `grep_search` | **Auto-Approve** (No restrictions) | +| **Tier 2** | Medium Risk | `write_file`, `replace_file_content` outside `src/` | **Shadow-to-Enforce** (Alerts on directory drift) | +| **Tier 3** | High Risk | `execute_command` (Parallel Worker spawns, `skill-creator`) | **Interactive Authorization** (Requires `--yes` flags) | +| **Tier 4** | Critical Risk | Unsandboxed network downloads, global policy deletes | **Strict Interdiction** (Pre-authorized receipt required) | + +#### Concrete Cedar Policies for Development De-Risking + +```cedar +// 1. TIER 3: Prevent runaway token burn from parallel workers unless explicitly approved +forbid( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name == "execute_command" + && resource.args.contains("orchestrate-batch-refactor") + && !resource.args.contains("--yes") +}; + +// 2. TIER 3: Block dynamic, unverified skill creation to prevent Prompt Pollution +forbid( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name == "execute_command" + && resource.args.contains("skill-creator") + && !resource.args.contains("--manual-auth") +}; + +// 3. TIER 2: Enforce a timeout block on loop-prone environment/Docker setups +permit( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name in ["execute_command", "write_file"] + && resource.args.contains("devcontainer-setup") +} when { + // Shadow-observe execution state to abort loops after 3 failures + context.session.failure_count < 3 +}; +``` + +### Signed Receipts + +Every policy decision produces a signed receipt: + +```json +{ + "payload": { + "type": "protectmcp:decision", + "tool_name": "read_file", + "decision": "allow", + "policy_digest": "sha256:9d0fd4c9e72c1d5d", + "issued_at": "2026-04-05T14:32:04.102Z", + "issuer_id": "sb:issuer:de073ae64e43" + }, + "signature": { + "alg": "EdDSA", + "kid": "sb:issuer:de073ae64e43", + "sig": "2a3b5022..." + } +} +``` + +The receipt format follows [IETF Internet-Draft draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/). + +## Step-by-Step Guide + +### 1. Initialize Governance for a Project + +```bash +# Install and initialize hooks (Claude Code integration) +npx protect-mcp init-hooks + +# Or run as a standalone MCP gateway +npx protect-mcp serve +``` + +This creates a `protect-mcp.config.json` and a starter Cedar policy in your project root. + +### 2. Write Your First Policy + +Create `policy.cedar` in your project: + +```cedar +// Start permissive — allow everything in shadow mode +permit( + principal, + action == Action::"call_tool", + resource +); +``` + +### 3. Run in Shadow Mode (Observe First) + +```bash +# Shadow mode is the default — logs decisions without blocking +npx protect-mcp --policy policy.cedar -- node your-mcp-server.js +``` + +Review the shadow log to understand what your agent is doing before writing restrictive policies. + +### 4. Tighten and Enforce + +Once you understand the tool-call patterns, write specific policies: + +```cedar +// Allow file reads, deny writes outside src/ +permit( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name == "read_file" +}; + +permit( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name == "write_file" + && resource has args + && resource.args.path like "src/*" +}; + +// Deny everything else +forbid( + principal, + action == Action::"call_tool", + resource +); +``` + +Switch to enforce mode: + +```bash +npx protect-mcp --policy policy.cedar --enforce -- node your-mcp-server.js +``` + +### 5. Verify Receipts + +```bash +# Verify a single receipt +npx @veritasacta/verify receipt.json --key + +# Verify an audit bundle (multiple receipts + keys) +npx @veritasacta/verify bundle.json --bundle + +# Self-test the verifier (proves it works offline) +npx @veritasacta/verify --self-test +``` + +Exit codes: `0` = signature valid (proven authentic), `1` = signature invalid (proven tampered), `2` = verifier error (malformed input). + +## Examples + +### Example 1: Governance for a Claude Code Session + +```bash +# Initialize hooks +npx protect-mcp init-hooks + +# Claude Code now generates a signed receipt for every tool call. +# Receipts are stored in .protect-mcp/receipts/ +``` + +**Explanation:** After initialization, every tool call Claude Code makes is logged with a signed receipt. No tool calls are blocked (shadow mode). + +### Example 2: Restrict a Production MCP Server + +```cedar +// Only allow approved tools with rate limiting +permit( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name in [ + "get_customer", + "search_orders", + "list_products" + ] +}; + +forbid( + principal, + action == Action::"call_tool", + resource +) when { + resource.tool_name in [ + "delete_customer", + "modify_payment", + "execute_sql" + ] +}; +``` + +**Explanation:** A production MCP server that serves customer data. Read-only operations are permitted; destructive operations are blocked. + +### Example 3: Verify an Audit Bundle After an Incident + +```bash +# Export the session's audit bundle +npx protect-mcp export-bundle --session sess_abc123 --out audit.json + +# Verify every receipt in the bundle +npx @veritasacta/verify audit.json --bundle + +# Expected output: +# ✓ Bundle: VALID +# Total: 47 +# Passed: 47 +# Failed: 0 +``` + +**Explanation:** After an incident, export the audit bundle and verify that no receipts have been tampered with. The bundle contains all receipts from the session plus the signing keys needed for verification. + +## Best Practices + +- ✅ **Do:** Start in shadow mode and observe before enforcing +- ✅ **Do:** Use `policy_digest` to track which policy version produced each decision +- ✅ **Do:** Store receipts alongside your application logs for correlation +- ✅ **Do:** Pin the verifier version when integrating into CI (`@veritasacta/verify@0.2.5`) +- ❌ **Don't:** Skip shadow mode and go straight to enforce in production +- ❌ **Don't:** Trust `claimed_issuer_tier` without independent verification +- ❌ **Don't:** Treat a valid signature as proof the signer is trustworthy — it only proves the receipt has not been tampered with since signing + +## Troubleshooting + +### Problem: Receipts fail verification with `no_public_key` +**Symptoms:** `npx @veritasacta/verify receipt.json` returns exit 2 with `no_public_key` +**Solution:** Provide the public key explicitly: `--key <64 hex chars>`. The receipt does not embed the public key by default. Check `protect-mcp.config.json` for the issuer's public key. + +### Problem: Shadow mode shows unexpected denials +**Symptoms:** Shadow log shows `deny` decisions for tools you expected to be allowed +**Solution:** Check your Cedar policy ordering. Cedar evaluates `forbid` rules before `permit` rules — a broad `forbid` will override specific `permit` rules. + +### Problem: Enforce mode blocks a legitimate tool call +**Symptoms:** Agent reports a tool call was denied after switching to enforce mode +**Solution:** Add the tool to your permit policy or switch back to shadow mode: remove `--enforce` flag. Review the receipt's `deny_reason` field for the specific policy violation. + +## Related Skills + +- `@security-auditor` — General security auditing and compliance +- `@security-audit` — Code vulnerability scanning +- `@mcp-development` — MCP server development patterns + +## Additional Resources + +- [protect-mcp on npm](https://www.npmjs.com/package/protect-mcp) — MIT licensed +- [Cedar Policy Language](https://www.cedarpolicy.com/) — AWS open-source policy engine +- [IETF Draft: Signed Receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/) — Receipt format specification +- [@veritasacta/verify](https://www.npmjs.com/package/@veritasacta/verify) — Apache-2.0 verifier, works offline + +## Limitations +- Use this skill only when the task clearly matches the scope described above. +- Do not treat the output as a substitute for environment-specific validation, testing, or expert review. +- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing. diff --git a/AGENTS.md b/AGENTS.md index 34883b1..db9d01a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,63 +1,43 @@ -# Site contract +# AGENTS.md -## Gates +Community contract for agents working in this repository. Internal factory/site overlay: [`docs/factory-overlay.md`](docs/factory-overlay.md). Positioning: [`docs/DESIGN-PIVOT.md`](docs/DESIGN-PIVOT.md). -| Command | Purpose | -|---|---| -| `./scripts/harness/verify.sh` | Functional and static acceptance | -| `./scripts/harness/adversarial.sh` | Authorized local adversarial probes | - -Record `verification_scripts` as the site directory `scripts/harness` (exactly those -two scripts). Optional wrappers may remain at `scripts/verify.sh` / -`scripts/adversarial.sh` for humans and CI; they are outside the digest boundary. - -The corporate handoff fixes scope. The site manager assigns ADRs; site specialists write; -the root orchestrator dispatches nondelegating workers and runs gate commands; operations -excellence reviews immutable root-produced evidence. Work in isolated roots, never edit -corporate approval state, and never self-approve. A site role cannot return work to -corporate design; that boundary requires an explicit user rework authorization. - -Site id: `fidusgate`. Prior Cursor Harness v4 (compose profile) is under `_archives/harness-v4/`. - -## Definition of Done - -Hermetic (PR verify job): +FidusGate issues **signed Ed25519 receipts for MCP tool calls** and ships a runnable admin console (ledger, Cedar simulator, receipt verifier). It is not a generic “zero-trust agent governance platform” and **not a production-hardened security product**. -```bash -npx npm@10.9.2 ci -./scripts/verify.sh -``` +## Commands -Integration (main repo root or CI `integration` job — never from `.worktrees/`): +| Command | Purpose | +|---------|---------| +| `./scripts/harness/verify.sh` | Hermetic Definition of Done (lint, test, Cedar, threat-model) | +| `./scripts/verify.sh` | Wrapper → harness verify | +| `npm run bootstrap` | WASM build + local hooks | +| `npm run dev` | Gateway `:3001` + admin console `:3000` | +| `npm test` | Workspace tests | +| `npm run lint` | Biome + workspace lint | +| `bash scripts/cedar-validate.sh` | `policy.cedar` against `policy.cedarschema` | +| `./scripts/adversarial.sh` | Authorized adversarial probes (main root / CI; not worktrees) | -```bash -./scripts/integration-smoke.sh -./scripts/adversarial.sh -``` +Do not claim green from prose. Run the verify script and keep the output. -Do **not** put Docker or integration smoke inside `verify.sh`. Child green in a worktree does not imply main-stack green — see [`docs/harness/false-green-checklist.md`](docs/harness/false-green-checklist.md). +## Cedar and receipts -CI (`.github/workflows/ci.yml`) mirrors this two-tier split: +| Path | Role | +|------|------| +| `policy.cedar` / `policy.cedarschema` | Authorization policy and schema | +| `protect-mcp.config.json` | Gateway mode, issuer, receipts directory | +| `packages/cedar-daemon` | Rust Cedar PDP | +| `apps/secure-gateway` | MCP / `/api/authorize` hot path and receipt issuance | +| `packages/crypto-utils` | Ed25519 sign and verify | +| `apps/admin-dashboard` | Ledger, simulator, verifier | +| `.github/skills/cedar-mcp-receipts/` | Skill for tool gates, shadow-to-enforce, receipt verification | +| `docs/DESIGN-PIVOT.md` | Receipts-and-console positioning | -| Job | Runs | -|-----|------| -| `verify` | `./scripts/verify.sh` (stub canary → `npm ci` → lint → test → threat-model) | -| `integration` | `./scripts/integration-smoke.sh` then `./scripts/adversarial.sh` | +Skill body is adapted from `scopeblind/scopeblind-gateway` (`source_repo` on the skill). Do not claim originality of that material. -## Layout +## Never weaken fail-closed -| Path | Purpose | -|------|---------| -| `.corp-harness/site.json` | Corp-site binding (unbound until a program) | -| `specs/threat-model.yaml` | Adversarial deny cases | -| `docs/adr/0000-threat-model.md` | Threat-model ADR | -| `_archives/harness-v4/` | Archived Cursor Harness v4 compose surface | +Do not convert authorize, kill-switch, PDP, principal-signature, production-profile, or KMS-missing paths to fail-open. If Cedar, the daemon, or a production prerequisite is unavailable, **deny**. Shadow mode may log-without-block only when `protect-mcp.config.json` `mode` is explicitly `shadow` — never as a silent fallback from enforce. -## Commands +## Honesty -| Command | Purpose | -|---------|---------| -| `./scripts/verify.sh` | Hermetic Definition of Done | -| `./scripts/integration-smoke.sh` | Integration E2E (CI + main root; not worktrees) | -| `./scripts/adversarial.sh` | Tier-3 adversarial oracle (worktree denial) | -| `./scripts/check-stub-canary.sh` | Stub/placeholder detector (via verify) | +Keep demo and mock surfaces labeled as demo (local keys, JSON datastore, simulated syscalls/OIDC). Do not add sidecar features to compete with OpenFirma, Vectimus, Symbiont, or Permit Cedar Agent. Deepen receipts and the console. diff --git a/README.md b/README.md index cc0efc6..c6c9ef9 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,18 @@ # FidusGate -**Evergreen open-source reference** for zero-trust governance and runtime verification of **autonomous AI agent operations** — Cedar policy gates, Ed25519 receipts, MCP proxy enforcement, and a runnable admin console demo. +**Signed Ed25519 receipts for MCP tool calls**, with Cedar authorization and a runnable admin console (ledger, policy simulator, receipt verifier). -FidusGate shifts security left: programmatic access controls, signature verification, and sandboxed command auditing on active agentic workflows. It establishes explicit, policy-enforced boundaries around AI tool execution to reduce unauthorized modifications, privilege escalation, and prompt-injection-driven compromise. +Cedar evaluates each tool call; the gateway signs the decision; the dashboard lets you inspect and verify the receipt. This is a reference implementation — **not** a production-hardened security product. See [Status, Maturity & Mocks](#-status-maturity--mocks) and [docs/DESIGN-PIVOT.md](docs/DESIGN-PIVOT.md). -> **Scope:** Reference implementation and capability showcase — **not** a production-hardened security product. See [Status, Maturity & Mocks](#-status-maturity--mocks). +OpenFirma, Vectimus, Symbiont, and Permit Cedar Agent already run Cedar on the hot path. FidusGate’s job is the receipt and the console, not another generic “zero-trust agent governance platform.” + +### Why not OpenFirma + +- OpenFirma is a sidecar that intercepts outbound agent calls and evaluates Cedar locally. FidusGate is a demo MCP gateway plus an admin console you can run. +- OpenFirma signs capability tokens and sidecar audit events. FidusGate signs a per-tool-call Ed25519 decision receipt that the in-console verifier can check. +- OpenFirma does not ship this ledger / Cedar simulator / paste-a-receipt UX. That operator loop is the product here. + +> **Scope:** Reference implementation and capability showcase — **not** a production-hardened security product. [![CI](https://github.com/SafetyMP/FidusGate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SafetyMP/FidusGate/actions/workflows/ci.yml) [![Docker Publish](https://github.com/SafetyMP/FidusGate/actions/workflows/docker-publish.yml/badge.svg?branch=main)](https://github.com/SafetyMP/FidusGate/actions/workflows/docker-publish.yml) diff --git a/docs/DESIGN-PIVOT.md b/docs/DESIGN-PIVOT.md new file mode 100644 index 0000000..ce03a6c --- /dev/null +++ b/docs/DESIGN-PIVOT.md @@ -0,0 +1,37 @@ +# Design pivot: receipts, not a generic governance platform + +**Date:** September 2026 +**Scope:** Positioning and documentation only. This change does not rewrite the app. + +## Stop competing here + +OpenFirma, Vectimus, Symbiont, and Permit Cedar Agent already put Cedar on the authorization hot path. FidusGate should not present itself as another generic “zero-trust agent governance platform.” That category is contested, and the phrase over-claims what this repository is. + +## What the product is + +FidusGate is **signed Ed25519 receipts for MCP tool calls**, plus a **runnable admin console** (transaction ledger, Cedar policy simulator, receipt verifier). + +Cedar still authorizes each tool call. The differentiated surface is the receipt and the console that lets a human inspect, simulate, and verify those decisions. + +This remains a **reference implementation — not a production-hardened security product.** Local key storage, the JSON datastore, and simulated syscall/OIDC pieces are illustrative. Do not market them as production controls. + +## Why not OpenFirma + +OpenFirma is a sidecar enforcement boundary: intercept outbound calls, evaluate Cedar locally, fail closed, and write a signed audit event. It does not ship this console or receipt UX. + +- OpenFirma wraps an agent process. FidusGate is a demo MCP gateway plus an admin console you run to see Cedar decisions and receipts. +- OpenFirma signs capability tokens and sidecar audit events. FidusGate signs a per-tool-call Ed25519 decision receipt that the dashboard verifier can check. +- OpenFirma has no in-repo ledger, Cedar simulator, or paste-a-receipt console. That operator loop is FidusGate’s product. + +Vectimus, Symbiont, and Permit Cedar Agent likewise already do Cedar-on-the-hot-path. Do not add features to “keep up” with those sidecars. Deepen receipts and the console. + +## Next build slice (not in this PR) + +- If the MCP gateway is a real server an operator can point a client at, **publish an MCP server listing**. +- If `mcp` is only a GitHub topic or label, **drop the `mcp` topic** so the storefront does not imply a listed server. + +## Invariants that do not change + +- Fail-closed authorize, kill-switch, PDP, principal-signature, and production-profile paths stay fail-closed. +- Demo and mock surfaces stay labeled as demo. +- Do not claim production hardening, certification, or originality of Cedar-on-the-hot-path. diff --git a/docs/README.md b/docs/README.md index 089ff1b..f1da91b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,8 @@ Use the links below to navigate our primary documentation suite: | Document Guide | Path | Focus & Target Audience | | :--- | :--- | :--- | +| **Design pivot (September 2026)** | [DESIGN-PIVOT.md](./DESIGN-PIVOT.md) | Receipts + admin console positioning vs Cedar sidecars (OpenFirma and others) | +| **Factory / site overlay** | [factory-overlay.md](./factory-overlay.md) | Internal harness contract; community agents start at [`AGENTS.md`](../AGENTS.md) | | **GitHub storefront (maintainers)** | [community/github-presentation.md](./community/github-presentation.md) | About panel, demo GIF regen, badges, social preview, community-health target | | **Branch protection (maintainers)** | [community/github-branch-protection.md](./community/github-branch-protection.md) | Optional required checks on `main` | | **Marketing assets index** | [assets/README.md](./assets/README.md) | `demo.gif`, screenshots, social preview source | @@ -28,8 +30,10 @@ Use the links below to navigate our primary documentation suite: FidusGate models security boundaries by mapping available operations to dedicated, domain-scoped playbooks under the `skills/` tree. These files establish context variables parsed by Cedar policies: ### Governance & Security Skills +* **`cedar-mcp-receipts`** | [SKILL.md](../.github/skills/cedar-mcp-receipts/SKILL.md) + *Authorize MCP tool calls with Cedar and verify Ed25519 receipts (adapted from scopeblind; not a prompt-injection classifier).* * **`protect-mcp-governance`** | [SKILL.md](../skills/protect-mcp-governance/SKILL.md) - *Main Cedar authorization template rules, transaction verification standards, and public-key audits.* + *Historical copy of the same skill under the older name.* * **`agentic-actions-auditor`** | [SKILL.md](../skills/agentic-actions-auditor/SKILL.md) *Static analysis definitions mapping prompt injection vulnerabilities and hardening workflows.* * **`security-sme`** | [SKILL.md](../skills/security-sme/SKILL.md) diff --git a/docs/community/github-presentation.md b/docs/community/github-presentation.md index 7475c89..dd433bb 100644 --- a/docs/community/github-presentation.md +++ b/docs/community/github-presentation.md @@ -6,10 +6,10 @@ Audience: **maintainers**. This page captures the repository's GitHub "storefron Set in **Settings** or the gear icon next to About on the repo home. Keep it to a single sentence so it reads well in search results and the sidebar: -> Evergreen OSS reference for zero-trust AI agent governance — Cedar policy gates, Ed25519 receipts, and a runnable admin console demo. Not a production-hardened security product. +> Signed Ed25519 receipts for MCP tool calls — Cedar authorization plus a runnable admin console (ledger, simulator, verifier). Not a production-hardened security product. - **Website:** `https://github.com/SafetyMP/FidusGate#demo` (or a future hosted demo URL). -- **Topics:** `ai-agents`, `agent-security`, `zero-trust`, `cedar`, `mcp`, `devsecops`, `reference-architecture`, `open-source`, `typescript`, `react`, `nodejs`, `docker`, `supply-chain-security`. +- **Topics:** `ai-agents`, `agent-security`, `cedar`, `ed25519`, `devsecops`, `reference-architecture`, `open-source`, `typescript`, `react`, `nodejs`, `docker`, `supply-chain-security`. Keep `mcp` only if the gateway is a listed MCP server; otherwise drop it (see [DESIGN-PIVOT.md](../DESIGN-PIVOT.md)). ## README badges diff --git a/docs/factory-overlay.md b/docs/factory-overlay.md new file mode 100644 index 0000000..1f1738b --- /dev/null +++ b/docs/factory-overlay.md @@ -0,0 +1,65 @@ +# Site contract overlay + +Internal factory/site overlay for `site_id: fidusgate`. Community agents start at [`AGENTS.md`](../AGENTS.md). Do not treat this file as the public product contract. + +## Gates + +| Command | Purpose | +|---|---| +| `./scripts/harness/verify.sh` | Functional and static acceptance | +| `./scripts/harness/adversarial.sh` | Authorized local adversarial probes | + +Record `verification_scripts` as the site directory `scripts/harness` (exactly those +two scripts). Optional wrappers may remain at `scripts/verify.sh` / +`scripts/adversarial.sh` for humans and CI; they are outside the digest boundary. + +The corporate handoff fixes scope. The site manager assigns ADRs; site specialists write; +the root orchestrator dispatches nondelegating workers and runs gate commands; operations +excellence reviews immutable root-produced evidence. Work in isolated roots, never edit +corporate approval state, and never self-approve. A site role cannot return work to +corporate design; that boundary requires an explicit user rework authorization. + +Site id: `fidusgate`. Prior Cursor Harness v4 (compose profile) is under `_archives/harness-v4/`. + +## Definition of Done + +Hermetic (PR verify job): + +```bash +npx npm@10.9.2 ci +./scripts/verify.sh +``` + +Integration (main repo root or CI `integration` job — never from `.worktrees/`): + +```bash +./scripts/integration-smoke.sh +./scripts/adversarial.sh +``` + +Do **not** put Docker or integration smoke inside `verify.sh`. Child green in a worktree does not imply main-stack green — see [`docs/harness/false-green-checklist.md`](harness/false-green-checklist.md). + +CI (`.github/workflows/ci.yml`) mirrors this two-tier split: + +| Job | Runs | +|-----|------| +| `verify` | `./scripts/verify.sh` (stub canary → `npm ci` → lint → test → threat-model) | +| `integration` | `./scripts/integration-smoke.sh` then `./scripts/adversarial.sh` | + +## Layout + +| Path | Purpose | +|------|---------| +| `.corp-harness/site.json` | Corp-site binding (unbound until a program) | +| `specs/threat-model.yaml` | Adversarial deny cases | +| `docs/adr/0000-threat-model.md` | Threat-model ADR | +| `_archives/harness-v4/` | Archived Cursor Harness v4 compose surface | + +## Commands + +| Command | Purpose | +|---------|---------| +| `./scripts/verify.sh` | Hermetic Definition of Done | +| `./scripts/integration-smoke.sh` | Integration E2E (CI + main root; not worktrees) | +| `./scripts/adversarial.sh` | Tier-3 adversarial oracle (worktree denial) | +| `./scripts/check-stub-canary.sh` | Stub/placeholder detector (via verify) | diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..8bbfbb3 --- /dev/null +++ b/llms.txt @@ -0,0 +1,26 @@ +# FidusGate + +> Signed Ed25519 receipts for MCP tool calls, with Cedar authorization and a runnable admin console (ledger, policy simulator, receipt verifier). Reference implementation — not a production-hardened security product. + +FidusGate does not compete as a generic zero-trust agent governance platform. OpenFirma, Vectimus, Symbiont, and Permit Cedar Agent already put Cedar on the hot path. This repo’s product is the receipt plus the console. + +## Docs + +- [README](https://github.com/SafetyMP/FidusGate/blob/main/README.md): product lede, demo, quick start +- [Design pivot](https://github.com/SafetyMP/FidusGate/blob/main/docs/DESIGN-PIVOT.md): receipts-and-console positioning vs Cedar sidecars +- [AGENTS.md](https://github.com/SafetyMP/FidusGate/blob/main/AGENTS.md): community contract (commands, Cedar/receipt paths, fail-closed) +- [Documentation portal](https://github.com/SafetyMP/FidusGate/blob/main/docs/README.md) +- [Architecture](https://github.com/SafetyMP/FidusGate/blob/main/docs/ARCHITECTURE.md) +- [Factory overlay](https://github.com/SafetyMP/FidusGate/blob/main/docs/factory-overlay.md): internal site/harness contract +- [Security policy](https://github.com/SafetyMP/FidusGate/blob/main/.github/SECURITY.md) +- [Contributing](https://github.com/SafetyMP/FidusGate/blob/main/CONTRIBUTING.md) + +## Skills + +- [cedar-mcp-receipts](https://github.com/SafetyMP/FidusGate/blob/main/.github/skills/cedar-mcp-receipts/SKILL.md): authorize MCP tool calls with Cedar and verify Ed25519 receipts (adapted from scopeblind/scopeblind-gateway; not a prompt-injection classifier) + +## Optional + +- [MCP 2026-07-28 migration](https://github.com/SafetyMP/FidusGate/blob/main/docs/mcp-2026-07-28-migration.md) +- [OWASP MCP Top 10 ADR](https://github.com/SafetyMP/FidusGate/blob/main/docs/adr/0001-owasp-mcp-top-10.md) +- [GitHub storefront playbook](https://github.com/SafetyMP/FidusGate/blob/main/docs/community/github-presentation.md) From 60e4dd3887daa58da0f6ac4c3feab1874e9aa96a Mon Sep 17 00:00:00 2001 From: Sage Hart - AI Date: Sat, 5 Sep 2026 13:22:06 -0500 Subject: [PATCH 2/3] Name the thesis piece this repo proves and the join it does not. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index c6c9ef9..d934bd7 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Cedar evaluates each tool call; the gateway signs the decision; the dashboard le OpenFirma, Vectimus, Symbiont, and Permit Cedar Agent already run Cedar on the hot path. FidusGate’s job is the receipt and the console, not another generic “zero-trust agent governance platform.” +> **In the SafetyMP thesis:** Agent path for **generic MCP tool calls**. This does not authorize EHS, clinical, or finance operations inside those systems of record. See the [portfolio README](https://github.com/SafetyMP/SafetyMP). + ### Why not OpenFirma - OpenFirma is a sidecar that intercepts outbound agent calls and evaluates Cedar locally. FidusGate is a demo MCP gateway plus an admin console you can run. From 21ed9e33928c79c120d99781f8f5093d36253a40 Mon Sep 17 00:00:00 2001 From: Sage Hart - AI Date: Sat, 5 Sep 2026 13:29:17 -0500 Subject: [PATCH 3/3] State the permit rule in operator language, not as a thesis footnote. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d934bd7..795d7bb 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Cedar evaluates each tool call; the gateway signs the decision; the dashboard le OpenFirma, Vectimus, Symbiont, and Permit Cedar Agent already run Cedar on the hot path. FidusGate’s job is the receipt and the console, not another generic “zero-trust agent governance platform.” -> **In the SafetyMP thesis:** Agent path for **generic MCP tool calls**. This does not authorize EHS, clinical, or finance operations inside those systems of record. See the [portfolio README](https://github.com/SafetyMP/SafetyMP). +> **Permit rule:** A tool call without a verifiable receipt did not happen. This path is generic MCP, not EHS/clinical/finance writes in those SoRs. Same instinct: [SafetyMP](https://github.com/SafetyMP/SafetyMP). ### Why not OpenFirma