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:

Threat Assessment Phase

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:

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:

Security Reviewer Agent

The Security Reviewer Agent is a specialized custom agent configured to perform security-focused code reviews. This agent scans code for vulnerabilities, identifies insecure patterns, and provides remediation guidance with severity ratings.

Agent Configuration

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:

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:

Using Custom Agents 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

Sample Prompts for Security Reviewer

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: OWASP Top 10 Vulnerability Scan

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

The Pipeline Security Agent is a specialized custom agent designed to analyze and harden CI/CD pipelines, GitHub Actions workflows, and deployment configurations. This agent focuses on identifying security misconfigurations, secrets exposure risks, supply chain vulnerabilities, and privilege escalation paths within your automation pipelines.

Why Pipeline Security Matters

CI/CD pipelines are prime targets for attackers because they:

• Often have elevated permissions to deploy code and access secrets
• May contain hardcoded credentials or insecure secret handling
• Can be exploited for supply chain attacks through compromised dependencies
• Execute arbitrary code that could be manipulated through pull request poisoning

The Pipeline Security Agent helps you identify and remediate these risks before they become production vulnerabilities.

Agent Capabilities

The Pipeline Security Agent can analyze:

• GitHub Actions workflows (.github/workflows/*.yml)
• Azure DevOps pipelines (azure-pipelines.yml)
• Jenkins pipelines (Jenkinsfile)
• GitLab CI configurations (.gitlab-ci.yml)
• Docker build configurations (Dockerfile, docker-compose.yml)
• Terraform and Bicep deployment scripts

Sample Prompts for Pipeline Security Agent

Workflow Hardening:

• "Help me harden this workflow"
• "Review this GitHub Actions workflow for security issues"
• "What permissions should I remove from this workflow?"
• "Is this workflow vulnerable to script injection attacks?"

Secrets Management:

• "Check this pipeline for secrets exposure risks"
• "Are my secrets being handled securely in this workflow?"
• "Review how environment variables are used in this pipeline"
• "Is it safe to use this secret in a pull_request trigger?"

Supply Chain Security:

• "Check this workflow for supply chain vulnerabilities"
• "Are my action dependencies pinned to specific versions?"
• "Should I be using commit SHAs instead of tags for actions?"
• "Review my dependency update workflow for security"

Permissions & Access Control:

• "What is the minimum permission set needed for this workflow?"
• "Is contents: write permission too broad for this job?"
• "Review the GITHUB_TOKEN permissions in this workflow"
• "Should this workflow use a PAT or GITHUB_TOKEN?"

Pull Request Security:

• "Is this workflow safe to run on pull_request_target?"
• "Check for pwn request vulnerabilities in this workflow"
• "How can I safely checkout PR code in this workflow?"
• "Review this PR workflow for code injection risks"

Container & Image Security:

• "Review this Dockerfile for security best practices"
• "Is my container image build secure?"
• "Check for privilege escalation risks in this container setup"
• "Should I be running as root in this container?"

Example: Hardening a GitHub Actions Workflow

When asked to "help me harden this workflow," the Pipeline Security Agent performs a comprehensive review including:

1. Permission Analysis - Identifies overly permissive GITHUB_TOKEN scopes
2. Action Version Pinning - Checks if actions are pinned to commit SHAs
3. Secret Handling - Reviews how secrets are accessed and exposed
4. Trigger Security - Evaluates risks from pull_request_target and fork workflows
5. Script Injection - Identifies ${{ }} expressions vulnerable to injection
6. Environment Protection - Checks for proper environment and approval gates

The screenshot below demonstrates the Pipeline Security Agent analyzing a workflow and providing hardening recommendations:

Common Security Issues Detected

Issue	Severity	Example
Unpinned action versions	HIGH	uses: actions/checkout@v4 instead of SHA
Overly permissive permissions	MEDIUM	permissions: write-all
Script injection via expressions	CRITICAL	run: echo "${{ github.event.issue.title }}"
Secrets in pull_request trigger	HIGH	Accessing secrets on forks
Missing environment protection	MEDIUM	Direct deployment without approvals
Hardcoded credentials	CRITICAL	API keys in workflow files

---

IaC Security Agent

we used prompt:

"secure the main.bicep file"

yieleded PR https://github.com/devopsabcs-engineering/gh-advsec-devsecops/pull/27

did changes like:

secure the main.bicep file

Getting Started

To create your own custom agents, follow these steps:

Prerequisites

• VS Code with the GitHub Copilot extension installed
• GitHub Copilot subscription (Individual, Business, or Enterprise)
• A GitHub repository where you have write access
• Custom agents feature enabled for your organization (see Prepare for Custom Agents)

Step-by-Step Setup

1. Create the directory structure

   mkdir -p .github/agents

2. Create your agent file

   touch .github/agents/security-reviewer.agent.md

3. Define configuration in YAML frontmatter

   ---
   name: security-reviewer
   description: Reviews code for security vulnerabilities and provides remediation guidance
   version: 1.0.0
   applyTo:
     - "**/*.cs"
     - "**/*.js"
     - "**/*.py"
   tools:
     - read_file
     - search_files
     - list_directory
   ---

4. Write instructions in markdown

   ## Role
   You are a security-focused code reviewer specializing in identifying vulnerabilities.
   
   ## Responsibilities
   - Scan code for OWASP Top 10 vulnerabilities
   - Identify insecure coding patterns
   - Provide actionable remediation with code examples
   
   ## Response Format
   Always include severity (CRITICAL/HIGH/MEDIUM/LOW) and specific fix recommendations.

5. Commit and push to your repository

   git add .github/agents/
   git commit -m "Add security reviewer custom agent"
   git push

6. Restart VS Code to load the new agent

7. Select your agent in Copilot Chat and start interacting

Troubleshooting

Issue	Solution
Agent not appearing in picker	Restart VS Code; ensure file is in .github/agents/
Agent ignoring instructions	Check YAML frontmatter syntax; validate markdown formatting
Tools not working	Verify tools are listed in frontmatter; check organization permissions
Slow responses	Reduce instruction complexity; limit applyTo patterns

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

---

Additional Resources

Resource	Description
GitHub Advanced Security Documentation	Official docs for code scanning, secret scanning, and Dependabot
OWASP Top 10	Industry-standard list of critical web application security risks
CIS Benchmarks	Security configuration best practices for various platforms
STRIDE Threat Modeling	Microsoft's threat categorization methodology used by Security Plan Creator