microsoft / microsoft/agent-governance-toolkit

[Feature]: Terraform/OpenTofu modules for governed agent infrastructure (AWS + Azure)

Open
#2,770 6 comments 0 reactions 1 assignee Claimed by @prashansapkota View on GitHub
accepted help wanted integration
Dominant language
Python
Stars
6.3k
Forks
1.1k
Avg merge
5d 11h
Merged PRs (30d)
142

Description

## Package

New integration / infra

## Problem Statement

AGT has runtime deployment targets (`DockerDeployer`, `KubernetesDeployer`) in `agent-runtime/deploy.py` and a GitHub Actions governance gate, but there is no Infrastructure-as-Code for the underlying cloud resources those deployers depend on.

In practice this creates a gap for teams running governed agents in production:

1. Every team has to hand-roll the IAM roles, VPCs, KMS keys, audit log buckets, and secrets storage that AGT's governance pipeline requires, with no guarantee those resources are configured correctly or consistently.

2. Governance receipts signed with Ed25519 need a secure key store (KMS on AWS, Key Vault on Azure) and a tamper-evident audit log destination (S3 / Blob Storage), but AGT provides no reusable IaC for either.

3. The `AGT_*` environment variables (`AGT_TRUST_LEVEL`, `AGT_MAX_TOOL_CALLS`, `AGT_RATE_LIMIT_RPM`, `AGT_AUDIT_ENABLED`, `AGT_KILL_SWITCH`, `AGT_RETENTION_DAYS`) that `DockerDeployer` and `KubernetesDeployer` inject into containers have no authoritative source of truth in infrastructure, teams store them as ad-hoc environment variables rather than managed config.

4. Regulated organizations (financial services, healthcare, government) require all infrastructure to be version-controlled, reviewed, and reproducible before they can adopt AGT.

## Proposed Solution

Add `infra/terraform/` with two reusable modules that provision the complete governed-agent infrastructure stack, with all governance config values directly mirroring `GovernanceConfig` in `agent-runtime/deploy.py`.

### `modules/governed-agent-aws/`

- VPC with private subnets (agents) + public subnets (NAT gateways) + routing
- Egress-only security group for agent workloads (HTTPS only, no inbound)
- KMS key (auto-rotating) for Ed25519 receipt signing and audit log encryption
- S3 bucket with versioning, KMS encryption, lifecycle tiers (Standard → IA at 90d → Glacier at 180d → expire at `retention_days`), public access blocked, TLS enforced
- IAM role + instance profile with least-privilege permissions (SSM read, S3 write, Secrets Manager read, KMS sign/verify, CloudWatch write)
- Secrets Manager secret for the Ed25519 signing key PEM
- SSM parameters for all `AGT_*` governance config values agents read at runtime
- CloudWatch Log Group for structured governance events

### `modules/governed-agent-azure/`

- Resource Group, VNet, subnet with service endpoints, NSG (all inbound denied)
- User-Assigned Managed Identity for passwordless agent auth
- Key Vault (Premium, purge-protected in prod, RBAC-based) for Ed25519 signing key
- Storage Account + Blob container with lifecycle management, GRS in prod, TLS-only
- App Configuration store for all `AGT_*` governance config values (mirrors SSM on AWS)
- Log Analytics Workspace for governance event ingestion and retention

### Governance config variables

All variables map directly to `GovernanceConfig` fields and `AGT_*` env vars:

| Terraform variable | Default | `AGT_*` env var |
|---|---|---|
| `trust_level` | `standard` | `AGT_TRUST_LEVEL` |
| `max_tool_calls` | `100` | `AGT_MAX_TOOL_CALLS` |
| `rate_limit_rpm` | `60` | `AGT_RATE_LIMIT_RPM` |
| `audit_enabled` | `true` | `AGT_AUDIT_ENABLED` |
| `kill_switch_enabled` | `true` | `AGT_KILL_SWITCH` |
| `retention_days` | `180` | `AGT_RETENTION_DAYS` |

`trust_level` validation accepts `unclassified`, `basic`, `standard`, `elevated`, `critical` — matching the `GovernanceTier` enum in `github_enterprise.py`.

### Example usage (AWS)

```hcl
module "governed_agent" {
source = "microsoft/agent-governance-toolkit//infra/terraform/modules/governed-agent-aws"

project = "my-agent"
environment = "prod"

trust_level = "elevated"
max_tool_calls = 50
rate_limit_rpm = 30
retention_days = 365
kill_switch_enabled = true
}
```

### Known limitations in this initial implementation

- `AGT_POLICY_PATH` (the Cedar/YAML policy file path) is not provisioned by Terraform — it is a runtime container mount. A follow-up could add an S3/Blob prefix for policy file storage and wire its path into SSM/App Configuration.
- No ECS task definition or AKS Helm chart — the module provisions the supporting infrastructure; the compute layer is left to the caller.

## Alternatives Considered

Teams can manually create these resources via the AWS/Azure console or bespoke scripts, but this produces inconsistent configurations across teams and provides no audit trail of infrastructure changes.

## Priority

Important

## Contribution

- I would love to submit a PR for this feature

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.