Tutorial 45: Shift-Left Governance¶

Time: 25 minutes · Level: Intermediate · Prerequisites: Tutorial 01 (Policy Engine), Tutorial 25 (Security Hardening)

Catch governance violations before they reach production. This tutorial walks through every layer of AGT's shift-left story: from pre-commit hooks that validate policy files on your laptop, through PR-time gates that enforce attestation and dependency review, to CI/CD checks that run security scans, binary analysis, and supply chain verification on every build.

Scope: commit-time, PR-time, CI/build-time, and release-time governance Tools: pre-commit hooks, GitHub Actions, GitHub CI workflows Audience: Platform engineers, DevOps teams, and security teams integrating AGT into their SDLC

What You'll Learn¶

Why Shift-Left?¶

Most AGT tutorials focus on runtime governance: policy evaluation when an agent acts, trust scoring when agents communicate, audit logging when decisions are made. Runtime governance is essential, but it is the last line of defense.

Shift-left governance moves checks earlier in the development lifecycle:

  Commit        PR           CI/Build        Release        Runtime
    │            │              │               │              │
    ▼            ▼              ▼               ▼              ▼

**Why it matters:**

- A social engineering contributor caught at PR open never gets code reviewed
- A malformed policy file caught at commit time costs zero CI minutes
- A secret caught in PR review never reaches the default branch
- A dependency confusion attack blocked in CI never reaches production
- An unsigned artifact blocked at release time never reaches users

---

## Commit-Time: Pre-Commit Hooks

AGT ships three pre-commit hooks in `.pre-commit-hooks.yaml` and a
[rollout template](../operations/pre-commit-hook-template.md) with additional
quality gates.

### §1.1 Built-In Hooks

| Hook ID | What It Checks | Triggers On |
|---------|---------------|-------------|
| `validate-policy` | YAML/JSON policy file schema and structure | `*polic*.yaml`, `*polic*.yml`, `*polic*.json` |
| `validate-plugin-manifest` | Plugin manifest required fields and schema | `plugin.json`, `plugin.yaml` |
| `evaluate-plugin-policy` | Plugin manifests against a governance policy | `plugin.json`, `plugin.yaml` |

### §1.2 Setup

Add AGT as a pre-commit hook source in your `.pre-commit-config.yaml`:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/microsoft/agent-governance-toolkit
    rev: main  # pin to a release tag in production
    hooks:
      - id: validate-policy
      - id: validate-plugin-manifest
      - id: evaluate-plugin-policy
        args: ['--policy', 'policies/marketplace-policy.yaml']

Install and run:

pip install pre-commit
pre-commit install
pre-commit run --all-files   # validate existing files

§1.3 Extended Quality Gates¶

The pre-commit hook rollout template adds governance-specific quality gates beyond schema validation:

§1.4 Phased Rollout¶

For teams adopting AGT incrementally:

1. Week 1: Install with --permissive mode, hooks warn but don't block
2. Week 2: Switch to --strict for policy validation only
3. Week 3: Enable all hooks as blocking
4. Week 4: Graduate to full blocking per the graduation checklist

PR-Time: Contributor Reputation¶

The leftmost check in AGT's shift-left pipeline. Before reviewing code, before running CI, the contributor reputation action screens the author's GitHub profile for signals of coordinated inauthentic behavior.

What It Detects¶

Add It to Your Repo¶

AGT ships a reusable composite action. Add this workflow to any repository:

# .github/workflows/contributor-check.yml
name: Contributor Reputation Check

on:
  pull_request_target:        # Use pull_request_target, not pull_request
    types: [opened]
  issues:
    types: [opened]

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  check:
    runs-on: ubuntu-latest
    if: github.actor != 'dependabot[bot]'
    steps:
      - name: Checkout AGT action
        uses: actions/checkout@v4
        with:
          repository: microsoft/agent-governance-toolkit
          sparse-checkout: |
            scripts
            .github/actions/contributor-check
          path: agt

      - name: Run contributor check
        uses: ./agt/.github/actions/contributor-check
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          checks: profile,credential    # Add 'cluster' for deep analysis
          risk-threshold: MEDIUM        # MEDIUM or HIGH

How It Works¶

1. On every PR or issue open, the action runs two checks (profile + credential audit) using only the GitHub REST API and Python stdlib. No dependencies to install.

2. Risk is computed as the max across all checks:

3. LOW: No action taken (silent pass)
4. MEDIUM: Posts a collapsible comment, adds needs-review:MEDIUM label

5. HIGH: Posts a detailed comment, adds needs-review:HIGH label

