aurasecurity

A deterministic security auditing engine with an optional AI advisory layer.

aurasecurity can be run as a CLI, a CI step, or a long-running service. The AI does not make enforcement decisions—all security findings come from deterministic scanners (Gitleaks, Trivy, Semgrep, etc.) with reproducible results.

Built on the Aura framework, it provides automated security analysis for code repositories and AWS infrastructure with a 3D visualization control plane.

Features

• Multi-Scanner Integration - Gitleaks, Trivy, Semgrep, npm audit
• AWS Infrastructure Scanning - IAM, S3, EC2, Lambda, RDS security checks
• Real-time WebSocket Updates - Instant notifications when scans complete
• 3D Visualization - Interactive Three.js control plane
• Notifications - Slack, Discord, and custom webhook integrations
• Persistent Storage - SQLite database for audit history
• Docker Ready - Full containerization with security tools included
• CI/CD Pipeline - GitHub Actions for automated testing and publishing

Table of Contents

• Installation
• Quick Start
• CLI Commands
• API Endpoints
• Usage Examples
• Security Scanning Tools
• AWS Scanning
• Docker Deployment
• Environment Variables
• 3D Visualizer Features
• Development
• Contributing
• License

Installation

Prerequisites

• Node.js 18.x or higher
• npm 8.x or higher
• Git (for cloning the repository)

Option 1: Install via npm (Recommended)

npm install -g aura-security

# Check installed tools
aura-security doctor

After installation, you can use the aura-security command directly:

aura-security --help

Option 2: Clone from GitHub

# Step 1: Clone the repository
git clone https://github.com/aurasecurityio/aura-security.git

# Step 2: Navigate to the project directory
cd aura-security

# Step 3: Install dependencies
npm install

# Step 4: Build the TypeScript code
npm run build

# Step 5: Verify installation
npm start -- --help

Option 3: Run with Docker

# Using Docker Compose (recommended)
docker-compose up -d

# Or build and run manually
docker build -t aura-security .
docker run -p 3000:3000 -p 3001:3001 -p 8080:8080 aura-security

Quick Start

Running the Full Stack

Terminal 1 - Start the Aura API Server:

npm start
# Server starts on http://127.0.0.1:3000
# WebSocket on ws://127.0.0.1:3001

Terminal 2 - Start the 3D Visualizer:

npm run visualizer
# Visualizer starts on http://127.0.0.1:8080

Open your browser: Navigate to http://127.0.0.1:8080 to access the 3D control plane.

Quick Test

Run a scan on a local directory:

# Via CLI
aura-security scan ./my-project

# Or via API
curl -X POST http://127.0.0.1:3000/tools \
  -H "Content-Type: application/json" \
  -d '{"tool":"scan-local","arguments":{"targetPath":"./my-project"}}'

One-Command Development Mode

# Start both server and visualizer together
npm run full

CLI Commands

# Initialize configuration
aura-security init [path]

# Scan local directory
aura-security scan <path>

# Scan AWS infrastructure
aura-security aws
aura-security aws --region us-west-2 -s iam,s3,ec2

# Start Aura server
aura-security serve

# Start 3D visualizer
aura-security visualizer

Architecture

aura-security/
├── src/
│   ├── index.ts              # Main entry + Aura server
│   ├── cli.ts                # CLI commands
│   ├── serve-visualizer.ts   # 3D web UI server
│   ├── auditor/              # Core audit logic
│   ├── client/               # High-level SDK
│   ├── database/             # SQLite persistence
│   ├── integrations/         # External connectors
│   │   ├── aws-scanner.ts    # AWS security scanning
│   │   ├── local-scanner.ts  # Local repo scanning
│   │   ├── notifications.ts  # Slack/Discord/webhooks
│   │   └── ...
│   ├── websocket/            # Real-time updates
│   └── aura/                 # Aura protocol impl
├── visualizer/               # 3D Web UI (Three.js)
├── Dockerfile                # Docker build
├── docker-compose.yml        # Docker Compose
└── .github/workflows/        # CI/CD pipeline

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /info | GET | Server information | | /tools | GET | List available tools | | /tools | POST | Execute a tool (scan, audit) | | /memory | GET | List/retrieve from memory | | /memory | POST | Store data in memory | | /settings | GET | Get all settings | | /settings | POST | Save settings | | /audits | GET | List audit history | | /audits/:id | GET | Get audit details | | /audits/:id | DELETE | Delete an audit | | /stats | GET | Audit statistics | | /notifications | GET | Notification history | | /notifications/test | POST | Test notification channel | | /notifications/send | POST | Send notification |

WebSocket

Connect to ws://127.0.0.1:3001 for real-time updates:

