ADWATCH - Active Directory Security Audit Platform

A comprehensive web-based security dashboard for Active Directory environments, designed to integrate with existing CLI audit tools and provide actionable security insights.

🚀 Features

Core Functionality

• Multi-user Authentication: Secure role-based access control (Admin, Analyst, Viewer)
• JSON Upload & Processing: Parse and analyze CLI audit tool output
• Interactive Dashboards: Real-time security metrics and threat analysis
• Professional Reporting: Export reports in JSON, HTML, and PDF formats
• Remediation Scripts: Auto-generate PowerShell and Bash scripts
• SIEM Integration: RESTful APIs for Grafana, Splunk, and ELK Stack
• Audit History: Complete versioning and tracking system

Security Features

• Role-based Permissions: Granular access control system
• Secure Session Management: JWT-based authentication
• Data Encryption: Secure handling of sensitive AD data
• Audit Logging: Complete activity tracking
• Rate Limiting: API protection against abuse

Dashboard Components

• Security Overview: Overall security score and key metrics
• Threat Analysis: Categorized threats with severity indicators
• User Risk Matrix: Risk-based user categorization
• GPO Analysis: Group Policy Object security assessment
• Network Topology: Infrastructure visualization
• Compliance Reporting: Standards compliance tracking

🛠️ Technology Stack

• Frontend: Next.js 14, React, TypeScript, TailwindCSS
• Backend: Next.js API Routes, Node.js
• Database: SQLite with Drizzle ORM
• Authentication: JWT with secure session management
• UI Components: shadcn/ui with custom dark theme
• Deployment: Docker with Nginx reverse proxy

📋 Prerequisites

• Node.js 18+
• npm, yarn, or pnpm
• Docker and Docker Compose (for containerized deployment)
• Active Directory environment with CLI audit tool

🚀 Quick Start

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd adwatch

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install

3. Set up environment variables

   cp .env.example .env.local

   Configure the following variables:

   JWT_SECRET=your-secure-jwt-secret-here
   NODE_ENV=development

4. Initialize the database

   npm run db:generate
   npm run db:push

5. Start the development server

   npm run dev

6. Access the application

   • Open http://localhost:3000
   • Register your first admin account

Production Deployment with Docker

1. Clone and configure

   git clone <repository-url>
   cd adwatch

2. Create environment file

   cp .env.example .env

   Update production values:

   JWT_SECRET=your-production-jwt-secret
   NODE_ENV=production

3. Deploy with Docker Compose

   # Basic deployment
   docker-compose up -d
   
   # Production deployment with SSL and backups
   docker-compose --profile production up -d

4. Access the application

   • HTTP: http://localhost:3000
   • HTTPS: https://localhost (with production profile)

🔧 Configuration

Environment Variables

Variable	Description	Default	Required
JWT_SECRET	Secret key for JWT token signing	adwatch-dev-secret	Yes
NODE_ENV	Environment mode	development	No
DATABASE_URL	Database connection string	file:./data/adwatch.db	No

User Roles

Role	Permissions
Admin	Full system access, user management, all features
Analyst	Upload reports, generate scripts, export data
Viewer	Read-only access to dashboards and reports

📊 API Documentation

Authentication Endpoints

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user

Audit Management

• POST /api/audit/upload - Upload audit report
• GET /api/audit/history - Get audit history
• DELETE /api/audit/history - Delete audit report

Reporting

• POST /api/reports/generate - Generate security report
• POST /api/remediation/generate - Generate remediation script

SIEM Integration

• GET /api/siem/endpoints - SIEM data endpoints
  • Query parameters: endpoint, format, timeRange
  • Supported endpoints: metrics, threats, alerts, users, health

Admin Management

• GET /api/admin/users - List users (Admin only)
• PUT /api/admin/users - Update user (Admin only)
• DELETE /api/admin/users - Delete user (Admin only)

🔒 Security Considerations

Production Security Checklist

• Change default JWT secret
• Enable HTTPS with valid SSL certificates
• Configure rate limiting
• Set up database backups
• Enable audit logging
• Configure firewall rules
• Regular security updates

Data Protection

• All sensitive data is encrypted at rest
• JWT tokens have configurable expiration
• Session management with secure cookies
• Input validation and sanitization
• SQL injection protection via ORM

🐳 Docker Deployment

Services

• adwatch: Main application container
• nginx: Reverse proxy with SSL termination
• backup: Automated database backup service

Volumes

• adwatch_data: Database storage
• adwatch_uploads: File uploads
• adwatch_backups: Database backups
• adwatch_logs: Nginx logs

Health Checks

The application includes comprehensive health checks:

• Database connectivity
• Memory usage monitoring
• Uptime tracking
• API endpoint validation

🔧 Maintenance

Database Backups

Automated daily backups are configured in the Docker setup:

# Manual backup
docker exec adwatch-app cp /app/data/adwatch.db /backups/manual-backup-$(date +%Y%m%d).db

# Restore from backup
docker exec adwatch-app cp /backups/backup-file.db /app/data/adwatch.db

Log Management

# View application logs
docker logs adwatch-app

# View nginx logs
docker logs adwatch-nginx

# Follow logs in real-time
docker logs -f adwatch-app

Updates

# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose build --no-cache
docker-compose up -d

🤝 Integration Guide

CLI Tool Integration

1. Configure your AD audit CLI tool to output JSON format
2. Use the /api/audit/upload endpoint to submit reports
3. Monitor processing status via the dashboard
4. Generate remediation scripts based on findings

SIEM Integration Examples

Grafana Dashboard

{
  "targets": [
    {
      "url": "https://adwatch.company.com/api/siem/endpoints?endpoint=metrics",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  ]
}

Splunk Data Input

curl -H "X-API-Key: your-api-key" \
     "https://adwatch.company.com/api/siem/endpoints?endpoint=alerts&format=json" \
     | splunk add oneshot

📈 Monitoring

Key Metrics

• Security score trends
• Threat detection rates
• User risk distribution
• System performance metrics
• API usage statistics

Alerting

Configure alerts for:

• Critical security threats
• Failed audit uploads
• System health issues
• Unusual user activity

🆘 Troubleshooting

Common Issues

1. Database Connection Failed

   • Check file permissions on data directory
   • Verify SQLite installation
   • Check disk space

2. Authentication Issues

   • Verify JWT_SECRET configuration
   • Check session cookie settings
   • Validate user permissions

3. Upload Failures

   • Check file size limits
   • Verify JSON format
   • Check disk space

Debug Mode

Enable debug logging:

NODE_ENV=development
DEBUG=adwatch:*

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For technical support or questions:

• Create an issue in the repository
• Contact your system administrator
• Review the troubleshooting guide

---

ADWATCH - Securing Active Directory environments through comprehensive audit analysis and automated remediation.