Skip to content

Commit c342825

Browse files
imran-siddiqueCopilot
imran-siddique
and
Copilot
committed
docs: add reference integration example for plugin marketplace governance (#427)
Add a complete reference example showing how to integrate agent-governance-toolkit into a GitHub-based plugin marketplace: - README with architecture diagram and 5-step integration guide - GitHub Actions workflow (3-job CI: validate → evaluate → verify) - Marketplace policy (MCP server allowlist/blocklist) - Plugin safety policy (tool restrictions, token limits) - Example compliant and non-compliant plugin manifests Closes #427 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent f022329 commit c342825

File tree

6 files changed

+499
-0
lines changed

6 files changed

+499
-0
lines changed

‎examples/marketplace-governance/.github/workflows/plugin-governance.yml‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Plugin Governance CI — validates plugins contributed via pull requests
2+
#
3+
# This workflow runs on PRs that modify files under plugins/ and enforces
4+
# marketplace policies before a plugin can be merged.
5+
#
6+
# Three jobs run in sequence:
7+
# 1. validate-manifest — schema-checks each changed plugin.json
8+
# 2. evaluate-policy — batch-evaluates all plugins against policy
9+
# 3. governance-verify — full governance attestation (OWASP controls)
10+
11+
name: Plugin Governance
12+
13+
on:
14+
pull_request:
15+
paths:
16+
- 'plugins/**'
17+
- 'policies/**'
18+
19+
permissions:
20+
contents: read
21+
pull-requests: write
22+
23+
jobs:
24+
# ------------------------------------------------------------------
25+
# Job 1: Validate that each changed plugin has a well-formed manifest
26+
# ------------------------------------------------------------------
27+
validate-manifest:
28+
name: Validate Plugin Manifests
29+
runs-on: ubuntu-latest
30+
31+
steps:
32+
- name: Checkout repository
33+
uses: actions/checkout@v4
34+
35+
- name: Detect changed plugins
36+
id: changes
37+
run: |
38+
PLUGINS=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
39+
| grep '^plugins/' \
40+
| cut -d'/' -f1-2 \
41+
| sort -u)
42+
echo "plugins<<EOF" >> "$GITHUB_OUTPUT"
43+
echo "$PLUGINS" >> "$GITHUB_OUTPUT"
44+
echo "EOF" >> "$GITHUB_OUTPUT"
45+
echo "Found changed plugin directories:"
46+
echo "$PLUGINS"
47+
48+
- name: Validate each manifest
49+
uses: microsoft/agent-governance-toolkit/action@v2
50+
with:
51+
command: marketplace-verify
52+
manifest-path: plugins/
53+
output-format: text
54+
55+
# ------------------------------------------------------------------
56+
# Job 2: Evaluate all plugins against marketplace and safety policies
57+
# ------------------------------------------------------------------
58+
evaluate-policy:
59+
name: Evaluate Marketplace Policy
60+
runs-on: ubuntu-latest
61+
needs: validate-manifest
62+
63+
steps:
64+
- name: Checkout repository
65+
uses: actions/checkout@v4
66+
67+
# Option A: Use the GitHub Action (recommended)
68+
- name: Run governance action
69+
uses: microsoft/agent-governance-toolkit/action@v2
70+
with:
71+
command: policy-evaluate
72+
policy-path: policies/marketplace-policy.yaml
73+
output-format: json
74+
75+
# Option B: Direct CLI usage (alternative)
76+
- name: Set up Python
77+
uses: actions/setup-python@v5
78+
with:
79+
python-version: '3.12'
80+
81+
- name: Install toolkit
82+
run: pip install --quiet agent-governance-toolkit[full]
83+
84+
- name: Batch evaluate plugins
85+
run: |
86+
python -m agent_marketplace.batch evaluate-batch plugins/ \
87+
--policy policies/plugin-safety.yaml \
88+
--format markdown \
89+
--output governance-report.md
90+
91+
- name: Upload report
92+
if: always()
93+
uses: actions/upload-artifact@v4
94+
with:
95+
name: governance-report
96+
path: governance-report.md
97+
98+
# ------------------------------------------------------------------
99+
# Job 3: Full governance verification (OWASP controls attestation)
100+
# ------------------------------------------------------------------
101+
governance-verify:
102+
name: Governance Verification
103+
runs-on: ubuntu-latest
104+
needs: evaluate-policy
105+
106+
steps:
107+
- name: Checkout repository
108+
uses: actions/checkout@v4
109+
110+
- name: Run governance verification
111+
id: verify
112+
uses: microsoft/agent-governance-toolkit/action@v2
113+
with:
114+
command: governance-verify
115+
output-format: json
116+
fail-on-warning: 'true'
117+
118+
- name: Report status
119+
if: always()
120+
run: |
121+
echo "## Governance Status" >> "$GITHUB_STEP_SUMMARY"
122+
echo "" >> "$GITHUB_STEP_SUMMARY"
123+
echo "- **Status:** ${{ steps.verify.outputs.status }}" >> "$GITHUB_STEP_SUMMARY"
124+
echo "- **Controls passed:** ${{ steps.verify.outputs.controls-passed }} / ${{ steps.verify.outputs.controls-total }}" >> "$GITHUB_STEP_SUMMARY"

