aura-security 0.4.0

package/deploy/AWS-DEPLOYMENT.md

@@ -0,0 +1,358 @@
+# AWS Deployment Guide
+
+This guide covers deploying aurasecurity to AWS with a professional setup including:
+- EC2 instance running the application
+- nginx reverse proxy with SSL
+- Domain setup with Route 53
+- Optional: Load balancer for high availability
+
+## Architecture
+
+```
+                    ┌─────────────┐
+                    │   Route 53  │
+                    │  (DNS)      │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │ Application │
+                    │ Load Balancer│ (optional)
+                    └──────┬──────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+        ┌─────▼─────┐┌─────▼─────┐┌─────▼─────┐
+        │   EC2     ││   EC2     ││   EC2     │
+        │ (nginx +  ││ (nginx +  ││ (nginx +  │
+        │  node)    ││  node)    ││  node)    │
+        └───────────┘└───────────┘└───────────┘
+```
+
+For most use cases, a single EC2 instance is sufficient.
+
+---
+
+## Option 1: Single EC2 Instance (Recommended for Start)
+
+### Step 1: Launch EC2 Instance
+
+1. Go to AWS Console → EC2 → Launch Instance
+2. Choose settings:
+   - **AMI**: Ubuntu 22.04 LTS
+   - **Instance type**: t3.small (2 vCPU, 2GB RAM) or larger
+   - **Key pair**: Create or select existing
+   - **Security Group**: Allow ports 22 (SSH), 80 (HTTP), 443 (HTTPS)
+
+### Step 2: Connect and Install Dependencies
+
+```bash
+# SSH into your instance
+ssh -i your-key.pem ubuntu@<EC2-PUBLIC-IP>
+
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install Node.js 20
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Install nginx
+sudo apt install -y nginx
+
+# Install security tools (optional but recommended)
+sudo apt install -y gitleaks
+sudo snap install trivy
+
+# Install pip and semgrep
+sudo apt install -y python3-pip
+pip3 install semgrep
+
+# Verify installations
+node --version   # Should show v20.x
+nginx -v         # Should show nginx version
+```
+
+### Step 3: Deploy aurasecurity
+
+```bash
+# Create app directory
+sudo mkdir -p /var/www/aura-security
+sudo chown ubuntu:ubuntu /var/www/aura-security
+
+# Install aurasecurity
+cd /var/www/aura-security
+npm install aura-security
+
+# Or clone from GitHub for latest
+git clone https://github.com/aurasecurity/aura-security.git .
+npm install
+npm run build
+```
+
+### Step 4: Create systemd Services
+
+Create the API service:
+
+```bash
+sudo tee /etc/systemd/system/aura-api.service << 'EOF'
+[Unit]
+Description=aurasecurity API Server
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/var/www/aura-security
+ExecStart=/usr/bin/node dist/index.js
+Restart=on-failure
+RestartSec=10
+Environment=NODE_ENV=production
+Environment=AURA_PORT=3000
+Environment=WS_PORT=3001
+
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+Create the visualizer service:
+
+```bash
+sudo tee /etc/systemd/system/aura-visualizer.service << 'EOF'
+[Unit]
+Description=aurasecurity Visualizer
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/var/www/aura-security
+ExecStart=/usr/bin/node dist/serve-visualizer.js
+Restart=on-failure
+RestartSec=10
+Environment=NODE_ENV=production
+Environment=VISUALIZER_PORT=8080
+
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+Enable and start services:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable aura-api aura-visualizer
+sudo systemctl start aura-api aura-visualizer
+
+# Check status
+sudo systemctl status aura-api
+sudo systemctl status aura-visualizer
+```
+
+### Step 5: Configure nginx
+
+```bash
+sudo tee /etc/nginx/sites-available/aura-security << 'EOF'
+server {
+    listen 80;
+    server_name your-domain.com www.your-domain.com;
+
+    # Landing page and static assets
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # API endpoints
+    location /api/ {
+        rewrite ^/api/(.*)$ /$1 break;
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Direct Aura endpoints (info, tools, memory, etc.)
+    location ~ ^/(info|tools|memory|settings|audits|stats|notifications)(/.*)?$ {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # WebSocket for real-time updates
+    location /ws {
+        proxy_pass http://127.0.0.1:3001;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400;
+    }
+}
+EOF
+
+# Enable site
+sudo ln -sf /etc/nginx/sites-available/aura-security /etc/nginx/sites-enabled/
+sudo rm -f /etc/nginx/sites-enabled/default
+
+# Test and reload
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+### Step 6: Add SSL with Let's Encrypt
+
+```bash
+# Install certbot
+sudo apt install -y certbot python3-certbot-nginx
+
+# Get certificate (replace with your domain)
+sudo certbot --nginx -d your-domain.com -d www.your-domain.com
+
+# Auto-renewal is set up automatically
+# Test renewal:
+sudo certbot renew --dry-run
+```
+
+### Step 7: Configure Domain (Route 53)
+
+1. Go to AWS Route 53
+2. Create/select your hosted zone
+3. Create an A record:
+   - Name: `your-domain.com` (or subdomain like `security.your-domain.com`)
+   - Type: A
+   - Value: Your EC2 public IP
+   - TTL: 300
+
+---
+
+## Option 2: Docker Deployment
+
+If you prefer Docker:
+
+```bash
+# Install Docker
+curl -fsSL https://get.docker.com | sudo sh
+sudo usermod -aG docker ubuntu
+
+# Pull and run
+docker pull aurasecurity/aura-security:latest
+docker run -d \
+  --name aura-security \
+  -p 3000:3000 \
+  -p 3001:3001 \
+  -p 8080:8080 \
+  -v aura-data:/app/.aura-security \
+  aurasecurity/aura-security:latest
+```
+
+Then configure nginx as shown above.
+
+---
+
+## Environment Variables
+
+Set these in your systemd service or `.env` file:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AURA_PORT` | 3000 | API server port |
+| `WS_PORT` | 3001 | WebSocket port |
+| `VISUALIZER_PORT` | 8080 | Web UI port |
+| `AWS_ACCESS_KEY_ID` | - | For AWS scanning |
+| `AWS_SECRET_ACCESS_KEY` | - | For AWS scanning |
+| `AWS_DEFAULT_REGION` | us-east-1 | AWS region |
+
+---
+
+## Security Recommendations
+
+1. **Use IAM Roles**: Instead of hardcoding AWS credentials, attach an IAM role to your EC2 instance with the permissions needed for scanning.
+
+2. **Security Groups**: Only allow:
+   - Port 22 from your IP only
+   - Ports 80/443 from anywhere
+
+3. **Enable AWS WAF**: If using ALB, add WAF rules for additional protection.
+
+4. **Regular Updates**:
+   ```bash
+   # Set up unattended upgrades
+   sudo apt install -y unattended-upgrades
+   sudo dpkg-reconfigure -plow unattended-upgrades
+   ```
+
+---
+
+## Monitoring
+
+### CloudWatch Logs
+
+```bash
+# Install CloudWatch agent
+wget https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb
+sudo dpkg -i amazon-cloudwatch-agent.deb
+
+# Configure to send logs
+sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
+```
+
+### Health Checks
+
+Add to nginx config:
+
+```nginx
+location /health {
+    proxy_pass http://127.0.0.1:3000/info;
+    access_log off;
+}
+```
+
+---
+
+## Cost Estimate
+
+| Resource | Specification | Monthly Cost (approx) |
+|----------|--------------|----------------------|
+| EC2 t3.small | 2 vCPU, 2GB RAM | ~$15 |
+| EBS | 20GB gp3 | ~$2 |
+| Route 53 | Hosted zone | ~$0.50 |
+| Data transfer | 10GB | ~$1 |
+| **Total** | | **~$20/month** |
+
+For higher traffic, consider t3.medium (~$30/month) or add a load balancer.
+
+---
+
+## Troubleshooting
+
+### Services not starting
+
+```bash
+# Check logs
+sudo journalctl -u aura-api -f
+sudo journalctl -u aura-visualizer -f
+```
+
+### 502 Bad Gateway
+
+```bash
+# Check if services are running
+sudo systemctl status aura-api
+sudo systemctl status aura-visualizer
+
+# Check ports
+sudo netstat -tlnp | grep -E '3000|3001|8080'
+```
+
+### WebSocket not connecting
+
+Make sure your nginx config has the WebSocket upgrade headers and the security group allows port 3001 (or use nginx proxy for all WebSocket traffic).

package/deploy/terraform/main.tf

@@ -0,0 +1,362 @@
+# aurasecurity - AWS Infrastructure
+# Deploy with: terraform init && terraform apply
+
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = var.aws_region
+}
+
+# Variables
+variable "aws_region" {
+  description = "AWS region"
+  default     = "us-east-1"
+}
+
+variable "instance_type" {
+  description = "EC2 instance type"
+  default     = "t3.small"
+}
+
+variable "key_name" {
+  description = "SSH key pair name"
+  type        = string
+}
+
+variable "domain_name" {
+  description = "Domain name for the application (optional)"
+  default     = ""
+}
+
+# Data sources
+data "aws_ami" "ubuntu" {
+  most_recent = true
+  owners      = ["099720109477"] # Canonical
+
+  filter {
+    name   = "name"
+    values = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"]
+  }
+
+  filter {
+    name   = "virtualization-type"
+    values = ["hvm"]
+  }
+}
+
+data "aws_availability_zones" "available" {
+  state = "available"
+}
+
+# VPC
+resource "aws_vpc" "main" {
+  cidr_block           = "10.0.0.0/16"
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = {
+    Name = "aura-security-vpc"
+  }
+}
+
+resource "aws_subnet" "public" {
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = "10.0.1.0/24"
+  availability_zone       = data.aws_availability_zones.available.names[0]
+  map_public_ip_on_launch = true
+
+  tags = {
+    Name = "aura-security-public"
+  }
+}
+
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+
+  tags = {
+    Name = "aura-security-igw"
+  }
+}
+
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block = "0.0.0.0/0"
+    gateway_id = aws_internet_gateway.main.id
+  }
+
+  tags = {
+    Name = "aura-security-public-rt"
+  }
+}
+
+resource "aws_route_table_association" "public" {
+  subnet_id      = aws_subnet.public.id
+  route_table_id = aws_route_table.public.id
+}
+
+# Security Group
+resource "aws_security_group" "aura_security" {
+  name        = "aura-security-sg"
+  description = "Security group for aurasecurity"
+  vpc_id      = aws_vpc.main.id
+
+  # SSH
+  ingress {
+    from_port   = 22
+    to_port     = 22
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"] # Restrict to your IP in production
+    description = "SSH access"
+  }
+
+  # HTTP
+  ingress {
+    from_port   = 80
+    to_port     = 80
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+    description = "HTTP access"
+  }
+
+  # HTTPS
+  ingress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+    description = "HTTPS access"
+  }
+
+  # All outbound
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  tags = {
+    Name = "aura-security-sg"
+  }
+}
+
+# IAM Role for EC2 (for AWS scanning)
+resource "aws_iam_role" "aura_security" {
+  name = "aura-security-ec2-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "sts:AssumeRole"
+        Effect = "Allow"
+        Principal = {
+          Service = "ec2.amazonaws.com"
+        }
+      }
+    ]
+  })
+}
+
+# IAM Policy for security scanning (read-only)
+resource "aws_iam_role_policy" "aura_security_scan" {
+  name = "aura-security-scan-policy"
+  role = aws_iam_role.aura_security.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "iam:List*",
+          "iam:Get*",
+          "s3:List*",
+          "s3:GetBucket*",
+          "s3:GetEncryptionConfiguration",
+          "ec2:Describe*",
+          "lambda:List*",
+          "lambda:GetFunction*",
+          "rds:Describe*"
+        ]
+        Resource = "*"
+      }
+    ]
+  })
+}
+
+resource "aws_iam_instance_profile" "aura_security" {
+  name = "aura-security-instance-profile"
+  role = aws_iam_role.aura_security.name
+}
+
+# EC2 Instance
+resource "aws_instance" "aura_security" {
+  ami                    = data.aws_ami.ubuntu.id
+  instance_type          = var.instance_type
+  key_name               = var.key_name
+  subnet_id              = aws_subnet.public.id
+  vpc_security_group_ids = [aws_security_group.aura_security.id]
+  iam_instance_profile   = aws_iam_instance_profile.aura_security.name
+
+  root_block_device {
+    volume_size = 20
+    volume_type = "gp3"
+  }
+
+  user_data = <<-EOF
+    #!/bin/bash
+    set -e
+
+    # Update system
+    apt-get update
+    apt-get upgrade -y
+
+    # Install Node.js 20
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+    apt-get install -y nodejs
+
+    # Install nginx
+    apt-get install -y nginx
+
+    # Install security tools
+    apt-get install -y gitleaks python3-pip
+    snap install trivy
+    pip3 install semgrep
+
+    # Create app directory
+    mkdir -p /var/www/aura-security
+    cd /var/www/aura-security
+
+    # Install aurasecurity
+    npm install aura-security
+
+    # Create systemd services
+    cat > /etc/systemd/system/slop-api.service << 'SVCEOF'
+    [Unit]
+    Description=aurasecurity API Server
+    After=network.target
+
+    [Service]
+    Type=simple
+    User=root
+    WorkingDirectory=/var/www/aura-security
+    ExecStart=/usr/bin/npx aura-security serve
+    Restart=on-failure
+    RestartSec=10
+    Environment=NODE_ENV=production
+
+    [Install]
+    WantedBy=multi-user.target
+    SVCEOF
+
+    cat > /etc/systemd/system/slop-visualizer.service << 'SVCEOF'
+    [Unit]
+    Description=aurasecurity Visualizer
+    After=network.target
+
+    [Service]
+    Type=simple
+    User=root
+    WorkingDirectory=/var/www/aura-security
+    ExecStart=/usr/bin/npx aura-security visualizer
+    Restart=on-failure
+    RestartSec=10
+    Environment=NODE_ENV=production
+
+    [Install]
+    WantedBy=multi-user.target
+    SVCEOF
+
+    # Enable and start services
+    systemctl daemon-reload
+    systemctl enable slop-api slop-visualizer
+    systemctl start slop-api slop-visualizer
+
+    # Configure nginx
+    cat > /etc/nginx/sites-available/aura-security << 'NGINXEOF'
+    server {
+        listen 80;
+        server_name _;
+
+        location / {
+            proxy_pass http://127.0.0.1:8080;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        location ~ ^/(info|tools|memory|settings|audits|stats|notifications)(/.*)?$ {
+            proxy_pass http://127.0.0.1:3000;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+        }
+
+        location /ws {
+            proxy_pass http://127.0.0.1:3001;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_read_timeout 86400;
+        }
+    }
+    NGINXEOF
+
+    ln -sf /etc/nginx/sites-available/aura-security /etc/nginx/sites-enabled/
+    rm -f /etc/nginx/sites-enabled/default
+    nginx -t && systemctl reload nginx
+  EOF
+
+  tags = {
+    Name = "aura-security"
+  }
+}
+
+# Elastic IP (optional, for stable IP)
+resource "aws_eip" "aura_security" {
+  instance = aws_instance.aura_security.id
+  domain   = "vpc"
+
+  tags = {
+    Name = "aura-security-eip"
+  }
+}
+
+# Outputs
+output "public_ip" {
+  description = "Public IP address"
+  value       = aws_eip.aura_security.public_ip
+}
+
+output "public_dns" {
+  description = "Public DNS name"
+  value       = aws_instance.aura_security.public_dns
+}
+
+output "landing_url" {
+  description = "Landing page URL"
+  value       = "http://${aws_eip.aura_security.public_ip}"
+}
+
+output "dashboard_url" {
+  description = "Dashboard URL"
+  value       = "http://${aws_eip.aura_security.public_ip}/app"
+}
+
+output "ssh_command" {
+  description = "SSH command to connect"
+  value       = "ssh -i ${var.key_name}.pem ubuntu@${aws_eip.aura_security.public_ip}"
+}

package/deploy/terraform/terraform.tfvars.example

@@ -0,0 +1,6 @@
+# Copy this file to terraform.tfvars and fill in your values
+
+aws_region    = "us-east-1"
+instance_type = "t3.small"
+key_name      = "your-ssh-key-name"  # Name of your EC2 key pair
+domain_name   = ""                    # Optional: your domain name