Integrating Aegis Policy Validation into IaC Pipelines¶

This guide explains how to integrate Aegis Policy Engine validation into Infrastructure-as-Code (IaC) pipelines using popular CI/CD platforms: GitLab CI, GitHub Actions, Azure DevOps, and Jenkins. The integration ensures that Terraform plans or state files are validated against your organization's security and compliance policies before deployment.

Overview¶

Aegis Policy Engine can be integrated into your Infrastructure-as-Code (IaC) pipeline to automatically validate Terraform plans or state files for security and compliance before deployment. The typical workflow is:

Export the Terraform plan or state as JSON.
Send the exported JSON to the Aegis Policy Engine via a REST API call.
Evaluate the response: if the policy check passes, the pipeline continues; if it fails, the pipeline stops.

The following diagram illustrates this validation flow:

---
config:
  theme: base
  themeVariables:
    background: transparent
    mainBkg: '#fef7ff'
    primaryColor: '#ddd6fe'
    primaryTextColor: '#1e293b'
    primaryBorderColor: '#c4b5fd'
    lineColor: '#a78bfa'
    sectionBkgColor: '#fef7ff'
    altSectionBkgColor: '#f3e8ff'
    gridColor: '#e9d5ff'
    secondaryColor: '#bbf7d0'
    tertiaryColor: '#fecaca'
    secondBkg: '#bbf7d0'
    tertiaryBkg: '#fecaca'
    darkMode: false
    textColor: '#1e293b'
    secondaryTextColor: '#334155'
    tertiaryTextColor: '#7c2d12'
    noteTextColor: '#1e293b'
    errorTextColor: '#991b1b'
    fontFamily: 'Inter, Segoe UI, Arial, sans-serif'
---
flowchart LR
    subgraph pipeline ["🚀 CI/CD Pipeline"]
        direction LR
        A(("🏁<br/>Start<br/>Pipeline"))
        B["📋<br/>Export<br/>Terraform<br/>Plan as JSON"]
        C["🌐<br/>Send to<br/>Aegis<br/>Engine"]
        D{{"⚖️<br/>Policy<br/>Evaluation"}}
        E(("✅<br/>Continue<br/>Pipeline"))
        F(("❌<br/>Fail<br/>Pipeline"))
        G["🛡️<br/>Aegis Policy<br/>Engine<br/>🔍 Security"]

        A --> B
        B --> C
        C -.->|"📡 API Call"| G
        G -.->|"📊 Response"| D
        D -->|"✓ Passed"| E
        D -->|"✗ Failed"| F
    end

    classDef startEnd fill:#bbf7d0,stroke:#86efac,stroke-width:2px,color:#1e293b,font-weight:bold,rx:20,ry:20
    classDef process fill:#ddd6fe,stroke:#c4b5fd,stroke-width:2px,color:#1e293b,font-weight:bold,rx:20,ry:20
    classDef decision fill:#fed7aa,stroke:#fdba74,stroke-width:2px,color:#7c2d12,font-weight:bold,rx:20,ry:20
    classDef fail fill:#fecaca,stroke:#fca5a5,stroke-width:2px,color:#991b1b,font-weight:bold,rx:20,ry:20
    classDef external fill:#bfdbfe,stroke:#93c5fd,stroke-width:2px,color:#1e40af,font-weight:bold,rx:20,ry:20

    class A,E startEnd
    class B,C process
    class D decision
    class F fail
    class G external

    style pipeline fill:#fef7ff,stroke:#e9d5ff,stroke-width:2px,stroke-dasharray: 8 4,rx:25,ry:25

IaC Policy Validation Pipeline Flow – Click to zoom

Prerequisites¶

Access to the Aegis Policy Engine API endpoint and an API token.
Terraform installed in your CI/CD environment.
The ability to export your Terraform plan or state as JSON (e.g., using terraform show -json or terraform state pull).

Example Integration Steps¶

1. Export Terraform State or Plan as JSON¶

terraform show -json > tfplan.json
# or for state
terraform state pull > tfstate.json

2. Call the Aegis Policy Engine API¶

curl -X POST "https://<aegis-endpoint>/api/eval/policies/<policy-name>" \
  -H "Authorization: Bearer $AEGIS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputData": <contents-of-tfplan-or-tfstate>}'

Parse the response and fail the pipeline if the policy evaluation fails.

GitLab CI Example¶

stages:
  - validate

aegis_policy_validation:
  stage: validate
  script:
    - terraform show -json > tfplan.json
    - |
      RESPONSE=$(curl -s -X POST "https://<aegis-endpoint>/api/eval/policies/<policy-name>" \
        -H "Authorization: Bearer $AEGIS_TOKEN" \
        -H "Content-Type: application/json" \
        -d @tfplan.json)
      echo "$RESPONSE"
      echo "$RESPONSE" | grep '"passed": true' || (echo "Policy validation failed" && exit 1)
  only:
    - merge_requests
    - main

GitHub Actions Example¶

name: IaC Policy Validation
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Terraform Plan
        run: terraform show -json > tfplan.json
      - name: Aegis Policy Validation
        run: |
          RESPONSE=$(curl -s -X POST "https://<aegis-endpoint>/api/eval/policies/<policy-name>" \
            -H "Authorization: Bearer ${{ secrets.AEGIS_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d @tfplan.json)
          echo "$RESPONSE"
          echo "$RESPONSE" | grep '"passed": true' || (echo "Policy validation failed" && exit 1)

Azure DevOps Example¶

- stage: Validate
  jobs:
    - job: PolicyValidation
      steps:
        - script: terraform show -json > tfplan.json
        - script: |
            RESPONSE=$(curl -s -X POST "https://<aegis-endpoint>/api/eval/policies/<policy-name>" \
              -H "Authorization: Bearer $(AEGIS_TOKEN)" \
              -H "Content-Type: application/json" \
              -d @tfplan.json)
            echo "$RESPONSE"
            echo "$RESPONSE" | grep '"passed": true' || (echo "Policy validation failed" && exit 1)

Jenkins Pipeline Example¶

pipeline {
  agent any
  stages {
    stage('Terraform Plan') {
      steps {
        sh 'terraform show -json > tfplan.json'
      }
    }
    stage('Aegis Policy Validation') {
      steps {
        script {
          def response = sh(script: 'curl -s -X POST "https://<aegis-endpoint>/api/eval/policies/<policy-name>" \
            -H "Authorization: Bearer $AEGIS_TOKEN" \
            -H "Content-Type: application/json" \
            -d @tfplan.json', returnStdout: true).trim()
          echo response
          if (!response.contains('"passed": true')) {
            error('Policy validation failed')
          }
        }
      }
    }
  }
}

Notes¶

Replace <aegis-endpoint>, <policy-name>, and token variables with your actual values.
You may use terraform state pull instead of terraform show if you want to validate the current state.
For more advanced parsing, use jq or similar tools to inspect the API response.

By integrating Aegis Policy validation into your CI/CD pipeline, you ensure that infrastructure changes comply with your organization's security and compliance requirements before deployment.