Aegis DevOps Integration

This guide explains how to integrate Aegis Scanner into your DevOps workflows, including CI/CD pipelines and Infrastructure-as-Code (IaC) validation. The Aegis Pipeline Scanner automatically validates your codebase against Aegis security policies in popular platforms: GitHub Actions, GitLab CI, Azure DevOps, and Jenkins.

Overview

The Aegis Pipeline Scanner is a Docker-based tool that scans files in your repository against Aegis policies during pipeline execution. It provides automated security and compliance validation as part of your DevOps workflow.

Key capabilities:

• Automated scanning of JSON, YAML, Terraform, and other configuration files
• Native integration with GitHub Actions and GitLab CI
• Comprehensive reporting with detailed scan results
• Secure API token authentication
• Flexible configuration via .aegis.yaml
• Custom labels for metadata tracking
• Proxy support for corporate environments

Pipeline Workflow

The following diagram illustrates the Aegis Scanner validation flow in CI/CD pipelines:

---
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(("Start<br/>Pipeline"))
        B["Checkout<br/>Code"]
        C["Run Aegis<br/>Scanner"]
        D{{"Policy<br/>Evaluation"}}
        E(("Continue<br/>Pipeline"))
        F(("Fail<br/>Pipeline"))
        G["Aegis Policy<br/>Engine<br/>Security Check"]

        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

CI/CD Pipeline Security Scanning Flow – Click to zoom

---

Installation

The Aegis Scanner is available as a Docker image, optimized for CI/CD pipeline execution:

docker pull pegasysai/aegis-scanner:latest

This image comes pre-configured with all dependencies and is ready to use in your pipelines.

Configuration

Creating .aegis.yaml

Create a .aegis.yaml configuration file in your project root. This is the same configuration file used by the Aegis Scanner Plugin for VS Code.

# Replace <tenant-name> and <policy-name> as appropriate
aegis_host: <tenant-name>.aegis.pegasys.cloud
policies:
  - name: <policy-name>
    file_patterns:
      - "**/*.json"
      - "**/*.yaml"
      - "**/*.tf"
api_config:
  # DO NOT CHANGE THIS LINE - it is required for proper functioning
  endpoint: "https://{{aegis_host}}/api/eval/policies/{{policy_name}}"
labels:
  environment: production
  team: platform-security
  project: pipeline-scanner
  region: us-west-2
  compliance_level: high
proxy:
  http_proxy: http://proxy.company.com:8080
  https_proxy: http://proxy.company.com:8080
  no_proxy: localhost,127.0.0.1,.local

Configuration Options

Policy Configuration

Define which policies to enforce and which files to scan:

policies:
  - name: security_policy
    file_patterns:
      - "**/*.json"
      - "**/*.yaml"
  - name: terraform_compliance
    file_patterns:
      - "**/*.tf"
      - "**/*.tfvars"

Each policy requires: - name: Policy identifier (alphanumeric, hyphens, underscores only) - file_patterns: Array of glob patterns matching files to scan

Labels (Optional)

Add custom metadata to API calls for enhanced tracking and filtering:

labels:
  environment: production
  team: platform-security
  project: your-project-name
  region: us-west-2
  compliance_level: high
  business_unit: engineering
  cost_center: "12345"

Common label use cases:

• Environment identification (environment: production, environment: staging)
• Team attribution (team: platform-security, team: devops)
• Project tracking (project: my-app, project_id: PROJ-123)
• Compliance levels (compliance_level: high, compliance_level: pci-dss)
• Geographic information (region: us-west-2, datacenter: aws)

Proxy Configuration (Optional)

Configure HTTP/HTTPS proxy settings for corporate environments:

proxy:
  http_proxy: http://proxy.company.com:8080
  https_proxy: http://proxy.company.com:8080
  no_proxy: localhost,127.0.0.1,.local

Proxy URLs can include authentication credentials:

