.env.example

# Zero-Shield CLI - Local Development Environment Configuration
#
# This configuration is for local development where you need to provide
# AWS credentials explicitly (not inherited from CloudShell).
#
# SETUP INSTRUCTIONS:
# These instructions assume you are in the Zero-Shield CLI repository root directory.
# If you cloned the repository: cd zero-shield-cli
# If you downloaded files individually: create a folder and navigate to it
#
# 1. Ensure you're in the repository root (same directory as zero_shield_cli.py)
# 2. Copy this file to root: cp environments/local/.env.example .env
# 3. Edit the new .env file: nano .env
# 4. Replace the placeholder values below with your actual credentials:
#    - Replace "your_github_token_here" with your actual GitHub token
#    - Replace "AKIAIOSFODNN7EXAMPLE" with your actual AWS access key
#    - Replace "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" with your actual AWS secret key
#    - Replace "us-east-1" with your AWS region (if different)
#    - Replace "sg-0123456789abcdef0" with your quarantine security group ID
# 5. Save and close the file
# 6. Verify: cat .env (should show your actual values, not placeholders)
# 7. Run: python3 zero_shield_cli.py

# =============================================================================
# COMMENTING STRATEGY EXPLAINED
# =============================================================================
#
# REQUIRED VALUES (not commented): Ready to use after you replace placeholders
# - GITHUB_TOKEN=your_github_token_here (replace with actual token)
# - AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE (replace with actual key)
# - AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY (replace with actual secret)
#
# OPTIONAL ALTERNATIVES (commented out): Choose one option, not both
# - Option 1: Standard AWS credentials (above, not commented)
# - Option 2: Temporary credentials (below, commented out - uncomment if using)
#
# This approach makes it clear which values are required vs optional alternatives.
#
# =============================================================================
# REQUIRED CONFIGURATION
# =============================================================================

# GitHub Models API Token (REQUIRED)
# This token is for accessing GitHub's AI Models API (GPT-4o, Llama, etc.)
# This is NOT for repository access - it's for calling AI models hosted by GitHub
# Get this from: https://github.com/settings/tokens
# Required scopes: NONE (create a token with no checkboxes selected)
# The token allows Zero-Shield to call GitHub's LLM inference API
GITHUB_TOKEN=your_github_token_here

# AWS Credentials (REQUIRED for local development)
# Option 1: Use IAM user credentials (recommended for development)
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Option 2: Use temporary credentials (if using assume-role)
# Uncomment these if using temporary credentials instead of Option 1:
# AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
# AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# AWS_SESSION_TOKEN=your_session_token_here

# AWS Region (REQUIRED)
# Choose the region where your AWS resources are located
AWS_DEFAULT_REGION=us-east-1

# =============================================================================
# RECOMMENDED CONFIGURATION
# =============================================================================

# Quarantine Security Group ID (REQUIRED for quarantine functionality)
# Create a restrictive security group for quarantining compromised instances
# Example: aws ec2 create-security-group --group-name ZeroShield-Quarantine --description "Quarantine zone"
QUARANTINE_SG_ID=sg-0123456789abcdef0

# =============================================================================
# OPTIONAL CONFIGURATION
# =============================================================================

# GitHub Models API Base URL (Optional - for custom endpoints)
# Default: https://models.inference.ai.azure.com
# GITHUB_MODELS_URL=https://models.inference.ai.azure.com

# Session Encryption Key Override (Optional)
# By default, GITHUB_TOKEN is used as the encryption key for session files
# Uncomment to use a different key (must be consistent across sessions):
# SESSION_ENCRYPTION_KEY=your_custom_32_character_key_here

# Debug Mode (Optional)
# Uncomment to enable verbose logging:
# DEBUG=true

# AWS Profile (Optional - alternative to access keys)
# If you have AWS CLI profiles configured, you can use them instead:
# AWS_PROFILE=your_aws_profile_name