6. Comments are idempotent: re-runs update the same comment instead of creating duplicates. Old risk labels are removed before applying the current one.

7. Cluster detection (opt-in) maps coordination networks from a seed account via shared forks, co-comments, and synchronized filing. It is API-heavy and recommended only for manual dispatch investigations.

Important: Use pull_request_target (not pull_request) so the action has write permissions to comment and label on fork PRs. Do not run untrusted PR code before this action in the same workflow.

PR-Time Gates¶

When code reaches a pull request, three independent workflows enforce governance before merge.

§2.1 Governance Attestation¶

The Governance Attestation action (action/governance-attestation/) validates that PR authors have completed a 7-section attestation checklist covering security, privacy, CELA, responsible AI, accessibility, release readiness, and org-specific launch gates.

# .github/workflows/pr-governance.yml
name: PR Governance
on:
  pull_request:
    types: [opened, edited, synchronize]

jobs:
  attestation:
    runs-on: ubuntu-latest
    steps:
      - uses: microsoft/agent-governance-toolkit/action/governance-attestation@main
        with:
          required-sections: |
            1) Security review
            2) Privacy review
            3) CELA review
            4) Responsible AI review
            5) Accessibility review
            6) Release Readiness / Safe Deployment
            7) Org-specific Launch Gates

The action outputs: - status: pass or fail - errors: list of missing sections - sections-found: JSON mapping of sections to checkbox counts

§2.2 Dependency Review¶

AGT's dependency review workflow blocks PRs that introduce dependencies with known CVEs or disallowed licences:

# From .github/workflows/dependency-review.yml
- uses: actions/dependency-review-action@v4
  with:
    fail-on-severity: moderate
    comment-summary-in-pr: always
    allow-licenses: >
      MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC,
      PSF-2.0, Python-2.0, 0BSD, Unlicense, CC0-1.0,
      CC-BY-4.0, Zlib, BSL-1.0, MPL-2.0

This runs on every PR that touches dependency manifests and flags: - Dependencies with moderate+ CVEs - Dependencies with licences not on the allow list

§2.3 Secret Scanning¶

The secret scanning workflow (secret-scanning.yml) runs on every PR to main and weekly on schedule. It combines:

1. Gitleaks for pattern-based secret detection across the full git history
2. High-entropy string scanning for API keys, GitHub tokens, AWS keys, and Slack tokens using regex patterns

§2.4 Supply Chain Checks¶

The supply chain check workflow (supply-chain-check.yml) runs when dependency manifests change and enforces:

• Exact version pinning: no ^ or ~ version ranges in package.json
• Lockfile presence: every package with dependencies must have a lockfile

§2.5 Quality Gates¶

The quality gates workflow (quality-gates.yml) runs on every PR and blocks merge if:

These mirror the pre-commit hooks from Section 1.3, providing defense in depth: pre-commit catches issues at the developer's machine, quality gates catch anything that bypasses hooks.

CI/Build-Time Checks¶

Once a PR passes the gate workflows, the main CI pipeline and specialized workflows perform deeper analysis.

§3.1 Governance Verify Action¶

The Agent Governance Verify action (action/action.yml) is the primary CI-time governance check. It runs the compliance CLI against your repository:

# .github/workflows/governance-ci.yml
name: Governance CI
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/agent-governance-toolkit/action@main
        with:
          command: all              # governance-verify + marketplace-verify + policy-evaluate
          policy-path: policies/    # path to policy files
          manifest-path: plugin.json
          output-format: json
          fail-on-warning: 'true'

The command input supports four modes:

§3.2 Security Scan Action¶

The Security Scan action (action/security-scan/) scans directories for secrets, CVEs, and dangerous code patterns:

- uses: microsoft/agent-governance-toolkit/action/security-scan@main
  with:
    paths: 'plugins/ scripts/'
    min-severity: high           # block on critical or high findings
    exemptions-file: .security-exemptions.json

Outputs include findings-count, blocking-count, and full findings in JSON format, making it easy to integrate with dashboards or notification systems.

§3.3 Policy Validation Workflow¶

The policy validation workflow (policy-validation.yml) triggers when any YAML file or the policy engine source changes. It:

1. Discovers all policy files matching *policy* naming
2. Validates each file using agent_os.policies.cli validate
3. Runs policy CLI unit tests to verify evaluation behavior

This ensures that policy file changes don't break the policy engine.

§3.4 CodeQL and Static Analysis¶

AGT uses CodeQL for semantic static analysis of Python and TypeScript code. The CodeQL workflow (codeql.yml) runs on pushes and PRs, uploading SARIF results to GitHub's security tab.

