# microsoft/ghazdo-resources architecture

> Architecture diagram of the GitHub repository microsoft/ghazdo-resources, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/ghazdo-resources
- Repository: https://github.com/microsoft/ghazdo-resources

## Overview

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.

Main entry points: [`src/setup`](https://github.com/microsoft/ghazdo-resources/tree/main/src/setup) (Setup Scripts), [`src/agent-setup`](https://github.com/microsoft/ghazdo-resources/tree/main/src/agent-setup) (Agent Install), [`src/3p-sarif`](https://github.com/microsoft/ghazdo-resources/tree/main/src/3p-sarif) (3P SARIF), [`src/gating`](https://github.com/microsoft/ghazdo-resources/tree/main/src/gating) (Pipeline Gates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Provisioning"]
  node_setup_bootstrap["Setup Scripts<br/>PowerShell/YAML bootstrap"]
  node_setup_enable["Enable GHAS<br/>PowerShell<br/>[Enable-GHAS.ps1]"]
  node_setup_classic["Classic CodeQL<br/>PowerShell"]
  node_setup_prs["PR CodeQL<br/>PowerShell"]
  node_setup_flow["Advanced Security<br/>Pipeline YAML"]
end

subgraph group_agents["Agent Prep"]
  node_agent_prep["Agent Install<br/>Shell/PowerShell"]
  node_agent_win["Windows<br/>PowerShell"]
  node_agent_mac["macOS<br/>Shell"]
  node_agent_ubu["Ubuntu<br/>Shell"]
end

subgraph group_extensions["ADO Extensions"]
  node_ext_autoinject["Autoinjection<br/>ADO extension"]
  node_ext_codeql_inject["CodeQL Inject<br/>ADO extension"]
  node_ext_autosetup["CodeQL Autosetup<br/>ADO task extension"]
end

subgraph group_scanners["Third-Party Scans"]
  node_sarif_suite["3P SARIF<br/>scanner examples"]
end

subgraph group_controls["Controls"]
  node_gating_core["Pipeline Gates<br/>PowerShell/YAML gate"]
  node_pr_gate["PR Verify<br/>PowerShell/JS gate"]
  node_matrix_flow["Matrix Runs<br/>YAML orchestration<br/>[ghazdo-matrix.yml]"]
end

subgraph group_reporting["Reporting"]
  node_csv_report["CSV Report<br/>PowerShell report"]
  node_committer_report["Committer Report<br/>PowerShell report"]
end

subgraph group_compliance["Compliance"]
  node_sbom_tool["SBOM Tool<br/>manifest/YAML"]
end

node_exit_32(("Exit 32<br/>demo scenario"))

node_setup_bootstrap -->|"enables"| node_setup_enable
node_setup_bootstrap -->|"configures"| node_setup_classic
node_setup_bootstrap -->|"configures"| node_setup_prs
node_setup_bootstrap -->|"drives"| node_setup_flow
node_ext_autoinject -->|"decorates"| node_setup_flow
node_ext_codeql_inject -->|"injects"| node_setup_bootstrap
node_ext_autosetup -->|"automates"| node_setup_bootstrap
node_agent_prep -->|"includes"| node_agent_win
node_agent_prep -->|"includes"| node_agent_mac
node_agent_prep -->|"includes"| node_agent_ubu
node_setup_bootstrap -->|"depends on"| node_agent_prep
node_sarif_suite -->|"feeds"| node_gating_core
node_sarif_suite -->|"feeds"| node_csv_report
node_sarif_suite -->|"feeds"| node_committer_report
node_gating_core -->|"extends"| node_pr_gate
node_matrix_flow -->|"fans out"| node_sarif_suite
node_setup_bootstrap -->|"orchestrates"| node_matrix_flow
node_sbom_tool -.->|"supports"| node_gating_core
node_exit_32 -.->|"demonstrates"| node_gating_core

click node_setup_bootstrap "https://github.com/microsoft/ghazdo-resources/tree/main/src/setup"
click node_setup_enable "https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/Enable-GHAS.ps1"
click node_setup_classic "https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/Setup_CodeQL_Classic.ps1"
click node_setup_prs "https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/Setup_CodeQL_PRs.ps1"
click node_setup_flow "https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/advanced_security.yml"
click node_agent_prep "https://github.com/microsoft/ghazdo-resources/tree/main/src/agent-setup"
click node_agent_win "https://github.com/microsoft/ghazdo-resources/blob/main/src/agent-setup/codeql-install-windows.ps1"
click node_agent_mac "https://github.com/microsoft/ghazdo-resources/blob/main/src/agent-setup/codeql-install-macos.sh"
click node_agent_ubu "https://github.com/microsoft/ghazdo-resources/blob/main/src/agent-setup/codeql-install-ubuntu.sh"
click node_ext_autoinject "https://github.com/microsoft/ghazdo-resources/tree/main/src/extensions/autoinjection"
click node_ext_codeql_inject "https://github.com/microsoft/ghazdo-resources/tree/main/src/extensions/codeql-autoinjection"
click node_ext_autosetup "https://github.com/microsoft/ghazdo-resources/tree/main/src/extensions/codeql-autosetup"
click node_sarif_suite "https://github.com/microsoft/ghazdo-resources/tree/main/src/3p-sarif"
click node_gating_core "https://github.com/microsoft/ghazdo-resources/tree/main/src/gating"
click node_pr_gate "https://github.com/microsoft/ghazdo-resources/tree/main/src/pr-gating"
click node_matrix_flow "https://github.com/microsoft/ghazdo-resources/blob/main/src/matrix/ghazdo-matrix.yml"
click node_csv_report "https://github.com/microsoft/ghazdo-resources/tree/main/src/csv-report"
click node_committer_report "https://github.com/microsoft/ghazdo-resources/tree/main/src/committer-report"
click node_sbom_tool "https://github.com/microsoft/ghazdo-resources/tree/main/src/sbom-tool"
click node_exit_32 "https://github.com/microsoft/ghazdo-resources/tree/main/src/exit-code-32"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup_bootstrap,node_setup_enable,node_setup_classic,node_setup_prs,node_setup_flow,node_sbom_tool toneBlue
class node_agent_prep,node_agent_win,node_agent_mac,node_agent_ubu toneAmber
class node_ext_autoinject,node_ext_codeql_inject,node_ext_autosetup toneMint
class node_sarif_suite toneRose
class node_gating_core,node_pr_gate,node_matrix_flow toneIndigo
class node_csv_report,node_committer_report toneTeal
class node_exit_32 toneNeutral
```

## Components

### Provisioning

Azure DevOps project and pipeline setup for GitHub Advanced Security and CodeQL.

- [Setup Scripts](https://github.com/microsoft/ghazdo-resources/tree/main/src/setup): PowerShell/YAML bootstrap · Core provisioning layer for enabling GHAS and CodeQL in Azure DevOps projects. · `src/setup`
- [Enable GHAS](https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/Enable-GHAS.ps1): PowerShell · Enables GitHub Advanced Security features in Azure DevOps. · `src/setup/Enable-GHAS.ps1`
- [Classic CodeQL](https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/Setup_CodeQL_Classic.ps1): PowerShell · Configures CodeQL for classic pipeline workflows. · `src/setup/Setup_CodeQL_Classic.ps1`
- [PR CodeQL](https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/Setup_CodeQL_PRs.ps1): PowerShell · Configures CodeQL for pull-request workflows. · `src/setup/Setup_CodeQL_PRs.ps1`
- [Advanced Security](https://github.com/microsoft/ghazdo-resources/blob/main/src/setup/advanced_security.yml): Pipeline YAML · Pipeline definition tying together setup and build automation. · `src/setup/advanced_security.yml`

### Agent Prep

Scripts that install and prepare tools on build agents.

- [Agent Install](https://github.com/microsoft/ghazdo-resources/tree/main/src/agent-setup): Shell/PowerShell · Installs CodeQL tooling on hosted or self-hosted agents. · `src/agent-setup`
- [Windows](https://github.com/microsoft/ghazdo-resources/blob/main/src/agent-setup/codeql-install-windows.ps1): PowerShell · Installs CodeQL on Windows agents. · `src/agent-setup/codeql-install-windows.ps1`
- [macOS](https://github.com/microsoft/ghazdo-resources/blob/main/src/agent-setup/codeql-install-macos.sh): Shell · Installs CodeQL on macOS agents. · `src/agent-setup/codeql-install-macos.sh`
- [Ubuntu](https://github.com/microsoft/ghazdo-resources/blob/main/src/agent-setup/codeql-install-ubuntu.sh): Shell · Installs CodeQL on Ubuntu agents. · `src/agent-setup/codeql-install-ubuntu.sh`

### ADO Extensions

Azure DevOps extension artifacts for decoration and task injection.

- [Autoinjection](https://github.com/microsoft/ghazdo-resources/tree/main/src/extensions/autoinjection): ADO extension · Decorator-based extension that injects pipeline behavior automatically. · `src/extensions/autoinjection`
- [CodeQL Inject](https://github.com/microsoft/ghazdo-resources/tree/main/src/extensions/codeql-autoinjection): ADO extension · CodeQL-specific decorator extension for automatic pipeline wiring. · `src/extensions/codeql-autoinjection`
- [CodeQL Autosetup](https://github.com/microsoft/ghazdo-resources/tree/main/src/extensions/codeql-autosetup): ADO task extension · Extension packaging a TypeScript task for automated CodeQL setup. · `src/extensions/codeql-autosetup`

### Third-Party Scans

Examples that normalize external scanner output into SARIF for ingestion.

- [3P SARIF](https://github.com/microsoft/ghazdo-resources/tree/main/src/3p-sarif): scanner examples · YAML examples for third-party scanners normalized into SARIF. · `src/3p-sarif`

### Controls

Gates and orchestration used to verify or fan out pipeline execution.

- [Pipeline Gates](https://github.com/microsoft/ghazdo-resources/tree/main/src/gating): PowerShell/YAML gate · Quality and security gates evaluated during pipeline execution. · `src/gating`
- [PR Verify](https://github.com/microsoft/ghazdo-resources/tree/main/src/pr-gating): PowerShell/JS gate · Pull-request gating and verification logic. · `src/pr-gating`
- [Matrix Runs](https://github.com/microsoft/ghazdo-resources/blob/main/src/matrix/ghazdo-matrix.yml): YAML orchestration · Matrix-based pipeline fan-out across targets or configurations. · `src/matrix/ghazdo-matrix.yml`

### Reporting

Post-processing outputs for visibility and committer-focused summaries.

- [CSV Report](https://github.com/microsoft/ghazdo-resources/tree/main/src/csv-report): PowerShell report · Generates CSV summaries from GitHub/Azure DevOps security data. · `src/csv-report`
- [Committer Report](https://github.com/microsoft/ghazdo-resources/tree/main/src/committer-report): PowerShell report · Produces committer-focused reporting and aggregation. · `src/committer-report`

### Compliance

Supply-chain packaging and SBOM generation support.

- [SBOM Tool](https://github.com/microsoft/ghazdo-resources/tree/main/src/sbom-tool): manifest/YAML · Supply-chain packaging and SBOM artifact generation support. · `src/sbom-tool`

### Other components

- [Exit 32](https://github.com/microsoft/ghazdo-resources/tree/main/src/exit-code-32): demo scenario · Scenario-specific example used to demonstrate pipeline behavior. · `src/exit-code-32`

## Connections

- Setup Scripts → Enable GHAS: enables · Bootstrap scripts turn on GHAS features.
- Setup Scripts → Classic CodeQL: configures · Bootstrap provisions classic CodeQL workflows.
- Setup Scripts → PR CodeQL: configures · Bootstrap provisions PR-based CodeQL workflows.
- Setup Scripts → Advanced Security: drives · Setup YAML orchestrates the provisioning workflow.
- Autoinjection → Advanced Security: decorates · Extension injects behavior into pipeline execution.
- CodeQL Inject → Setup Scripts: injects · CodeQL-specific extension automates pipeline wiring.
- CodeQL Autosetup → Setup Scripts: automates · Task extension helps prepare CodeQL setup steps.
- Agent Install → Windows: includes · Agent preparation has OS-specific installers.
- Agent Install → macOS: includes · Agent preparation has OS-specific installers.
- Agent Install → Ubuntu: includes · Agent preparation has OS-specific installers.
- Setup Scripts → Agent Install: depends on · Provisioning expects agents to have CodeQL installed.
- 3P SARIF → Pipeline Gates: feeds · Scanner outputs are evaluated by gates.
- 3P SARIF → CSV Report: feeds · Scan results can be summarized into CSV reports.
- 3P SARIF → Committer Report: feeds · Scan results can be aggregated for committer reporting.
- Pipeline Gates → PR Verify: extends · Pull-request gating is a specialized verification boundary.
- Matrix Runs → 3P SARIF: fans out · Matrix execution broadens scanner and target coverage.
- Setup Scripts → Matrix Runs: orchestrates · Setup pipelines can launch matrix-based runs.
- SBOM Tool → Pipeline Gates: supports · SBOM artifacts participate in compliance and verification workflows.
- Exit 32 → Pipeline Gates: demonstrates · Example scenario used to show gate behavior.