proxy:
  http_proxy: http://username:password@proxy.company.com:8080
  https_proxy: http://username:password@proxy.company.com:8080

Usage

The Aegis Scanner runs as a Docker container in your CI/CD pipelines. It automatically detects the .aegis.yaml configuration file and scans files matching the defined patterns.

Command Line Options

The scanner accepts the following options via Docker command arguments:

Option	Description
--token <token>	API token for Aegis service (required)
--workspace <path>	Workspace root path (default: current directory)
--allow-self-signed	Allow self-signed SSL certificates (development only)
--verbose	Enable verbose logging

Environment Variables

The following environment variables can be set in your pipeline:

Variable	Description
AEGIS_TOKEN	API token for authentication
AEGIS_WORKSPACE	Path to the workspace directory

Exit Codes

• 0: All scans passed
• 1: One or more scans failed or configuration error

CI/CD Platform Integration

GitHub Actions

Create .github/workflows/aegis-scan.yml in your repository:

name: Aegis Security Scan

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  aegis-scan:
    runs-on: ubuntu-latest
    container:
      image: pegasysai/aegis-scanner:latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Run Aegis Security Scan
      env:
        AEGIS_TOKEN: ${{ secrets.AEGIS_TOKEN }}
        AEGIS_WORKSPACE: ${{ github.workspace }}
      run: --token "$AEGIS_TOKEN"

Setting up GitHub Secrets:

1. Go to your repository's Settings > Secrets and variables > Actions
2. Click "New repository secret"
3. Name: AEGIS_TOKEN
4. Value: Your Aegis API token
5. Click "Add secret"

GitLab CI

Add to your .gitlab-ci.yml:

stages:
  - security-scan

aegis-scan:
  image: pegasysai/aegis-scanner:latest
  stage: security-scan
  variables:
    AEGIS_WORKSPACE: "$CI_PROJECT_DIR"
    AEGIS_TOKEN: "$AEGIS_TOKEN"  # Set in GitLab CI/CD variables
  script:
    - --token $AEGIS_TOKEN
  only:
    - main
    - merge_requests

Setting up GitLab Variables:

1. Go to your project's Settings > CI/CD > Variables
2. Click "Add variable"
3. Key: AEGIS_TOKEN
4. Value: Your Aegis API token
5. Check "Mask variable" to hide it in logs
6. Click "Add variable"

Azure DevOps

Add to your azure-pipelines.yml:

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

container: pegasysai/aegis-scanner:latest

steps:
- checkout: self

- script: |
    --token "$(AEGIS_TOKEN)"
  displayName: 'Run Aegis Security Scan'
  env:
    AEGIS_TOKEN: $(AEGIS_TOKEN)
    AEGIS_WORKSPACE: $(Build.SourcesDirectory)

Setting up Azure DevOps Variables:

1. Go to your pipeline's edit page
2. Click "Variables" button
3. Click "+ Add"
4. Name: AEGIS_TOKEN
5. Value: Your Aegis API token
6. Check "Keep this value secret"
7. Click "OK" and save

Jenkins

Add to your Jenkinsfile:

pipeline {
  agent {
    docker {
      image 'pegasysai/aegis-scanner:latest'
    }
  }

  environment {
    AEGIS_TOKEN = credentials('aegis-api-token')
    AEGIS_WORKSPACE = "${WORKSPACE}"
  }

  stages {
    stage('Aegis Security Scan') {
      steps {
        sh '--token "$AEGIS_TOKEN"'
      }
    }
  }

  post {
    failure {
      echo 'Aegis security scan failed. Review policy violations.'
    }
  }
}

Setting up Jenkins Credentials:

1. Go to Jenkins > Manage Jenkins > Manage Credentials
2. Select appropriate domain or add to Global
3. Click "Add Credentials"
4. Kind: "Secret text"
5. Secret: Your Aegis API token
6. ID: aegis-api-token
7. Description: "Aegis API Token"
8. Click "Create"