‎examples/marketplace-governance/README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Governance for GitHub-Based Plugin Marketplaces
2+
3+
⚠️ **IMPORTANT:** This is a SAMPLE integration example provided as a starting point.
4+
You MUST review, customize, and extend these configurations for your specific
5+
use case before deploying to production.
6+
7+
## Overview
8+
9+
This example demonstrates how to integrate the Agent Governance Toolkit into a
10+
GitHub-based plugin marketplace. Plugins are contributed via pull requests,
11+
validated automatically in CI, and promoted through environments (dev → staging →
12+
production) only after passing governance checks.
13+
14+
The pattern enforces:
15+
16+
- **MCP server allowlists** — only approved servers may be referenced by plugins
17+
- **Plugin type restrictions** — control which plugin categories are accepted
18+
- **Signature requirements** — require Ed25519 signatures in production
19+
- **Tool safety rules** — block dangerous tools and enforce token budgets
20+
- **Batch evaluation** — scan all plugins on every PR for policy drift
21+
22+
## Architecture
23+
24+
```
25+
┌──────────────────────────────────────────────────────────────┐
26+
│ Plugin Marketplace (GitHub) │
27+
│ │
28+
│ contributor ──► Pull Request ──► CI Governance Pipeline │
29+
│ │
30+
│ ┌────────────────────────────────────────────────────────┐ │
31+
│ │ PR Workflow │ │
32+
│ │ │ │
33+
│ │ ┌──────────────┐ ┌───────────────┐ ┌──────────┐ │ │
34+
│ │ │ Validate │──►│ Evaluate │──►│ Verify │ │ │
35+
│ │ │ Manifest │ │ Policy │ │ Governance│ │ │
36+
│ │ └──────────────┘ └───────────────┘ └──────────┘ │ │
37+
│ │ │ │ │ │ │
38+
│ │ ▼ ▼ ▼ │ │
39+
│ │ plugin.json marketplace- governance │ │
40+
│ │ schema check policy.yaml attestation │ │
41+
│ │ plugin-safety.yaml │ │
42+
│ └────────────────────────────────────────────────────────┘ │
43+
│ │ │
44+
│ ┌─────────┴─────────┐ │
45+
│ ▼ ▼ │
46+
│ ✅ Compliant ❌ Non-compliant │
47+
│ Merge + promote Block PR │
48+
│ to environment with annotations │
49+
└──────────────────────────────────────────────────────────────┘
50+
```
51+
52+
## Directory Structure
53+
54+
```
55+
examples/marketplace-governance/
56+
├── README.md # This file
57+
├── .github/
58+
│ └── workflows/
59+
│ └── plugin-governance.yml # CI workflow for PR validation
60+
├── policies/
61+
│ ├── marketplace-policy.yaml # MCP allowlist and plugin controls
62+
│ └── plugin-safety.yaml # Tool restrictions and token budgets
63+
└── plugins/
64+
├── example-compliant/
65+
│ └── plugin.json # Passes all governance checks
66+
└── example-non-compliant/
67+
└── plugin.json # Uses a blocked MCP server
68+
```
69+
70+
## Step-by-Step Integration Guide
71+
72+
### 1. Add Governance Policies to Your Repo
73+
74+
Copy the policy files from `policies/` into your marketplace repository:
75+
76+
```bash
77+
cp -r policies/ your-marketplace/policies/
78+
```
79+
80+
The two policy files serve different purposes:
81+
82+
| File | Purpose |
83+
|------|---------|
84+
| `marketplace-policy.yaml` | Controls which MCP servers, plugin types, and signing requirements are enforced |
85+
| `plugin-safety.yaml` | Agent-level safety rules — tool restrictions, file access auditing, token budgets |
86+
87+
See the inline comments in each file for customization guidance.
88+
89+
### 2. Add the GitHub Action to Your PR Workflow
90+
91+
Copy `.github/workflows/plugin-governance.yml` into your repository. The workflow
92+
triggers on pull requests that modify files under `plugins/` and runs three jobs:
93+
94+
1. **validate-manifest** — Checks that each changed plugin has a valid `plugin.json`
95+
2. **evaluate-policy** — Evaluates all plugins against `marketplace-policy.yaml`
96+
3. **governance-verify** — Runs the full governance attestation suite
97+
98+
```yaml
99+
- uses: microsoft/agent-governance-toolkit/action@v2
100+
with:
101+
command: marketplace-verify
102+
manifest-path: plugins/my-plugin/plugin.json
103+
```
104+
105+
### 3. Configure Marketplace Policy
106+
107+
Edit `policies/marketplace-policy.yaml` to match your marketplace:
108+
109+
- **MCP server allowlist** — Add the MCP servers your marketplace trusts
110+
(e.g., `code-search`, `ms-learn`, `playwright`). Any plugin referencing an
111+
unlisted server will be rejected.
112+
- **Plugin types** — Restrict to the types you accept (`integration`, `agent`,
113+
`policy_template`, `validator`).
114+
- **Signature requirements** — Set `require_signature: true` for production to
115+
enforce Ed25519 plugin signing.
116+
117+
### 4. Configure Plugin Safety Policy
118+
119+
Edit `policies/plugin-safety.yaml` to define agent-level safety rules:
120+
121+
- **Tool restrictions** — Block dangerous tools like `shell_exec`, `eval`, and
122+
`file_delete` to prevent destructive actions.
123+
- **Audit rules** — Log sensitive operations (e.g., file access) without
124+
blocking them.
125+
- **Token budgets** — Cap the maximum tokens per tool call to prevent runaway
126+
costs.
127+
128+
### 5. Add Pre-Commit Hooks for Local Feedback
129+
130+
Give plugin contributors fast local feedback before they push:
131+
132+
```bash
133+
# Install the toolkit
134+
pip install agent-governance-toolkit[full]
135+
136+
# Validate a single manifest
137+
python -m agent_marketplace.cli_commands verify plugins/my-plugin/plugin.json
138+
139+
# Batch-evaluate all plugins against policy
140+
python -m agent_marketplace.batch evaluate-batch plugins/ \
141+
--policy policies/marketplace-policy.yaml \
142+
--format text
143+
```
144+
145+
You can wire this into a Git pre-commit hook or use [pre-commit](https://pre-commit.com/).
146+
147+
## Customization Points
148+
149+
| What | Where | Notes |
150+
|------|-------|-------|
151+
| Allowed MCP servers | `policies/marketplace-policy.yaml` → `mcp_servers.allowed` | Add/remove servers as your trust boundary changes |
152+
| Blocked MCP servers | `policies/marketplace-policy.yaml` → `mcp_servers.blocked` | Use blocklist mode for open marketplaces |
153+
| Plugin type restrictions | `policies/marketplace-policy.yaml` → `allowed_plugin_types` | Remove to allow all types |
154+
| Signature enforcement | `policies/marketplace-policy.yaml` → `require_signature` | `false` for dev, `true` for production |
155+
| Dangerous tool rules | `policies/plugin-safety.yaml` → `rules[]` | Add rules matching your security posture |
156+
| Token budgets | `policies/plugin-safety.yaml` → `rules[]` | Adjust `max_tokens` per your cost tolerance |
157+
| CI trigger paths | `.github/workflows/plugin-governance.yml` → `paths` | Narrow or widen the trigger scope |
158+
| Toolkit version | Action input `toolkit-version` | Pin to a specific version for reproducibility |
159+
| Output format | Action input `output-format` | `json` for machine-readable, `text` for human-readable |
160+
161+
## Related Tutorials
162+
163+
- [Tutorial 07 — MCP Security Gateway](../../docs/tutorials/07-mcp-security-gateway.md):
164+
Deep dive into MCP server allowlisting and tool-poisoning detection
165+
- [Tutorial 10 — Plugin Marketplace](../../docs/tutorials/10-plugin-marketplace.md):
166+
End-to-end plugin lifecycle — discovery, installation, verification, and signing
167+
- [Tutorial 18 — Compliance Verification](../../docs/tutorials/18-compliance-verification.md):
168+
Governance attestation and compliance evidence generation
169+
170+
## Related
171+
172+
- [Policies](../policies/) — Additional sample governance policies
173+
- [Quickstart](../quickstart/) — One-file governed agents for popular frameworks

‎examples/marketplace-governance/plugins/example-compliant/plugin.json‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
"name": "code-review-assistant",
3+
"description": "An agent plugin that performs automated code reviews using approved MCP servers for code search and documentation lookup.",
4+
"version": "1.0.0",
5+
"author": "marketplace-contrib",
6+
"skills": [
7+
{
8+
"name": "review-pull-request",
9+
"description": "Analyzes pull request diffs for common issues"
10+
},
11+
{
12+
"name": "suggest-improvements",
13+
"description": "Suggests code quality improvements based on best practices"
14+
}
15+
],
16+
"agents": [
17+
{
18+
"name": "reviewer",
19+
"model": "gpt-4o",
20+
"instructions": "You are a code review assistant. Analyze diffs and suggest improvements."
21+
}
22+
],
23+
"mcps": [
24+
{
25+
"name": "code-search",
26+
"url": "https://mcp.github.dev/code-search",
27+
"tools": ["search_code", "get_file_contents"]
28+
},
29+
{
30+
"name": "ms-learn",
31+
"url": "https://mcp.microsoft.com/ms-learn",
32+
"tools": ["search_docs", "get_article"]
33+
}
34+
]
35+
}

‎examples/marketplace-governance/plugins/example-non-compliant/plugin.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "risky-automation-tool",
3+
"description": "An agent plugin that automates tasks using unrestricted shell access and filesystem writes.",
4+
"version": "0.9.0",
5+
"author": "unknown-contributor",
6+
"skills": [
7+
{
8+
"name": "run-script",
9+
"description": "Executes arbitrary shell scripts on the host"
10+
}
11+
],
12+
"agents": [
13+
{
14+
"name": "automator",
15+
"model": "gpt-4o",
16+
"instructions": "You are an automation agent. Execute scripts as requested."
17+
}
18+
],
19+
"mcps": [
20+
{
21+
"name": "shell-exec",
22+
"command": "/bin/bash",
23+
"tools": ["shell_exec", "os_system", "subprocess_run"]
24+
},
25+
{
26+
"name": "filesystem-write",
27+
"command": "fs-server --mode=write",
28+
"tools": ["file_write_root", "file_delete", "rmtree"]
29+
}
30+
]
31+
}

0 commit comments

Comments
 (0)