Security-Focused GitHub Copilot Agents Architecture

This repository is a reusable approach for building, governing, and operating security-focused GitHub Copilot agents across:

• VS Code with the GitHub Copilot extension
• GitHub.com Copilot and Copilot cloud agent
• DevSecOps, CI/CD, and secure code review workflows using GitHub Copilot CLI

The package is intentionally platform-neutral where possible and uses native GitHub/VS Code customization primitives where supported:

Capability	Location in this starter	Primary use
Repository-wide instructions	.github/copilot-instructions.md	Always-on secure-by-design rules, build/test expectations, compliance guardrails
Agent instructions	AGENTS.md	Multi-agent compatible instructions for Copilot CLI, VS Code, cloud agents, and other tools that support AGENTS.md
Path-specific instructions	.github/instructions/*.instructions.md	Secure rules scoped by file type, domain, or workflow
Prompt files	.github/prompts/*.prompt.md	Reusable slash-command style workflows for threat modeling, reviews, testing, and compliance evidence
Custom agents	.github/agents/security-master.agent.md + .github/agents/*.agent.md	One master security agent that delegates to specialist subagents with least-privilege tool access
Agent skills	.github/skills/*/SKILL.md	Portable task packages with repeatable workflows, templates, and scripts
Hooks	.github/hooks/*.json + scripts/hooks/*	Deterministic enforcement, audit logging, validation, and command blocking
MCP config	.vscode/mcp.json	Secure integration with tools such as GitHub, security scanners, evidence stores, and policy services
CI/CD examples	.github/workflows/*.yml	Copilot CLI secure review, agent governance checks, and evidence packaging

Recommended rollout model

1. Pilot in a template repository with security-master as the only default user-facing agent and specialist subagents behind it.
2. Promote stable standards to organization-level instructions and agents after security approval.
3. Introduce hooks and MCP servers in controlled tiers: read-only first, write-capable only after risk review.
4. Use central governance through CODEOWNERS, branch protection, required workflows, audit log streaming, and AI customization reviews.
5. Treat agent behavior as production code: version, test, approve, monitor, and retire agents like any other enterprise automation.

File tree

.
├── AGENTS.md
├── docs/
├── .github/
│   ├── copilot-instructions.md
│   ├── agents/
│   ├── instructions/
│   ├── prompts/
│   ├── skills/
│   ├── hooks/
│   └── workflows/
├── .vscode/
├── scripts/
└── policy/

Agent hierarchy

The design uses one master security agent as the default entry point:

security-master
├── security-architect
├── threat-modeler
├── secure-code-reviewer
├── appsec-remediator
├── devsecops-pipeline-engineer
├── secrets-supply-chain-analyst
└── compliance-evidence-analyst

security-master performs task classification, delegation, conflict resolution, evidence synthesis, and escalation. The specialist files remain in .github/agents/, but they now declare role: subagent, parent-agent: security-master, and user-invocable: false by default.

Architecture summary

The architecture uses a layered control plane:

• Governance plane: policies, lifecycle, ownership, approvals, audit, compliance mappings.
• Context plane: instructions, prompts, skills, AGENTS.md, approved reference material.
• Agent execution plane: VS Code local agents, GitHub.com cloud agents, and Copilot CLI in developer workstations or CI/CD.
• Tool plane: built-in tools, MCP tools, scanners, SBOM tools, dependency tools, GitHub APIs, evidence repositories.
• Guardrail plane: hooks, branch rulesets, protected environments, permissions, content exclusion, secret scanning, and workflow gates.
• Evidence plane: PR comments, SARIF, SBOMs, signed artifacts, AI review summaries, audit log events, and compliance evidence.

See docs/01-architecture.md and docs/02-platform-design.md for the full design.

Important security notes

• Do not give agents broad write access by default.
• Do not expose production secrets, regulated data, CUI, PCI cardholder data, customer PII, or confidential architecture data through MCP servers unless an explicit data-flow and control review has been completed.
• Do not rely on natural-language instructions alone for high-risk controls. Use hooks, CI checks, branch protection, required reviewers, and policy-as-code.
• Use read-only MCP tokens whenever possible.
• Use short-lived credentials, OIDC, and environment-scoped secrets for CI/CD.
• Require human approval for production-impacting changes.

Quick start

1. Copy the .github, .vscode, docs, scripts, and policy folders into a pilot repository.
2. Update .github/copilot-instructions.md with the repository's actual build, test, and deployment commands.
3. Enable VS Code discovery for organization-level instructions/agents only after pilot approval; publish security-master first and keep subagents exception-invocable by policy.
4. Review .vscode/mcp.json; remove or replace placeholder MCP servers before enabling.
5. Enable required workflows: agent-governance-check.yml, secret scanning, CodeQL, dependency review, and branch rulesets.
6. Assign CODEOWNERS for agent customizations and require AppSec approval.

Maintenance model

• Review agents quarterly and after major Copilot, VS Code, or GitHub policy changes.
• Track agent versions in docs/10-runbook.md and policy/agent-registry.yml.
• Archive deprecated agents by moving files to .github/agents/_deprecated and disabling workflows that invoke them.
• Stream enterprise and organization audit logs to SIEM for long-term evidence retention.