# =============================================================================
# ZERO-SHIELD WRITE CAPABILITIES
# =============================================================================
#
# Zero-Shield has ONLY 3 write operations (all require HITL confirmation):
#
# 1. QUARANTINE - Moves instance to quarantine security group
#    AWS API: ec2:ModifyInstanceAttribute (changes security groups)
#    Requires: QUARANTINE_SG_ID environment variable
#
# 2. MODIFY_SG - Changes instance security groups
#    AWS API: ec2:ModifyInstanceAttribute (changes security groups)
#
# 3. DEACTIVATE_ACCESS_KEY - Disables IAM access key
#    AWS API: iam:UpdateAccessKey (sets status to 'Inactive')
#    Note: Does NOT delete the key, only deactivates it
#
# All other operations (30+ actions) are READ-ONLY:
# - EC2 describe operations (instances, security groups, VPCs, etc.)
# - IAM list/get operations (users, roles, keys)
# - S3 get operations (bucket policies, ACLs)
# - CloudWatch/CloudTrail read operations
# - Cost Explorer read operations
# - GuardDuty/KMS/WAF read operations
#
# =============================================================================
# REQUIRED AWS IAM PERMISSIONS
# =============================================================================
#
# For FULL functionality (including write operations), use:
# aws-setup/policies/zero-shield-full.json
#
# For READ-ONLY investigation (no write operations), use:
# aws-setup/policies/zero-shield-minimal.json
#
# For STANDARD operations (quarantine but no IAM key deactivation), use:
# aws-setup/policies/zero-shield-standard.json
#
# See aws-setup/IAM_POLICIES.md for detailed permission explanations
#
# =============================================================================
# LOCAL DEVELOPMENT NOTES
# =============================================================================
#
# 1. AWS Credentials: Multiple options available
#    - IAM User Access Keys (recommended for development)
#    - AWS CLI Profiles (aws configure --profile myprofile)
#    - Temporary credentials from assume-role
#    - Environment variables (this file)
#
# 2. Security Considerations:
#    - Never commit .env file to version control (.gitignore protects this)
#    - Use IAM users with minimal required permissions
#    - Consider using temporary credentials for production
#    - Rotate access keys regularly (Zero-Shield can audit key ages)
#    - Test with read-only permissions first (minimal policy)
#
# 3. File Persistence: Local files persist until manually deleted
#    - Session files (session_state.json, session_kg.json) remain
#    - Files are encrypted using your GITHUB_TOKEN
#    - Delete session files if you change GITHUB_TOKEN
#
# 4. Network Requirements:
#    - Internet access for GitHub Models API
#    - AWS API endpoints (usually internet-based)
#    - Consider corporate firewall/proxy settings
#
# =============================================================================
# AWS CREDENTIAL PRIORITY ORDER
# =============================================================================
#
# Zero-Shield (via boto3) checks credentials in this order:
# 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# 2. AWS credentials file (~/.aws/credentials)
# 3. AWS config file (~/.aws/config)
# 4. IAM roles (if running on EC2)
# 5. Container credentials (if running in ECS)
#
# =============================================================================
# QUICK SETUP COMMANDS
# =============================================================================
#
# IMPORTANT: Run these commands from the repository root directory
#
# 1. Navigate to repository root:
#    cd zero-shield-cli
#
# 2. Copy this template to root:
#    cp environments/local/.env.example .env
#
# 3. Edit with your values:
#    nano .env
#
# 4. WHAT TO REPLACE (line by line):
#
#    Line: GITHUB_TOKEN=your_github_token_here
#    Replace with: GITHUB_TOKEN=ghp_YourActualGitHubToken123456789
#    Get from: https://github.com/settings/tokens
#    Purpose: Allows Zero-Shield to call GitHub Models API for LLM inference
#    Scopes: NONE required (create token with no checkboxes selected)
#
#    Line: AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
#    Replace with: AWS_ACCESS_KEY_ID=AKIAIOSFODNN7YOURKEY
#    Get from: AWS Console → IAM → Users → Security credentials
#
#    Line: AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
#    Replace with: AWS_SECRET_ACCESS_KEY=YourActualSecretKey123456789
#    Get from: AWS Console → IAM → Users → Security credentials
#
#    Line: AWS_DEFAULT_REGION=us-east-1
#    Replace with: AWS_DEFAULT_REGION=your-region (e.g., us-west-2, eu-west-1)
#    Use the region where your AWS resources are located
#
#    Line: QUARANTINE_SG_ID=sg-0123456789abcdef0
#    Replace with: QUARANTINE_SG_ID=sg-YourActualSecurityGroupID
#    Create with: aws ec2 create-security-group --group-name ZeroShield-Quarantine --description "Quarantine zone"
#
# 5. Test AWS credentials:
#    aws sts get-caller-identity
#
# 6. Test GitHub token:
#    curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user
#
# 7. Create quarantine security group (if not exists):
#    aws ec2 create-security-group \
#      --group-name ZeroShield-Quarantine \
#      --description "Quarantine zone for compromised instances"
#    # Note the sg-xxxxxxxx ID and update QUARANTINE_SG_ID in .env
#
# 8. Run Zero-Shield:
#    python3 zero_shield_cli.py
#
# NOTE: The .env file will be created in the repository root (same directory as zero_shield_cli.py)
#
# =============================================================================
# ALTERNATIVE: AWS CLI CONFIGURATION
# =============================================================================
#
# Instead of using this .env file for AWS credentials, you can configure
# AWS CLI and leave AWS_* variables commented out:
#
# aws configure
# # OR for named profile:
# aws configure --profile zero-shield
# # Then uncomment and set: AWS_PROFILE=zero-shield
#
# =============================================================================
# TESTING YOUR SETUP
# =============================================================================
#
# Test read-only access:
#   aws ec2 describe-instances --max-items 1
#   aws iam list-users --max-items 1
#
# Test write access (if using standard/full policy):
#   # Don't actually run these - just verify permissions exist
#   aws ec2 modify-instance-attribute --dry-run --instance-id i-test --groups sg-test
#   aws iam update-access-key --dry-run --user-name test --access-key-id AKIA --status Inactive
#