Aegis Policy Scanner for VS Code

The Aegis Policy Scanner is a VS Code extension that enables development-time policy adherence scanning, allowing developers to catch policy violations early in the development cycle before code reaches CI/CD pipelines or production.

Overview

Aegis Policy Scanner integrates directly into your development environment, providing real-time policy validation for JSON, YAML, and Terraform files as you work. This shift-left approach helps teams identify and fix security and compliance issues at the earliest possible stage.

Features

• Workspace Scanning: Automatically scan JSON, YAML, and Terraform 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

Installation

1. Open VS Code
2. Go to the Extensions view (Ctrl/Cmd + Shift + X)
3. Search for "Aegis Scanner by Pegasys AI"
4. Click Install

Alternatively, you can install from the VS Code Marketplace.

Requirements

Before using the Aegis Policy Scanner, you'll need:

1. Aegis API Token: Obtain an API token from your Aegis Platform account
2. Configuration File: Create a .aegis.yaml file in your workspace root
3. (Optional) GitHub Copilot: For AI-powered fix suggestions and intelligent analysis

Configuration

Setting Your API Token

1. Open the Command Palette (Ctrl/Cmd + Shift + P)
2. Run the command: Aegis: Set API Token
3. Enter your API token when prompted

The token is securely stored using VS Code's Secret Storage and is never saved in plain text.

Creating .aegis.yaml

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

# .aegis.yaml - Aegis Policy Scanner Configuration
aegis_host: <tenant-name>.aegis.pegasys.cloud #change the <tenant-name> as appropriate

# Define Aegis policies to scan
policies:
  - name: <policy-name 1>
    #change the <policy-name 1> as appropriate
    file_patterns:
      - "**/*.json"
  - name: <policy-name 2>
    #change the <policy-name 2> as appropriate
    file_patterns:
      - "**/*.tf"

# DO NOT CHANGE THIS SECTION - it is required for proper functioning
api_config:
  endpoint: "https://{{aegis_host}}/api/eval/policies/{{policy_name}}"

# Add custom labels as needed
labels:
  environment: production
  team: platform-security
  project: your-project-name
  region: us-west-2

# Optional proxy configuration
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"

Each policy must have: - name: The name of the policy in your Aegis Platform - file_patterns: Glob patterns matching files to scan

Labels

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

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

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 - 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

Proxy Configuration

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

Running a Scan

There are two ways to scan your workspace:

1. Command Palette:
2. Open Command Palette (Ctrl/Cmd + Shift + P)

3. Run: Aegis: Scan Workspace

4. Status Bar:

5. Click the Aegis icon in the status bar

Viewing Results

Scan results appear in two places:

1. Output Panel: Detailed scan logs and summary
2. View > Output

3. Select "Aegis Scanner" from the dropdown

4. Problems Panel: List of all violations

5. View > Problems (Ctrl/Cmd + Shift + M)
6. Click on any violation to jump to the file and line

Scan Summary

After each scan, you'll see a comprehensive summary including:

• Total Files Scanned: Number of files processed
• Violations Found: Count of policy violations
• Policy Breakdown: Violations per policy
• File Status: Pass/fail status for each file

GitHub Copilot Integration

Aegis Scanner integrates with GitHub Copilot through Language Model Tools (MCP) and a dedicated @aegis Chat Participant, enabling AI-powered policy violation analysis and fix suggestions.

Quick Start with Copilot

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 in conversation:

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]

Available Copilot Tools

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

Tool	Purpose	Auto-Invoked When
aegis_get_violations	Get violations (optional file filter)	Asking about issues/violations
aegis_get_scan_summary	Get scan statistics	Asking about results/summary
aegis_get_configuration	Get scanner config	Asking about policies/settings
aegis_generate_file_fixes	Generate file fixes	Asking to fix specific files

Automatic Tool Selection

You don't invoke these tools directly. Copilot and @aegis select them automatically based on your questions.

Extension Settings

Configure the extension behavior through VS Code settings:

• aegisScanner.allowSelfSignedCerts: Allow self-signed SSL certificates
• Default: false
• Warning: Only enable in development environments, NOT recommended for production

To modify settings: 1. Open Settings (Ctrl/Cmd + ,) 2. Search for "Aegis Scanner" 3. Adjust settings as needed

Security

The Aegis Policy Scanner implements comprehensive security measures:

• SSL/TLS Enforcement: All API communications use HTTPS by default
• Secure Token Storage: API tokens stored using VS Code's Secret Storage API
• Input Validation: All configuration inputs are validated and sanitized
• SSRF Protection: API endpoint validation prevents server-side request forgery
• No Plaintext Secrets: Tokens never written to disk in plain text

Self-Signed Certificates

The allowSelfSignedCerts setting should only be enabled for development environments with self-signed certificates. Never enable this in production environments as it reduces security.

Development Workflow Best Practices

Shift-Left Security

Integrate Aegis Scanner into your daily development workflow:

1. Before Committing: Run a scan before committing code
2. During Development: Keep the scanner active for real-time feedback
3. Code Reviews: Reference scan results in pull request discussions
4. CI/CD Integration: Combine with DevOps Integration for multi-layer validation

Continuous Scanning

Configure your development workflow to make policy validation automatic:

• Enable auto-save in VS Code for immediate feedback
• Set up pre-commit hooks to run scans before commits
• Use GitHub Copilot integration for immediate fix suggestions
• Review scan results in the Problems panel regularly

Team Collaboration

Share configurations across your team:

1. Commit .aegis.yaml to version control
2. Document required policies in project README
3. Establish team standards for violation handling
4. Use labels for team/project attribution

Troubleshooting

Common Issues

Issue	Symptom	Solutions
API Token Invalid	Scan fails with authentication error	• Verify token is still valid in Aegis Platform • Run Aegis: Set API Token to update • Check token has necessary permissions
No Violations Detected	Scan completes but no violations shown	• Verify .aegis.yaml file patterns match your files • Check policies are active in Aegis Platform • Review Output panel for scan details
Proxy Connection Issues	Cannot connect to Aegis API	• Verify proxy configuration in .aegis.yaml • Test proxy connectivity outside VS Code • Check no_proxy settings for internal hosts
Self-Signed Certificate Errors	SSL certificate verification fails	• Enable aegisScanner.allowSelfSignedCerts (development only) • Install proper CA certificates in development environment • Contact platform team for production certificate issues

Getting Help

If you encounter issues:

1. Check the Output panel (View > Output > Aegis Scanner)
2. Review the Aegis Platform documentation
3. Contact Pegasys AI support

Next Steps

• Learn More: Explore Aegis Platform Concepts
• CI/CD Integration: Set up DevOps Integration
• Policy Management: Learn about Managing Policies
• Advanced Usage: Check out the Policy Evaluation API

---

Enjoy development-time policy scanning with Aegis!

---

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