§3.5 Dependency Confusion Scan¶

A dedicated CI job runs scripts/check_dependency_confusion.py --strict on every build. This checks that:

• Internal package names don't collide with public PyPI/npm packages
• Notebook pip install commands only reference registered packages

§3.6 Workflow Security Audit¶

When GitHub Actions workflow files change, a workflow security job scans for:

• Expression injection vulnerabilities (${{ github.event.* }} in run:)
• Overly permissive permissions
• Unpinned action references

§3.7 .NET Binary Analysis (BinSkim)¶

For the .NET SDK, the CI pipeline runs Microsoft BinSkim binary analysis on compiled assemblies:

- name: BinSkim binary security analysis
  run: |
    dotnet tool install --global Microsoft.CodeAnalysis.BinSkim --version 4.*
    BinSkim analyze "src/AgentGovernance/bin/Release/net8.0/*.dll" \
      --output binskim-results.sarif --verbose

Results are uploaded as SARIF to GitHub's code scanning dashboard.

Language-Specific Build-Time Enforcement¶

Each AGT SDK uses its language's native tooling to enforce governance standards at compile time. These are implemented today in the repository.

§4.1 .NET (Microsoft.AgentGovernance)¶

The .NET SDK enforces the strictest compile-time checks via MSBuild properties in Directory.Build.props and Directory.Build.targets:

These are enforced automatically for any project in the agent-governance-dotnet/ directory tree.

§4.2 TypeScript (@microsoft/agentmesh-sdk)¶

The TypeScript SDK uses strict compiler settings in tsconfig.json:

§4.3 Python (agent-governance-python)¶

Python packages use typed package markers and static analysis tooling:

§4.4 Recommended Extensions¶

The following patterns are not yet enforced in AGT's own CI but are recommended for teams consuming AGT:

Release-Time Gates¶

Before artifacts reach users, the release pipeline adds a final layer of verification. These are covered in depth by Tutorial 26, but here is how they fit into the shift-left lifecycle:

Reference Architecture¶

Here is how all the shift-left governance layers compose into a single pipeline:

Developer Machine          GitHub PR              CI Pipeline              Release
─────────────────          ─────────              ───────────              ───────
pre-commit hooks           Governance             Main CI                  SBOM
├─ validate-policy         attestation            ├─ lint (ruff, ESLint)   ├─ SPDX
├─ validate-plugin         ├─ 7-section           ├─ build (.NET, TS,      ├─ CycloneDX
│  -manifest               │  checklist           │  Rust, Go, Python)     │
├─ evaluate-plugin         │                      ├─ test (all SDKs)       Signing
│  -policy                 Dependency review      ├─ governance-verify     ├─ Sigstore
├─ agt-validate            ├─ CVE check           ├─ policy-validation     ├─ ESRP
├─ agt-doctor (pre-push)   ├─ licence check       ├─ CodeQL / SAST        │
├─ detect-secrets          │                      ├─ BinSkim (.NET)       Provenance
├─ no-stubs                Secret scanning        ├─ dependency-scan       ├─ SLSA
├─ no-custom-crypto        ├─ Gitleaks            ├─ workflow-security     ├─ SBOM
                           ├─ entropy scan        │                        │  attestation
                           │                      ├─ ci-complete gate      │
                           Supply chain check     │  (required status      Scorecard
                           ├─ version pinning     │   check)               └─ OpenSSF
                           ├─ lockfile presence   │
                           │                      Security scan action
                           Quality gates          ├─ secrets
                           ├─ no stubs            ├─ CVEs
                           ├─ no crypto           ├─ dangerous patterns
                           ├─ security audit
                           ├─ dep audit trail

Required Status Checks¶

The CI pipeline uses a ci-complete gate job as a single required status check. This job:

1. Runs if: always() regardless of skip conditions
2. Depends on all other CI jobs
3. Checks that no jobs failed (skipped is acceptable)
4. Reports a single pass/fail to branch protection

This pattern lets individual jobs skip based on path filters while still enforcing that nothing that ran has failed.

Cross-Reference¶

Source Files¶

Next Steps¶

• Set up pre-commit hooks in your repository using the rollout template
• Add the Governance Verify action to your CI pipeline for automated compliance checks
• Enable dependency review to catch CVE and licence issues at PR time
• Read Tutorial 25 (Security Hardening) for deeper coverage of CodeQL, fuzzing, and Scorecard
• Read Tutorial 26 (SBOM & Signing) for release-time artifact signing and SBOM attestation