Skip to content

Commit 9f02f33

Browse files
CalinLCalinL
committed
Add DevSecOps Concepts Guide to documentation for enhanced understanding of security workflows
1 parent 5bb03e9 commit 9f02f33

File tree

2 files changed

+130
-1
lines changed

2 files changed

+130
-1
lines changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,4 +69,8 @@ Boost visibility between security and development teams by integrating GHAS with
6969
7070
> **⚡ DevSecOps is essential for modern software delivery.**
7171
72-
> **🛡️ GitHub Advanced Security (GHAS) embeds security natively into developer workflows.**
72+
> **🛡️ GitHub Advanced Security (GHAS) embeds security natively into developer workflows.**
73+
74+
## 📖 Documentation
75+
76+
For a concise overview of the shift-left security concepts, workflows, AI agents, and infrastructure patterns demonstrated in this repo, see the [DevSecOps Concepts Guide](docs/devsecops-concepts.md).

‎docs/devsecops-concepts.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: DevSecOps Concepts Guide
3+
description: A concise overview of the shift-left security concepts, workflows, and AI agents demonstrated in this repository.
4+
ms.date: 2026-03-30
5+
ms.topic: overview
6+
---
7+
8+
## What This Repo Demonstrates
9+
10+
This repository is a reference implementation for **Agentic AI-driven DevSecOps**. It combines GitHub Advanced Security (GHAS), GitHub Copilot custom agents, and Microsoft Defender for Cloud to show how security integrates into every phase of the software delivery lifecycle.
11+
12+
The core application is an ASP.NET Core Razor Pages web app (.NET 9.0), paired with intentionally vulnerable sample code across multiple languages so you can see each scanner in action.
13+
14+
## Shift-Left Security
15+
16+
Shift-left means catching vulnerabilities as early as possible, ideally before code reaches `main`. This repo implements shift-left through three layers:
17+
18+
1. **Developer environment**: Copilot agents review code and generate security plans inside VS Code, before a commit is ever pushed.
19+
2. **Pull request gates**: Automated workflows run SAST, SCA, container scanning, and IaC checks on every PR.
20+
3. **Continuous monitoring**: Scheduled scans, SBOM generation, and Defender for Cloud integration provide ongoing visibility.
21+
22+
The goal is to reduce the cost and risk of fixing vulnerabilities by finding them where they are cheapest to resolve: at the developer's keyboard.
23+
24+
## Security Workflows
25+
26+
Seventeen GitHub Actions workflows cover the full scanning spectrum. Each workflow runs on pull requests, pushes, or on a schedule, and results surface directly in the GitHub Security tab.
27+
28+
### Static Analysis (SAST)
29+
30+
| Workflow | What It Scans |
31+
|----------|---------------|
32+
| CodeQL | C#, JavaScript, Python, Go across four separate language configs |
33+
| ESLint | JavaScript for code quality and security patterns |
34+
| Microsoft Security DevOps (MSDO) | Multi-tool orchestration feeding Defender for Cloud |
35+
36+
### Software Composition Analysis (SCA)
37+
38+
| Workflow | What It Does |
39+
|----------|--------------|
40+
| Dependency Review | Blocks PRs that introduce known-vulnerable dependencies |
41+
| Anchore Syft SBOM | Generates software bill of materials on every build |
42+
| Microsoft SBOM Tool | Produces SPDX-format SBOMs for compliance |
43+
| OpenSSF Scorecard | Rates supply-chain security posture weekly |
44+
45+
### Container and Image Scanning
46+
47+
| Workflow | What It Does |
48+
|----------|--------------|
49+
| Anchore Grype | Scans container images for OS and language-level CVEs |
50+
| Trivy | Scans images and filesystem for vulnerabilities and misconfigurations |
51+
52+
### Infrastructure as Code (IaC)
53+
54+
| Workflow | What It Scans |
55+
|----------|---------------|
56+
| tfsec | Terraform files for cloud security misconfigurations |
57+
| Checkmarx KICS | Terraform, ARM, Docker, Kubernetes manifests |
58+
| Kubesec | Kubernetes manifests for workload security risks |
59+
60+
### Dynamic Analysis (DAST)
61+
62+
| Workflow | What It Does |
63+
|----------|--------------|
64+
| OWASP ZAP | Runs baseline scans against the deployed web application |
65+
66+
### CI/CD Pipeline
67+
68+
A build-and-deploy workflow provisions Azure infrastructure through Bicep, builds the application, and deploys it, with security checks gating each stage.
69+
70+
## AI Security Agents
71+
72+
Six custom GitHub Copilot agents live in the repository and run inside VS Code. They bring security expertise directly into the developer workflow without context-switching to external tools.
73+
74+
| Agent | Focus Area |
75+
|-------|------------|
76+
| Security Agent | Full-repository assessment: SAST, SCA, IaC, and CI/CD review with prioritized findings |
77+
| Security Reviewer | Code-review lens: checks changes for OWASP Top 10 issues and suggests line-level fixes |
78+
| Pipeline Security | CI/CD hardening: audits workflow permissions, action pinning, secret handling, and triggers |
79+
| IaC Security | Infrastructure guard: scans Terraform, Bicep, ARM, Kubernetes, Helm, and Dockerfiles |
80+
| Supply Chain Security | Dependency hygiene: secrets detection, SBOM verification, provenance, and repo governance |
81+
| Security Plan Creator | Architect role: generates five-phase security plans with threat models and architecture diagrams |
82+
83+
Each agent produces structured, actionable output. The Security Plan Creator, for example, walks through blueprint selection, architecture analysis, threat assessment, plan generation, and validation.
84+
85+
## Blueprints
86+
87+
Two Azure deployment blueprints (Bicep) provide real infrastructure patterns:
88+
89+
* **Containerized web app**: Azure Container Registry, App Service, and managed identity for a single-container deployment.
90+
* **Three-tier application**: App Service, Azure SQL, Key Vault, and Application Insights for a production-grade stack.
91+
92+
These blueprints pair with the Security Plan Creator agent, which uses them as inputs when generating architecture-specific security plans.
93+
94+
## Terraform Landing Zone
95+
96+
A set of Terraform modules under `terraform/azure/` provisions a full Azure landing zone: AKS, App Service, Key Vault, networking, RBAC, policies, Security Center, SQL, and storage. IaC scanning workflows validate these files on every change.
97+
98+
## Sample Vulnerable Code
99+
100+
The `samples/` directory contains intentionally insecure code across JavaScript, Python, Go, Terraform, ARM, and Dockerfiles. These files exist for demonstration purposes: they trigger findings in the scanning workflows so you can see real alerts and remediation flows.
101+
102+
> Do not deploy sample code to production. These files contain deliberate vulnerabilities for educational use.
103+
104+
## How It All Connects
105+
106+
```text
107+
Developer writes code
108+
│
109+
▼
110+
Copilot agents review in VS Code ──► early feedback before commit
111+
│
112+
▼
113+
Push / PR triggers workflows ──► SAST, SCA, IaC, container scans
114+
│
115+
▼
116+
Results appear in Security tab ──► prioritized, actionable findings
117+
│
118+
▼
119+
Copilot Autofix suggests patches ──► one-click remediation
120+
│
121+
▼
122+
Defender for Cloud aggregates ──► org-wide security posture
123+
```
124+
125+
Security is not a gate at the end of the pipeline. It is continuous feedback woven into every step, from the first keystroke to production monitoring.

0 commit comments

Comments
 (0)