Home

Welcome to the gh-advsec-devsecops wiki!

This wiki documents how to leverage GitHub Copilot Custom Agents for DevSecOps workflows. Custom agents are specialized versions of GitHub Copilot that you can tailor to your unique workflows, coding conventions, and security requirements. Think of them as hiring a specialist consultant for your codebase—except this one never takes coffee breaks.

Key References

Resource	Description
microsoft/hve-core	HVE Core repository with security plan templates and custom agent examples
Prepare for Custom Agents (Organization)	Official GitHub documentation for setting up custom agents at the organization level
About Custom Agents	GitHub's conceptual overview of custom agents, their capabilities, and configuration options
Build Your Own GitHub Copilot Agent	Comprehensive tutorial by Jenna Massardo on creating custom agents from scratch

---

Security Plan Creator Custom Agent

The Security Plan Creator is a custom GitHub Copilot agent designed to analyze infrastructure-as-code (IaC) templates and generate comprehensive security plans. This agent automates the traditionally manual process of threat modeling and security assessment, producing detailed documentation that includes threat matrices, risk heat maps, and prioritized remediation steps.

The screenshot below shows the Security Plan Creator agent in action within GitHub Copilot Chat. The agent analyzes Bicep or ARM templates and walks through a multi-phase security assessment process:

Phase 3: Threat Assessment

During the Threat Assessment phase, the Security Plan Creator agent performs a comprehensive analysis of potential security threats using the STRIDE methodology (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege). The agent evaluates each identified threat against the specific infrastructure components and assigns risk levels based on likelihood and impact.

The screenshot below demonstrates the agent generating threat assessments, categorizing threats by type (Network Security, Identity Management, Privileged Access, Data Protection, etc.), and calculating risk scores:

Phase 5: Sample Security Plan Outputs

The Security Plan Creator generates detailed markdown documents containing:

• Executive Summary with security posture highlights and areas requiring attention
• System Architecture Diagrams showing component relationships
• Data Flow Diagrams with encryption and authentication details
• Threat Summary Matrix with likelihood, impact, and risk levels
• Detailed Mitigation Recommendations with Bicep code samples
• Implementation Checklists prioritized by criticality (P1/P2/P3)

Note: Output is non-deterministic, meaning each run may produce slightly different results based on the AI's analysis. This is expected behavior and reflects the comprehensive nature of the threat modeling process.

Sample Outputs:

• security-plan-sample-web-app.md (hve-core)
• security-plan-sample-web-app.md (this repo)

Multi-Application Support - The agent can analyze multiple applications or entire infrastructure repositories at once:

• security-plan-gh-aspnet-webapp.md

---

Custom Agents

Custom agents live in your repository's .github/agents/ directory. Each agent is defined using a Markdown file (.agent.md) containing YAML frontmatter for configuration and markdown content for instructions. This allows you to encode your conventions, frameworks, and desired outcomes directly into Copilot.

The screenshot below shows the repository structure with custom agents visible in the .github/agents/ folder. Each .agent.md file represents a specialized agent with its own role, capabilities, and instructions:

Custom Security Agent

The Custom Security Agent is a specialized agent configured to perform security-focused code reviews. The agent file includes:

• Name: Unique identifier (e.g., security-reviewer)
• Description: Purpose displayed in the agent picker
• Version: Semantic versioning for tracking changes
• applyTo: File patterns where the agent is most relevant (e.g., **/*.cs, **/*.js)
• Tools: Capabilities like read_file, search_files, list_directory

The screenshot below displays the contents of a security agent definition file, showing the YAML frontmatter configuration and the markdown instructions that define the agent's personality, responsibilities, and review approach:

Agent Workflow Integration

Custom agents can be integrated with GitHub Actions workflows to provide automated security checks on pull requests. This enables shift-left security practices where vulnerabilities are identified early in the development lifecycle.

The screenshot below shows a GitHub Actions workflow that leverages the security agent for automated code review and vulnerability scanning:

Security Reviewer in VS Code

Once configured, custom agents become available in VS Code through the GitHub Copilot Chat interface. To activate an agent:

1. Open Copilot Chat (Ctrl+Shift+I or click the Copilot icon)
2. Click the agent picker (icon next to the chat input)
3. Select your custom agent from the dropdown list
4. Start asking security-focused questions

Interacting with Your Agent

With your security reviewer agent active, you can ask questions like:

• "Review this authentication function for security issues"
• "Check this API endpoint for vulnerabilities"
• "Is this password hashing implementation secure?"
• "Scan this file for OWASP Top 10 vulnerabilities"

The agent responds according to its instructions, focusing on security concerns and providing actionable remediation guidance with severity levels (CRITICAL, HIGH, MEDIUM, LOW, INFO).

The screenshot below shows the VS Code Copilot Chat panel with the security reviewer agent selected, ready to analyze code for security issues:

The following screenshot demonstrates the agent providing detailed security feedback on a code file, identifying potential vulnerabilities and suggesting fixes:

Example: Scan this file for OWASP Top 10 vulnerabilities

When asked to scan for OWASP Top 10 vulnerabilities, the security reviewer agent performs a systematic review covering:

1. A01:2021 - Broken Access Control
2. A02:2021 - Cryptographic Failures
3. A03:2021 - Injection (SQL, XSS, Command)
4. A04:2021 - Insecure Design
5. A05:2021 - Security Misconfiguration
6. A06:2021 - Vulnerable and Outdated Components
7. A07:2021 - Identification and Authentication Failures
8. A08:2021 - Software and Data Integrity Failures
9. A09:2021 - Security Logging and Monitoring Failures
10. A10:2021 - Server-Side Request Forgery (SSRF)

The screenshot below shows the agent's comprehensive OWASP Top 10 scan results, with findings organized by category and accompanied by code-level fix recommendations:

Pipeline Security Agent

• "Help me harden this workflow"

Monitor Azure Portal

Note 3 windows container creating when each new node is added, therefore can only fit 3 agents in a single windows note for given SKU

---

Getting Started

To create your own custom agents:

1. Create the directory structure: mkdir -p .github/agents
2. Create your agent file: touch .github/agents/YourAgent.agent.md
3. Define configuration in YAML frontmatter (name, description, tools, applyTo)
4. Write instructions in markdown (role, responsibilities, communication style)
5. Commit and push to your repository
6. Restart VS Code to load the new agent
7. Select your agent in Copilot Chat and start interacting

For detailed guidance, see the Build Your Own GitHub Copilot Agent tutorial.