Version Guard

Version Guard is an open-source cloud infrastructure version monitoring system that continuously scans cloud resources (databases, caches, compute) to detect version drift and compliance issues.

🎯 Purpose

Version Guard helps organizations maintain infrastructure security and compliance by:

Proactive Detection: Identifying resources running deprecated or end-of-life (EOL) versions before they become security risks
Multi-Cloud Support: Scanning resources across AWS, GCP, and Azure through unified inventory sources
Cost Optimization: Preventing expensive extended support charges (6x base price for AWS Extended Support)
Compliance Tracking: Providing Red/Yellow/Green classification for compliance dashboards
Automation: Continuously monitoring infrastructure without manual intervention

🏗️ Architecture

Version Guard implements a two-stage detection pipeline:

┌────────────────────────────────────────────────────────────┐
│  STAGE 1: DETECT (Temporal Workflow)                       │
│                                                            │
│   Fan-Out: Parallel Detection per Resource Type            │
│   ┌───────┐  ┌─────────┐  ┌───────┐                        │
│   │Aurora │  │   EKS   │  │ More  │  ...                   │
│   └───┬───┘  └────┬────┘  └───┬───┘                        │
│       └───────────┼───────────┘                            │
│                   ▼                                        │
│   Inventory (Wiz) + EOL Data + Classify                    │
│                   │                                        │
└───────────────────┼────────────────────────────────────────┘
                    │
┌───────────────────┼────────────────────────────────────────┐
│  STAGE 2: STORE                                            │
│                   ▼                                        │
│   Create Versioned JSON Snapshot                           │
│                   │                                        │
│   s3://bucket/snapshots/YYYY/MM/DD/{snapshot-id}.json      │
│   s3://bucket/snapshots/latest.json                        │
│                                                            │
└────────────────────────────────────────────────────────────┘
                    │
                    ▼
          📤 YOUR CUSTOM EMITTERS
        (See "Extending Version Guard")

Key Components:

Inventory Sources: Wiz saved reports for resource discovery (multi-cloud)
EOL Data: endoflife.date API — no cloud provider credentials needed
Classification: Red (EOL/deprecated), Yellow (extended support/approaching EOL), Green (current)
S3 Snapshots: Versioned JSON storage for audit trail and downstream consumption
gRPC API: Query interface for compliance dashboards

✨ Features

✅ Multi-Cloud Inventory: Wiz integration for AWS, GCP, Azure resource discovery
✅ Open EOL Data: All EOL data from endoflife.date — no cloud provider credentials needed
✅ Parallel Detection: Temporal-based workflows for scalable scanning
✅ Versioned Snapshots: S3 storage with full audit history
✅ Local Development: Full docker-compose setup with MinIO (S3) and Temporal
✅ Extensible Architecture: Plugin your own emitters for issue tracking, dashboards, notifications

📦 Supported Resources

Resource	Inventory	EOL Source	Code	Status
EKS (Kubernetes)	Wiz	amazon-eks	✅ Implemented	✅ Working
ElastiCache (Redis/Valkey)	Wiz	amazon-elasticache-redis, valkey	✅ Implemented	✅ Working
Aurora PostgreSQL	Wiz	amazon-aurora-postgresql	✅ Implemented	🔜 Needs Wiz report with PostgreSQL data
Aurora MySQL	Wiz	amazon-aurora-mysql	✅ Implemented	🔜 EOL data pending endoflife.date#9534
RDS MySQL	—	amazon-rds-mysql	❌ Needs Wiz report	📋 Planned
RDS PostgreSQL	—	amazon-rds-postgresql	❌ Needs Wiz report	📋 Planned
OpenSearch	—	amazon-opensearch	❌ Needs Wiz report	📋 Planned
Lambda	—	aws-lambda	❌ Needs Wiz report	📋 Planned

Adding a new resource type requires:

A Wiz saved report + inventory source (~100 lines)
One line in ProductMapping to map the engine name to endoflife.date

🚀 Quick Start

Prerequisites

Go 1.24+
Docker (for docker-compose local setup)
Wiz API access (optional — falls back to mock data)

Installation

git clone https://github.com/block/Version-Guard.git
cd Version-Guard

# Build binaries
make build-all

# Verify build
./bin/version-guard --help
./bin/version-guard-cli --help

Run Locally (docker-compose)

The easiest way to run Version Guard locally. This starts Temporal, MinIO (S3-compatible storage), and the Version Guard server in one command:

# With mock inventory (no Wiz credentials needed)
docker compose up --build

