aegis

README

AEGIS

AEGIS - The divine shield that validates your API contracts.

A high-performance API contract testing platform that validates real API responses against OpenAPI specifications. Designed for CI/CD integration, AEGIS ensures API contract compliance through automated testing, detailed reporting, and actionable feedback.

Features

• OpenAPI 3.0/3.1 Support - Validate against the latest OpenAPI specifications
• Multi-Protocol Support - OpenAPI, GraphQL, gRPC, AsyncAPI, and WebSocket testing
• Real API Testing - Test against live endpoints, not just mock data
• Parallel Execution - Fast validation with configurable concurrency
• Multiple Output Formats - Table, JSON, HTML, JUnit, TAP, and Jest reports
• CI/CD Ready - GitHub Actions integration with status checks
• Detailed Error Messages - Clear, actionable feedback on contract violations
• Cross-Platform - Works on Linux, macOS, and Windows

Quick Start

Installation

Homebrew (macOS/Linux)

brew tap klismannb/aegis
brew install aegis

Go Install

go install github.com/klismannb/aegis/cmd/aegis@latest

Download Binary

Download the latest release from the releases page.

Usage

Basic Validation

# Validate a spec against a live API
aegis validate --spec ./openapi.yaml --base-url https://api.example.com

Output Formats

AEGIS supports multiple output formats for different use cases:

# Human-readable table (default)
aegis validate --spec ./openapi.yaml --base-url https://api.example.com

# JSON for programmatic use
aegis validate --spec ./openapi.yaml --base-url https://api.example.com --format json --output results.json

# HTML report
aegis validate --spec ./openapi.yaml --base-url https://api.example.com --format html --output report.html

# JUnit XML for CI/CD integration (Jenkins, GitLab, etc.)
aegis validate --spec ./openapi.yaml --base-url https://api.example.com --format junit --output junit.xml

# TAP (Test Anything Protocol)
aegis validate --spec ./openapi.yaml --base-url https://api.example.com --format tap

# Jest-like output
aegis validate --spec ./openapi.yaml --base-url https://api.example.com --format jest

GitHub Actions

name: API Validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate API
        uses: klismannb/aegis/validate-action@v1
        with:
          spec: './openapi.yaml'
          base-url: 'https://api.staging.example.com'

Documentation

• Technical Specification
• Project Structure
• MVP Scope
• Contributing Guide
• Getting Started

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   OpenAPI   │────▶│   Validator  │────▶│   Report    │
│    Spec     │     │    Engine    │     │   Output    │
└─────────────┘     └──────────────┘     └─────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │   Live API   │
                     └──────────────┘

Development

Prerequisites

• Go 1.21 or later
• Make
• golangci-lint (optional but recommended)

Setup

# Clone the repository
git clone https://github.com/klismannb/aegis.git
cd aegis

# Download dependencies
make deps

# Build
make build

# Run tests
make test

# Run linter
make lint

Project Structure

aegis/
├── cmd/
│   ├── aegis/          # CLI entry point
│   └── lsp/            # Language Server Protocol implementation
├── internal/           # Internal packages
│   ├── commands/       # CLI commands
│   ├── config/         # Configuration
│   └── output/         # Output formatters
├── pkg/                # Public packages
│   ├── openapi/        # OpenAPI parsing
│   ├── graphql/        # GraphQL schema validation
│   ├── grpc/           # gRPC/Protocol Buffer testing
│   ├── asyncapi/       # AsyncAPI specification support
│   ├── websocket/      # WebSocket testing
│   ├── serverless/     # Serverless/API Gateway testing (AWS Lambda, Azure, GCP)
│   ├── validator/      # Validation engine
│   ├── testrunner/     # Test execution
│   ├── reporter/       # Report generation
│   ├── diff/           # Schema diff visualization
│   └── repository/     # Community rule repository client
├── api/                # SaaS API server
│   ├── cmd/server/     # API server entry point
│   └── internal/       # API internal code
├── editors/            # IDE/Editor extensions
│   ├── vscode/         # VS Code extension
│   ├── intellij/       # IntelliJ/WebStorm plugin
│   ├── vim/            # Vim/Neovim plugin
│   └── emacs/          # Emacs integration
├── integrations/       # CI/CD integrations
│   ├── gitlab-ci/      # GitLab CI templates
│   ├── jenkins/        # Jenkins shared library
│   ├── circleci/       # CircleCI orb
│   ├── azure-devops/   # Azure DevOps extension
│   └── bitbucket-pipelines/  # Bitbucket Pipes
└── tests/              # Test suites

Roadmap

See ROADMAP.md for a detailed project roadmap including:

• Current development phase and milestones
• Upcoming features and timelines
• Version planning and release schedule
• Success metrics and risk assessment

Quick Overview

• ✅ Phase 1 (MVP): Core CLI with validation, reporting, and GitHub Actions
• ✅ Phase 2: Enhanced developer experience with additional output formats
• ✅ Phase 3: Advanced validation rules and performance testing
• ✅ Phase 4: SaaS platform foundation with API, database, and RBAC
• 🚧 Phase 5: Ecosystem expansion (GraphQL, gRPC, AsyncAPI, WebSocket)
• 📋 Phase 6+: Enterprise features and AI-powered capabilities

Current Status: Phase 5 in progress (v2.0.0 released)

Completed Features:

• ✅ Multi-protocol support (OpenAPI, GraphQL, gRPC, AsyncAPI, WebSocket)
• ✅ 6 CI/CD integrations (GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure DevOps, Bitbucket)
• ✅ Advanced validation with custom rules
• ✅ AI-powered test generation and anomaly detection
• ✅ Enterprise integrations (Slack, Teams, Jira, ServiceNow)

Security

AEGIS takes security seriously. We employ multiple layers of security scanning:

Snyk Integration

We use Snyk to continuously monitor for vulnerabilities in:

• Dependencies - Go modules and third-party packages
• Code - Static code analysis for security issues
• Licenses - License compliance checking

Security Scanning

Our CI/CD pipeline includes automated security scanning:

# Security scans run on every PR and daily
- Snyk dependency vulnerability scan
- Snyk static code analysis (SAST)
- Gosec security scanner
- Dependency review for PRs

Reporting Security Issues

If you discover a security vulnerability, please:

1. DO NOT open a public issue
2. Email security concerns to: security@aegis.dev
3. Include detailed information about the vulnerability
4. Allow time for the issue to be addressed before public disclosure

We follow responsible disclosure practices and will:

• Acknowledge receipt within 48 hours
• Provide regular updates on the fix progress
• Credit you in the security advisory (if desired)

Security Best Practices

When using AEGIS:

• Always use the latest version
• Regularly run go mod tidy and go mod verify
• Review the Snyk vulnerability report
• Enable security scanning in your CI/CD pipeline
• Use environment variables for sensitive configuration (API keys, tokens)
• Follow the principle of least privilege for API testing

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

• kin-openapi - OpenAPI validation library
• Cobra - CLI framework
• All contributors who have helped shape AEGIS

---

AEGIS - Guarding your API boundaries with precision. ⚔️🛡️