microsoft/ghazdo-resources

1. This repo is a collection of Azure DevOps resources, scripts, and extension artifacts for demonstrating and accelerating adoption of GitHub Advanced Security on Azure DevOps. It is not a single application; it is a toolkit that wires security scanning, pipeline setup, gating, reporting, and agent preparation together.

2. The main architectural boundary is Azure DevOps itself. Most scripts either:

- configure Azure DevOps pipelines and security features,

- run in build/PR pipelines as gates or helpers,

- or post-process security outputs into reports.

The repo is therefore organized around pipeline lifecycle, not around a runtime service.

3. The src/setup area is the core provisioning layer. It contains PowerShell scripts and pipeline definitions used to enable GHAS features, set up CodeQL for classic and PR-based workflows, and drive builds. Files like Enable-GHAS.ps1, Setup_CodeQL_Classic.ps1, Setup_CodeQL_PRs.ps1, and advanced_security.yml indicate this is the main “bootstrap” subsystem for turning on security scanning in ADO projects.

4. The src/agent-setup scripts are a separate infrastructure layer for build agents. They install CodeQL on Windows, macOS, and Ubuntu agents so downstream pipeline jobs can run analysis locally on the agent rather than relying on the repository to carry the tool binaries.

5. The src/extensions tree is an Azure DevOps extension subsystem. It includes:

- decorator-based autoinjection extensions,

- a CodeQL autoinjection extension,

- and a codeql-autosetup extension with a TypeScript task packaged as an ADO extension.

These pieces sit at the Azure DevOps platform boundary and automate pipeline decoration or task insertion rather than running as standalone tools.

6. The src/3p-sarif directory handles third-party scanner integration. Its .ado subfolders contain YAML examples for tools such as Bandit, Brakeman, OpenGrep, PMD, Psalm, and Security Code Scan. The architectural role here is to normalize external scanner output into SARIF so Azure DevOps/GHAS can ingest and display results consistently.

7. Reporting is split into dedicated post-processing utilities. src/csv-report generates CSV reports from GH/ADO security data, and src/committer-report produces committer-focused reporting via PowerShell. These are downstream consumers of pipeline or scan results, meant for aggregation and visibility rather than enforcement.

8. Gating and verification are handled by src/gating and src/pr-gating. These scripts implement quality/security gates around pipeline execution, especially for pull requests. CIGate.ps1, CIVerify.yml, and related documentation indicate a boundary where scan findings or build state are evaluated before merge or continuation.

9. src/matrix contains YAML for matrix-driven pipeline execution, likely used to fan out tests or scans across multiple targets or configurations. This is an orchestration aid rather than a functional subsystem, but it matters because it determines how broad the security/demo coverage is across environments.

10. src/sbom-tool is a packaging/compliance subsystem for generating or demonstrating software bill of materials artifacts. The presence of a manifest and pipeline YAML suggests it fits into the broader supply-chain security story alongside scanning and reporting.

11. The repo also includes specialized demo/support scripts such as src/exit-code-32 and the various setup/readme files under subsystem folders. These look like scenario-specific examples used to demonstrate particular pipeline or security behaviors rather than production components.

12. In terms of data flow, the typical path is: Azure DevOps pipeline or extension triggers setup scripts -> agents get CodeQL or other scanners installed -> scans run and emit findings/SARIF -> gating scripts evaluate results -> reporting scripts summarize outcomes into CSV or committer reports. That flow is the key architecture to capture in a diagram.

13. Tooling is mostly PowerShell and YAML, with a small TypeScript-based Azure DevOps task and some JavaScript for PR gating. The repo is therefore operational/integration heavy: it is centered on pipeline configuration, extension packaging, and agent-side automation, not on a long-running backend service or UI.