Scanning Terraform Plans and State

In addition to scanning Terraform source files (.tf), you can validate Terraform plans by generating them as JSON files in your workspace. The Aegis Scanner will automatically pick up these files based on your .aegis.yaml configuration.

Workflow

1. Generate Terraform plan and export as JSON to workspace
2. Run Aegis Scanner - it will scan the plan JSON files based on .aegis.yaml file patterns
3. Evaluate the results: if policy violations are found, the pipeline fails

Configuration

Ensure your .aegis.yaml includes patterns for JSON files:

# Replace <tenant-name> and <policy-name> as appropriate
aegis_host: <tenant-name>.aegis.pegasys.cloud
policies:
  - name: terraform_policy
    file_patterns:
      - "**/*.tf"
      - "**/*.json"  # This will pick up the generated plan files
api_config:
  # DO NOT CHANGE THIS LINE - it is required for proper functioning
  endpoint: "https://{{aegis_host}}/api/eval/policies/{{policy_name}}"

GitHub Actions Example

name: Terraform Security Scan

on:
  pull_request:
    branches: [ main ]

jobs:
  terraform-scan:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup Terraform
      uses: hashicorp/setup-terraform@v3
      with:
        terraform_version: 1.6.0

    - name: Terraform Init
      run: terraform init

    - name: Terraform Plan
      run: terraform plan -out=tfplan

    - name: Export Plan as JSON
      run: terraform show -json tfplan > tfplan.json

    - name: Run Aegis Scanner
      uses: docker://pegasysai/aegis-scanner:latest
      env:
        AEGIS_TOKEN: ${{ secrets.AEGIS_TOKEN }}
        AEGIS_WORKSPACE: ${{ github.workspace }}
      with:
        args: --token "$AEGIS_TOKEN"

GitLab CI Example

stages:
  - plan
  - scan

terraform_plan:
  stage: plan
  image: hashicorp/terraform:1.6
  script:
    - terraform init
    - terraform plan -out=tfplan
    - terraform show -json tfplan > tfplan.json
  artifacts:
    paths:
      - tfplan.json
    expire_in: 1 hour

aegis_scan:
  stage: scan
  image: pegasysai/aegis-scanner:latest
  dependencies:
    - terraform_plan
  variables:
    AEGIS_WORKSPACE: "$CI_PROJECT_DIR"
    AEGIS_TOKEN: "$AEGIS_TOKEN"
  script:
    - --token $AEGIS_TOKEN

Azure DevOps Example

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: TerraformPlan
  jobs:
  - job: Plan
    steps:
    - task: TerraformInstaller@0
      inputs:
        terraformVersion: '1.6.0'

    - script: |
        terraform init
        terraform plan -out=tfplan
        terraform show -json tfplan > tfplan.json
      displayName: 'Terraform Plan and Export'

    - publish: $(System.DefaultWorkingDirectory)/tfplan.json
      artifact: TerraformPlan

- stage: SecurityScan
  dependsOn: TerraformPlan
  jobs:
  - job: AegisScan
    container: pegasysai/aegis-scanner:latest
    steps:
    - download: current
      artifact: TerraformPlan

    - script: |
        cp $(Pipeline.Workspace)/TerraformPlan/tfplan.json $(System.DefaultWorkingDirectory)/
        --token "$(AEGIS_TOKEN)"
      displayName: 'Run Aegis Scanner'
      env:
        AEGIS_TOKEN: $(AEGIS_TOKEN)
        AEGIS_WORKSPACE: $(System.DefaultWorkingDirectory)

Jenkins Example

pipeline {
  agent any

  environment {
    AEGIS_TOKEN = credentials('aegis-api-token')
  }

  stages {
    stage('Terraform Plan') {
      steps {
        sh '''
          terraform init
          terraform plan -out=tfplan
          terraform show -json tfplan > tfplan.json
        '''
      }
    }

    stage('Aegis Security Scan') {
      agent {
        docker {
          image 'pegasysai/aegis-scanner:latest'
        }
      }
      environment {
        AEGIS_WORKSPACE = "${WORKSPACE}"
      }
      steps {
        sh '--token "$AEGIS_TOKEN"'
      }
    }
  }

  post {
    failure {
      echo 'Security scan failed. Review Terraform plan violations.'
    }
  }
}