# With real Wiz inventory
export WIZ_CLIENT_ID_SECRET="your-client-id"
export WIZ_CLIENT_SECRET_SECRET="your-client-secret"
export WIZ_EKS_REPORT_ID="your-report-id"
export WIZ_AURORA_REPORT_ID="your-report-id"
export WIZ_ELASTICACHE_REPORT_ID="your-report-id"
docker compose up --build

Services started:

Service	Purpose	Port
`temporal`	Workflow orchestration	`7233` (gRPC), `8233` (Web UI)
`minio`	S3-compatible snapshot storage	`9000` (API), `9001` (Console)
`version-guard`	The server	`8080` (gRPC)

Once running, open the Temporal Web UI at http://localhost:8233 to trigger and monitor workflows.

Run Locally (manual)

If you prefer running components individually:

Start local Temporal server:

make temporal
# Opens Web UI at http://localhost:8233

Run Version Guard server (in a separate terminal):

# With mock inventory data (no Wiz credentials needed)
make dev

# Or with real Wiz inventory (requires credentials)
export WIZ_CLIENT_ID_SECRET="your-client-id"
export WIZ_CLIENT_SECRET_SECRET="your-client-secret"
export WIZ_AURORA_REPORT_ID="your-report-id"
make dev

Trigger a Scan

# Via Temporal CLI (from inside the temporal container if using docker-compose)
docker compose exec temporal temporal workflow start \
  --task-queue version-guard-detection \
  --type OrchestratorWorkflow \
  --input '{}' \
  --address localhost:7233 \
  --namespace version-guard-dev

# Or via the Temporal Web UI at http://localhost:8233 → Start Workflow

Query Findings

# Using gRPC
grpcurl -plaintext localhost:8080 list
grpcurl -plaintext localhost:8080 \
  block.versionguard.VersionGuard/GetFleetSummary

# Using the CLI
./bin/version-guard-cli service list
./bin/version-guard-cli finding list

Run Tests

# Run all tests
make test

# Run specific package tests
go test ./pkg/detector/aurora -v
go test ./pkg/policy -v

# Run with coverage
make test-coverage

🔧 Configuration

Version Guard is configured via environment variables or CLI flags:

Variable	Description	Default
`TEMPORAL_ENDPOINT`	Temporal server address	`localhost:7233`
`TEMPORAL_NAMESPACE`	Temporal namespace	`version-guard-dev`
`GRPC_PORT`	gRPC service port	`8080`
`S3_BUCKET`	S3 bucket for snapshots	`version-guard-snapshots`
`AWS_REGION`	AWS region (for S3 snapshots)	`us-west-2`
`WIZ_CLIENT_ID_SECRET`	Wiz client ID (optional)	-
`WIZ_CLIENT_SECRET_SECRET`	Wiz client secret (optional)	-
`TAG_APP_KEYS`	Comma-separated AWS tag keys for app/service	`app,application,service`
`TAG_ENV_KEYS`	Comma-separated AWS tag keys for environment	`environment,env`
`TAG_BRAND_KEYS`	Comma-separated AWS tag keys for brand/business unit	`brand`
`--verbose` / `-v`	Enable debug-level logging	`false`

Customizing AWS Tag Keys:

Version Guard extracts metadata (service name, environment, brand) from AWS resource tags. By default, it looks for tags like app, application, or service. You can customize these to match your organization's tagging conventions:

# Example: Your organization uses "cost-center" instead of "brand"
export TAG_BRAND_KEYS="cost-center,department,business-unit"

# Example: Your organization uses "team" for service attribution
export TAG_APP_KEYS="team,squad,application"

The tag keys are tried in order — the first matching tag wins.

Logging:

Version Guard uses structured JSON logging via Go's log/slog package for production observability:

# Run with debug-level logging
./bin/version-guard --verbose

# Production mode (info-level logging only)
./bin/version-guard

Logs are output in JSON format for easy parsing by log aggregation tools (Datadog, Splunk, CloudWatch Insights):

{
  "time": "2024-01-15T10:30:45Z",
  "level": "WARN",
  "msg": "failed to detect drift for resource",
  "resource_id": "arn:aws:rds:us-west-2:123456789012:cluster:my-db",
  "error": "version not found in EOL database"
}

Benefits:

Machine-readable structured data with typed fields
Context-aware logging with trace IDs
Queryable logs (e.g., filter by resource_id or error)
Integrates seamlessly with observability platforms

See ./bin/version-guard --help for all options.

🎨 Classification Policy

Status	Criteria	Typical Action
🔴 RED	Past EOL, deprecated, extended support expired	Urgent upgrade required
🟡 YELLOW	In extended support (costly), approaching EOL (< 90 days)	Plan upgrade soon
🟢 GREEN	In standard support, current version	Compliant
⚪ UNKNOWN	Version not found in EOL database	Investigate

