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

$3

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

$3

``bash
npm install -g aura-security

Check installed tools


aura-security doctor
`

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

`bash
aura-security --help
`

$3

`bash


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
`

$3

`bash


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

$3

Terminal 1 - Start the Aura API Server:
`bash
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:
`bash
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.

$3

Run a scan on a local directory:
`bash


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"}}'
`

$3

`bash


Start both server and visualizer together


npm run full
`

CLI Commands

`bash


Initialize configuration

aura-security init [path]

Scan local directory

aura-security scan

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 |

$3

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

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

$3

`bash


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"
}
}'
`

$3

`bash


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"]
}
}'
`

$3

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

`bash
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/..."
}
}'
`

$3

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

`bash


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

`bash


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

`bash


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

$3

Port already in use:
`bash


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:
`bash


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:
`bash
rm -rf .aura-security/
npm start # Will recreate the database
``

$3

- 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