Notes

• The scanner automatically detects and scans files matching patterns in .aegis.yaml
• Terraform plan JSON files are treated like any other JSON file in the scan
• Ensure the plan JSON file is generated in the workspace before running the scanner
• Use artifacts/caching in multi-stage pipelines to pass plan files between stages
• Consider scanning both source .tf files and generated plan files for comprehensive coverage

Best Practices

Security

• Store API tokens securely: Always use CI/CD secret management
• Use HTTPS endpoints: Ensure production deployments use HTTPS
• Validate configuration: Review .aegis.yaml before committing
• Minimize token scope: Use tokens with minimal required permissions
• Rotate tokens regularly: Implement token rotation policies

Configuration Management

• Version control .aegis.yaml: Commit configuration to repository
• Environment-specific configs: Use different configs for dev/staging/prod
• Document policies: Maintain clear documentation of policy requirements
• Test configuration: Validate config changes in non-production first

Pipeline Integration

• Run early in pipeline: Scan before expensive build/deployment steps
• Fail fast: Configure pipeline to stop on policy violations
• Clear error messages: Enable verbose logging for troubleshooting
• Monitor scan duration: Track performance and optimize file patterns
• Parallel execution: Run scans in parallel with other validation steps where possible

Development Workflow

Combine CI/CD scanning with the Aegis Scanner Plugin for VS Code for comprehensive coverage:

1. Development: Use VS Code plugin for real-time feedback
2. Pre-commit: Run local scans before committing
3. Pull Request: Automated CI/CD scans on PR creation
4. Merge: Final validation before merging to main branch
5. Deployment: Production deployment validation

Troubleshooting

Common Issues

Issue	Symptom	Solutions
Authentication Failures	401 Unauthorized or 403 Forbidden errors	• Verify API token is valid and not expired • Check token has necessary permissions • Ensure token is correctly set in CI/CD secrets • Confirm token hasn't been rotated without updating CI/CD
Configuration Not Found	Error: .aegis.yaml not found	• Verify .aegis.yaml exists in repository root • Check file is committed to version control • Ensure workspace path is correct • Verify file permissions allow reading
Network/Proxy Issues	Connection timeouts or network errors	• Verify proxy configuration in .aegis.yaml • Test connectivity to Aegis platform from CI/CD environment • Check firewall rules allow outbound HTTPS • Review no_proxy settings for internal hosts
SSL Certificate Errors	UNABLE_TO_VERIFY_LEAF_SIGNATURE or SSL errors	• Install proper CA certificates in CI/CD environment • Use --allow-self-signed flag for development (not recommended for production) • Contact platform team for certificate issues • Verify SSL/TLS configuration
Scan Timeouts	Scanner times out or runs too long	• Optimize file patterns to reduce scanned files • Exclude unnecessary directories (node_modules, .git, etc.) • Increase CI/CD timeout limits if needed • Contact support if platform response is slow

Getting Help

If you encounter issues:

1. Enable verbose logging with --verbose flag
2. Review scan output and error messages
3. Check Aegis Platform documentation
4. Verify configuration against VS Code Scanner guide
5. Contact Pegasys AI support at support@pegasys.ai

Next Steps

• Development Integration: Set up the Aegis Scanner Plugin for VS Code
• Policy Management: Learn about Managing Policies
• Platform Concepts: Understand Aegis Platform architecture
• API Reference: Explore the Policy Evaluation API
• Continuous Monitoring: Implement runtime policy monitoring

---

Copyright © 2025 Pegasys AI (www.pegasys.ai). All rights reserved.