🔌 Extending Version Guard

Version Guard provides interfaces for custom emitters so you can integrate with your own systems:

1. Implementing Custom Emitters

See pkg/emitters/emitters.go for interface definitions:

type IssueTrackerEmitter interface {
    Emit(ctx context.Context, snapshotID string, findings []*types.Finding) (*IssueTrackerResult, error)
}

type DashboardEmitter interface {
    Emit(ctx context.Context, snapshotID string, summary *types.SnapshotSummary) (*DashboardResult, error)
}

Example implementations:

pkg/emitters/examples/logging_emitter.go - Logs findings to stdout (included)
Your custom emitter - Send findings to Jira, ServiceNow, Slack, PagerDuty, etc.

2. Consuming S3 Snapshots

Snapshots are stored as JSON in S3:

s3://your-bucket/snapshots/YYYY/MM/DD/{snapshot-id}.json
s3://your-bucket/snapshots/latest.json

Snapshot Schema:

{
  "snapshot_id": "scan-2026-04-09-123456",
  "version": "v1",
  "generated_at": "2026-04-09T12:34:56Z",
  "findings_by_type": {
    "aurora": [
      {
        "resource_id": "db-cluster-1",
        "status": "red",
        "message": "Running deprecated version 13.3 (EOL: 2025-03-01)",
        "recommendation": "Upgrade to version 15.5 or later"
      }
    ]
  },
  "summary": {
    "total_resources": 150,
    "red_count": 12,
    "yellow_count": 35,
    "green_count": 103,
    "compliance_percentage": 68.7
  }
}

Consume snapshots with:

AWS Lambda triggered on S3 events
Scheduled cron job reading latest.json
Custom Temporal workflow (implement Stage 3: ACT)

3. Using the gRPC API

Version Guard exposes a gRPC API for querying compliance data:

# List services and their compliance scores
grpcurl -plaintext localhost:8080 \
  block.versionguard.VersionGuard/GetFleetSummary

# Get specific service score
grpcurl -plaintext -d '{"service":"my-service"}' \
  localhost:8080 block.versionguard.VersionGuard/GetServiceScore

# List all RED/YELLOW findings
grpcurl -plaintext -d '{"status":"red"}' \
  localhost:8080 block.versionguard.VersionGuard/ListFindings

📖 Documentation

ARCHITECTURE.md - Detailed system architecture
CONTRIBUTING.md - How to contribute
pkg/detector/ - Detector implementation examples

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

Code of conduct
Development setup
Testing guidelines
Pull request process

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🐛 Issues & Support

Bug reports: GitHub Issues
Feature requests: GitHub Discussions
Security issues: Please email security@block.xyz (do not open public issues)

🙏 Acknowledgments

Version Guard is maintained by Block, Inc. and the open-source community.

Special thanks to:

Temporal for the workflow orchestration framework
Wiz for multi-cloud security scanning
endoflife.date for open EOL data

Note: Version Guard is designed as a collector/detector system. The emission of findings to issue trackers, dashboards, or notification systems is left to implementers. See "Extending Version Guard" above for integration patterns.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.git-hooks		.git-hooks
.github		.github
charts/version-guard		charts/version-guard
cmd		cmd
deploy		deploy
pkg		pkg
protos/block/versionguard		protos/block/versionguard
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
ARCHITECTURE.md		ARCHITECTURE.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
USAGE.md		USAGE.md
codecov.yml		codecov.yml
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum
renovate.json		renovate.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Version Guard

🎯 Purpose

🏗️ Architecture

✨ Features

📦 Supported Resources

🚀 Quick Start

Prerequisites

Installation

Run Locally (docker-compose)

Run Locally (manual)

Trigger a Scan

Query Findings

Run Tests

🔧 Configuration

🎨 Classification Policy

🔌 Extending Version Guard

1. Implementing Custom Emitters

2. Consuming S3 Snapshots

3. Using the gRPC API

📖 Documentation

🤝 Contributing

📜 License

🐛 Issues & Support

🙏 Acknowledgments

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Version Guard

🎯 Purpose

🏗️ Architecture

✨ Features

📦 Supported Resources

🚀 Quick Start

Prerequisites

Installation

Run Locally (docker-compose)

Run Locally (manual)

Trigger a Scan

Query Findings

Run Tests

🔧 Configuration

🎨 Classification Policy

🔌 Extending Version Guard

1. Implementing Custom Emitters

2. Consuming S3 Snapshots

3. Using the gRPC API

📖 Documentation

🤝 Contributing

📜 License

🐛 Issues & Support

🙏 Acknowledgments

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages