initial commit - initial implementation of Version Guard - Cloud Infrastructure Version Compliance Monitoring

[Kiran01bm]

Summary

This PR introduces Version Guard, an open-source system for monitoring and reporting on cloud infrastructure version compliance across AWS resources.

What is Version Guard?

Version Guard continuously monitors cloud infrastructure versions (databases, caches, Kubernetes clusters) and classifies them by lifecycle status:

• RED: End-of-Life or deprecated versions (urgent upgrade required)
• YELLOW: Extended support or approaching EOL (plan upgrade soon)
• GREEN: Current, fully supported versions

Key Features

Core Components

Detection Pipeline (Stages 1 & 2):

• Stage 1 - DETECT: Fan-out detection across resource types (Aurora, ElastiCache, EKS)
• Stage 2 - STORE: Versioned S3 snapshots for audit trail and downstream processing

Inventory Integration:

• Wiz API integration for multi-cloud asset inventory
• Mock inventory sources for local testing

EOL Data Providers:

• AWS RDS API (Aurora MySQL/PostgreSQL versions)
• AWS EKS API (Kubernetes versions)
• endoflife.date API (Redis, Memcached, Valkey)
• Extensible provider interface for custom sources

Classification Engine:

• Configurable policies for Red/Yellow/Green classification
• Considers: EOL status, deprecation, extended support, time to EOL

Temporal Workflows:

• Orchestrator workflow (fan-out to all resource types)
• Detection workflows (per resource type: Aurora, ElastiCache, EKS)
• Snapshot workflow (S3 persistence with pagination)

gRPC Query API:

• GetServiceScore - compliance score per service
• ListFindings - filterable findings list (by service, status, region, etc.)
• GetFleetSummary - aggregate fleet statistics

Command-line Interface:

• Fleet summary commands
• Finding list/export commands
• Service compliance checks

Extensibility

Emitter Interfaces (Defined, Not Implemented):

• ASREmitter - for issue tracking systems
• DXEmitter - for compliance dashboards
• Users implement their own emitters based on interfaces
• Example logging emitters provided for reference

Service Attribution:

• 3-tier fallback: Resource tags → Registry API → Name parsing
• Registry client interface for custom service lookups

Supported Resources

Resource Type	Cloud	EOL Provider	Status
Aurora MySQL/PostgreSQL	AWS	AWS RDS API	✅ Implemented
ElastiCache (Redis/Memcached/Valkey)	AWS	endoflife.date	✅ Implemented
EKS (Kubernetes)	AWS	AWS EKS API	✅ Implemented
More coming..

Technical Details

Stack:

• Language: Go 1.24
• Workflow Engine: Temporal
• API: gRPC (Protocol Buffers)
• Storage: In-memory store + S3 snapshots
• Cloud SDKs: AWS SDK v2
• Testing: 183 unit tests, 3 integration tests

Project Structure:

pkg/
├── types/          # Core data structures (Resource, Finding, VersionLifecycle)
├── policy/         # Classification policies (Red/Yellow/Green logic)
├── inventory/      # Inventory sources (Wiz, mock)
├── eol/            # EOL providers (AWS RDS/EKS, endoflife.date)
├── detector/       # Resource-specific detectors (Aurora, ElastiCache, EKS)
├── store/          # Storage abstraction (in-memory)
├── snapshot/       # S3 snapshot management
├── workflow/       # Temporal workflows (detection, orchestrator)
├── service/grpc/   # gRPC service implementation
├── emitters/       # Emitter interfaces (ASR, DX)
└── registry/       # Service registry interface

cmd/
├── server/         # Full working example server
└── cli/            # Command-line interface

Getting Started

Prerequisites:

• Go 1.24+
• Temporal server (local or remote)
• AWS credentials (for EOL API access)
• Optional: Wiz credentials (otherwise uses mock data)

Quick Start:

# Clone and build
git clone https://github.com/block/Version-Guard.git
cd Version-Guard
make build

# Copy environment template
cp .env.example .env
# Edit .env with your values

# Run local Temporal (if needed)
make temporal

# Start the server
./bin/version-guard

# In another terminal, query the API
./bin/version-guard-cli fleet summary

Testing

# Run all tests
make test

# Run linter
make lint

# Build binaries
make build

Test Coverage:

• 183 total tests across 22 packages
• Unit tests for all detectors (Aurora: 41 tests, EKS, ElastiCache)
• Integration tests with real endoflife.date API
• Policy engine tests (16 tests)
• Workflow tests with Temporal test suite

Documentation

• README.md - Project overview, quick start, architecture
• ARCHITECTURE.md - Detailed architecture, interfaces, extensibility guide
• USAGE.md - Operational guide for service owners and platform operators
• CONTRIBUTING.md - Contribution guidelines

Future Extensions

Multi-Cloud Support (framework in place):

• GCP: CloudSQL, Memorystore, GKE
• Azure: Azure Database, Redis Cache, AKS

Additional Resource Types:

• Lambda runtimes
• RDS (non-Aurora)
• OpenSearch
• DynamoDB

Advanced Features:

• Historical trend analysis
• Automated remediation workflows
• Compliance reporting dashboards
• Alert integrations

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[bakayolo]

🔍 Block-Specific Reference Audit

This PR contains several Block/Square-internal references that must be cleaned up before merging to open source.

🔴 HIGH — Must Fix

.golangci.yml:

1. local-prefixes: github.com/squareup/version-guard → should be github.com/block/Version-Guard
2. skip-dirs: protos/squareup → should be protos/block
3. # Based on Square's Go linting standards → remove "Square's"

Makefile:
4. docker build -t squareup/version-guard:latest (×2 in docker-build and docker-run) → block/version-guard
5. goimports -local github.com/squareup/version-guard → github.com/block/Version-Guard
6. -not -path './protos/squareup/*' (×3 in fmt, fmt-imports, lines targets) → ./protos/block/*

pkg/emitters/emitters.go + pkg/emitters/examples/logging_emitter.go:
7. ASREmitter / ASRResult / LoggingASREmitter — "ASR" = AppSecReporter, Block's internal Security Command Center. Rename to generic names (e.g., IssueTrackerEmitter)
8. DXEmitter / DXResult / LoggingDXEmitter — "DX" = Block's internal developer experience platform. Rename to generic names (e.g., ScorecardEmitter)
9. Comments explicitly name internal tools: "AppSecReporter (SCC issue tracking)", "DX Scorecards"

🟡 MEDIUM — Block-Specific Conventions

pkg/inventory/wiz/aurora.go:
10. Tag keys "block-appname", "block-environment", "block-brand" are Block's internal AWS tagging conventions. These should be made configurable or replaced with generic defaults like "appname", "environment", "brand".

⚠️ Inconsistency

The pre-push hook correctly excludes ./protos/block/*, but the Makefile excludes ./protos/squareup/* — these contradict each other.

✅ Clean

go.mod, cmd/, all detectors, workflows, proto definitions, .env.example, CONTRIBUTING.md, README.md, ARCHITECTURE.md, USAGE.md, CI workflow — no Block-specific leakage. No internal URLs, secrets, or credentials found.

[bakayolo]

Approving so I am not blocking — please address the inline comments about squareup references, ASR/DX naming, and block-* tag conventions before merging.