const ws = new WebSocket('ws://127.0.0.1:3001');
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type: 'audit_started', 'audit_completed', 'finding', 'settings_changed'
};

Usage Examples

Scan Local Directory

# Via CLI
aura-security scan ./my-project

# Via API
curl -X POST http://127.0.0.1:3000/tools \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "scan-local",
    "arguments": {
      "targetPath": "/path/to/project"
    }
  }'

Scan AWS Infrastructure

# Via CLI
aura-security aws --region us-east-1 -s iam,s3,ec2

# Via API (configure in Settings UI first)
curl -X POST http://127.0.0.1:3000/tools \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "scan-aws",
    "arguments": {
      "region": "us-east-1",
      "services": ["iam", "s3", "ec2"]
    }
  }'

Configure Notifications

Use the Settings panel in the 3D visualizer or via API:

curl -X POST http://127.0.0.1:3000/settings \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "notifications.slack.enabled": "true",
      "notifications.slack.webhookUrl": "https://hooks.slack.com/services/..."
    }
  }'

Use the Client SDK

import { AuditClient, createPullRequestEvent } from 'aura-security';

const client = new AuditClient({
  serverUrl: 'http://127.0.0.1:3000'
});

// Check server health
const healthy = await client.isHealthy();

// Run an audit
const result = await client.audit({
  changeEvent: createPullRequestEvent(
    'acme/webapp',
    'abc123...',
    ['src/auth/login.ts'],
    '+const API_KEY = "secret";',
    'staging'
  ),
  evidenceBundle: { vuln_scan: 'critical: 1' },
  policyContext: {
    critical_assets: ['auth', 'billing'],
    risk_tolerance: 'low'
  }
});

console.log(result.output?.agent_state); // 'blocked', 'escalated', etc.

Security Scanning Tools

The scanner integrates with these security tools when available:

| Tool | Purpose | Install | |------|---------|---------| | gitleaks | Secrets detection | winget install gitleaks | | trivy | Vulnerability scanning | winget install trivy | | semgrep | SAST analysis | pip install semgrep | | npm audit | NPM vulnerabilities | Built into npm |

Falls back to regex patterns if tools aren't installed.

AWS Scanning

Scans for security misconfigurations:

• IAM: Overly permissive policies, unused credentials, MFA status
• S3: Public buckets, missing encryption, insecure ACLs
• EC2: Open security groups, public IPs, unencrypted volumes
• Lambda: Overly permissive roles, exposed environment variables
• RDS: Public accessibility, encryption status, backup config

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t aura-security .
docker run -p 3000:3000 -p 3001:3001 -p 8080:8080 aura-security

# With AWS credentials
docker run -p 3000:3000 -p 3001:3001 -p 8080:8080 \
  -e AWS_ACCESS_KEY_ID=xxx \
  -e AWS_SECRET_ACCESS_KEY=xxx \
  -e AWS_DEFAULT_REGION=us-east-1 \
  aura-security

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | AURA_PORT | 3000 | Aura HTTP server port | | WS_PORT | 3001 | WebSocket server port | | VISUALIZER_PORT | 8080 | 3D visualizer web server port | | AURA_BUS_URL | - | External Aura bus URL (optional) | | AWS_DEFAULT_REGION | us-east-1 | AWS region for scanning |

3D Visualizer Features

The web-based 3D control plane provides:

• Real-time agent state visualization
• Interactive Three.js scene with orbit controls
• Module management (add/remove/configure)
• Audit history browser with click-to-view details
• Settings panel for AWS/Slack/Discord configuration
• Live WebSocket updates (no polling delay)
• Quick-action presets for testing

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Run both server and visualizer
npm run full

# Run tests
npm test

Publishing

# npm
npm login
npm publish --access public

# Docker Hub
docker build -t yourusername/aura-security .
docker push yourusername/aura-security

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

Troubleshooting

Common Issues

Port already in use:

# Check what's using port 3000
netstat -ano | findstr :3000  # Windows
lsof -i :3000                 # macOS/Linux

# Use a different port
AURA_PORT=3001 npm start

Security tools not found: The scanner will fall back to regex patterns if tools aren't installed. For best results, install:

# Windows
winget install gitleaks
winget install trivy

# macOS
brew install gitleaks
brew install trivy

# Linux
# See respective tool documentation for installation

WebSocket connection failed: Ensure the WebSocket server is running on port 3001. Check browser console for errors.

Database errors: The SQLite database is stored in .aura-security/auditor.db. To reset:

rm -rf .aura-security/
npm start  # Will recreate the database

Getting Help

• Check the Issue Tracker for known issues
• Open a new issue with your error message and environment details

License

MIT - See LICENSE for details.

Links

• GitHub Repository
• npm Package
• Issue Tracker
• Changelog