Aegis Policy Scanner

Aegis Policy Scanner is a VS Code extension that scans your workspace files for policy violations using the Aegis policy engine by Pegasys.ai.

Features

• Workspace Scanning: Automatically scan JSON and YAML files against Aegis policies
• Policy Configuration: Configure scanning policies via .aegis.yaml file
• Real-time Diagnostics: View policy violations directly in the Problems panel
• Secure API Integration: Securely store API tokens using VS Code's Secret Storage
• SSL Configuration: Support for self-signed certificates in development environments
• Comprehensive Scan Summary: Detailed running counts and summary tables showing scan results, policy breakdown, and file status
• Progress Tracking: Real-time progress updates with detailed statistics during scanning
• 🤖 GitHub Copilot Integration: Built-in MCP tools and @aegis chat participant for intelligent fix suggestions

🚀 GitHub Copilot Integration

Aegis Scanner integrates with GitHub Copilot through Language Model Tools (MCP) and a dedicated @aegis Chat Participant.

Quick Start

1. Run a scan: Execute Aegis: Scan Workspace from the command palette
2. Open Copilot Chat: Click the chat icon in sidebar or press Ctrl/Cmd + I
3. Ask questions: Use @aegis for direct queries or mention Aegis naturally
4. Get intelligent responses: Copilot automatically uses registered tools for accurate answers

Two Ways to Interact

🎯 Method 1: @aegis Chat Participant (Fast & Direct)

The @aegis participant provides instant access to your scan data:

@aegis show me all violations
@aegis what violations are in config/database.yaml?
@aegis give me a scan summary
@aegis fix for compute.tf
@aegis what policies are configured?

Best for: Quick data queries, file-specific fixes, structured responses

🤖 Method 2: Natural Conversation with Copilot (AI-Powered)

Copilot automatically invokes Aegis tools when you mention Aegis:

What Aegis violations were found?
Why did my Aegis scan fail and what should I prioritize?
Explain the hardcoded-secrets violation and how to fix it

Best for: Complex analysis, explanations, strategic recommendations

Example Conversations

With @aegis (Direct Data):

You: @aegis show me all violations

Aegis: 🔍 Found 3 violation(s):

- hardcoded-secrets (error) in config/database.yaml:15
  Issue: Hardcoded database password detected
  Fix: Use environment variables or secrets manager
[...]

Natural Conversation (AI Analysis):

You: Why did my Aegis scan fail?

Copilot: Based on the Aegis scan results, you have 3 critical violations.
I recommend prioritizing the hardcoded secrets first because...
[Automatically used aegis_get_violations and aegis_get_scan_summary]

Behind the Scenes: MCP Tools

Four tools are registered with VS Code's Language Model API:

Note: You don't invoke these tools directly. Copilot and @aegis select them automatically.

Requirements

1. An Aegis API token from Pegasys.ai
2. A .aegis.yaml configuration file in your workspace root
3. (Optional) GitHub Copilot for AI-powered fix suggestions

.aegis.yaml Configuration

Create a .aegis.yaml file in your workspace root:

aegis_host: platform.aegis.pegasys.cloud
policies:
  - name: security_policy
    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: your-project-name
  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

Proxy Configuration

The extension supports HTTP and HTTPS proxy configuration through the .aegis.yaml file:

• http_proxy: URL for HTTP proxy (e.g., http://proxy.company.com:8080)
• https_proxy: URL for HTTPS proxy (e.g., http://proxy.company.com:8080)
• no_proxy: Comma-separated list of hosts to bypass proxy (e.g., 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

Labels Configuration

The labels field allows you to add custom key-value pairs that will be included in API calls for enhanced metadata 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"

Labels are optional and can contain any string values. Label keys must contain only alphanumeric characters, hyphens, and underscores.

Use Cases for Labels

Labels can be used for:

• 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
• Business Context: business_unit: engineering, cost_center: "12345"

Label Validation Rules

• Keys: Must contain only letters, numbers, hyphens (-), and underscores (_)
• Values: Can be any string (including numbers, special characters)
• Optional: Labels section is completely optional
• Security: Keys are validated to prevent injection attacks

Example with various label types:

labels:
  simple_label: value
  numeric_value: "12345"
  hyphenated-key: allowed
  underscore_key: also_allowed
  complex_value: "Special chars: @#$%^&*()"

Extension Settings

This extension contributes the following settings:

• aegisScanner.allowSelfSignedCerts: Allow self-signed SSL certificates (NOT RECOMMENDED for production, default: false)

Security

This extension implements comprehensive security measures including SSL/TLS enforcement, input validation, SSRF protection, and secure API token storage. For detailed security information, see SECURITY.md.

Usage

1. Set your API token: Run command Aegis: Set API Token
2. Create a .aegis.yaml configuration file in your workspace
3. Run command Aegis: Scan Workspace or click the Aegis icon in the status bar
4. View results in the Output panel and Problems panel

Enjoy scanning with Aegis!

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