Exfil-Sentry: VNC Data Exfiltration Detection and Prevention System

Exfil-Sentry is a comprehensive, full-stack cybersecurity solution designed to simulate, detect, and prevent VNC-based data exfiltration attacks. It provides real-time monitoring, automated detection, and intelligent response capabilities for securing Virtual Network Computing (VNC) environments.

This system was developed for the Smart India Hackathon 2025 (Problem Statement #25230, National Technical Research Organisation - NTRO).

---

Table of Contents

• Features
• Architecture
• Quick Start
• USING SCRIPTS
• Access Points and Credentials
• The Attack-Detection-Prevention Loop
• Project Structure
• API Endpoints (Selected)
• Development Setup
• Testing
• Docker Deployment
• Configuration
• Firewall Integration
• Monitoring and Alerting
• Security Considerations
• Testing the System
• Troubleshooting
• Database Schema
• Contributing
• Acknowledgments
• License
• Support

---

Features

Exfil-Sentry provides a robust defense system with the following capabilities:

Core Capabilities

• Real-time Traffic Monitoring: Capture and analyze VNC traffic using zeek/tcpdump/Tshark/Zeek.
• Rule-based Detection Engine: Configurable detection rules for various attack patterns, including large data transfers, suspicious payloads, and anomalous connection frequency.
• Automated Firewall Enforcement: Dynamic iptables/nftables rule management for host-level enforcement.
• Interactive Web Dashboard: A React-based interface for monitoring, alert management, and attack orchestration.
• VNC Attack Simulation: Built-in tools to simulate VNC attack scenarios like clipboard exfiltration, file transfer, and screen capture for controlled testing.
• Comprehensive Audit Logging: All system and user actions are recorded in PostgreSQL.

---

Architecture

Exfil-Sentry employs a 7-container microservices architecture:

• Frontend (React): Web dashboard and user interface.
• Backend (FastAPI): REST API, authentication, orchestration, and firewall control.
• Database (PostgreSQL): Persistent storage for users, alerts, rules, and audit logs.
• Detector (Zeek/TcpDump): Network traffic capture and detection rules engine.
• Attacker: VNC attack simulator for exercising detection rules.
• Victim-TigerVNC: TigerVNC server used as a test target (port 5900).
• Victim-RealVNC: RealVNC server used as a test target (port 5901).

The system supports host firewall integration and utilizes isolated networks for VNC test containers.

---

Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.11+ (for backend and detector development)
• Node.js 18+ (for frontend development)
• Recommended: 8GB RAM (16GB preferred), 10GB free disk space.

Clone and Start

1. Clone the repository:

   git clone https://github.com/Anorak001/Exfil-Sentry.git
   cd Exfil-Sentry

2. Start all services with Docker Compose:

   docker compose up -d

3. Alternatively, use the master setup script:

Platform	Command
Windows (PowerShell)	.\scripts\setup.ps1
Linux / macOS (Bash)	chmod +x scripts/setup.sh then ./scripts/setup.sh

The setup script performs prerequisite checks, builds containers, starts services, initializes the database, configures VNC servers, and verifies deployment.

Access after Setup

• Web Dashboard: http://localhost:3000
• Backend API Documentation (Swagger): http://localhost:8000/docs

Default Test Accounts (Local Only)

• Admin: admin / admin123
• Analyst: analyst / analyst123

---

Using scripts:

Using Setup.ps1:

.\scripts\setup.ps1

Using rebuild.ps1:

# Fast rebuild (reuses detector/VNC cache)
.\scripts\rebuild.ps1

# Rebuild only frontend
.\scripts\rebuild.ps1 -Service frontend

# Full rebuild including detector/VNC
.\scripts\rebuild.ps1 -All

# Rebuild detector specifically
.\scripts\rebuild.ps1 -Service detector

# Force fresh build without cache
.\scripts\rebuild.ps1 -NoCache

Access Points and Credentials

The project services use the following common ports in a local environment:

Service	URL	Default Credentials (Local Testing)
Web Dashboard	http://localhost:3000	admin/admin123 or analyst/analyst123
API Documentation	http://localhost:8000/docs	Requires login
Attack Simulator	http://localhost:8001	-
TigerVNC Server	localhost:5900	VNC: vncpass, Linux: linux123
RealVNC Server	localhost:5901	VNC: vncpass, Linux: linux123
Admin User (sudo)	Both containers	Username: admin, Password: admin123
PostgreSQL	localhost:5432	exfilsentry/password
Adminer	http://localhost:8080	exfilsentry/password

---

The Attack-Detection-Prevention Loop

The system provides a clear cycle for defensive operations:

1. Attack Simulation: Frontend triggers POST /api/attack/start $\to$ Backend $\to$ Attacker Container launches VNC attack on Victim Container.
2. Detection: Detector Container (zeek/tcpdump) monitors traffic $\to$ Detects attack pattern $\to$ Writes Alert to Database.
3. Alert Display: Frontend polls GET /api/alerts (Backend) $\to$ Dashboard displays alert with attacker IP.
4. Prevention: Analyst triggers POST /api/firewall/block (Backend) $\to$ Executes iptables/nftables command $\to$ Blocks attacker IP at host firewall.

---

Project Structure

The high-level layout of the repository is as follows:

Exfil-Sentry/
├── containers/             # All containerized services
│   ├── backend/            # FastAPI control server (API, auth, orchestration)
│   │   ├── api/            # API endpoints and routing
│   │   ├── config/         # Configuration management
│   │   ├── core/           # Database and core utilities
│   │   ├── models/         # Database models
│   │   ├── services/       # Business logic (traffic monitor, VNC manager)
│   │   ├── tests/          # Backend unit and integration tests
│   │   ├── main.py         # FastAPI application entry point
│   │   └── Dockerfile      # Backend container image
│   ├── frontend/           # React dashboard
│   │   ├── src/            # React source code
│   │   │   ├── components/ # Reusable UI components
│   │   │   ├── pages/      # Page components (Dashboard, Login, Firewall, etc.)
│   │   │   ├── services/   # API client services
│   │   │   └── hooks/      # Custom React hooks
│   │   ├── public/         # Static assets
│   │   └── Dockerfile      # Frontend container image
│   ├── detector/           # Network traffic analyzer (Zeek-based)
│   │   ├── detector.py     # Main detection logic
│   │   ├── zeek_logs/      # Zeek analysis scripts and pcap files
│   │   └── Dockerfile      # Detector container image
│   ├── attacker/           # VNC attack simulator
│   │   ├── attacker.py     # Attack orchestration script
│   │   └── Dockerfile      # Attacker container image
│   ├── victim-tigervnc/    # TigerVNC test server (port 5900)
│   │   ├── supervisord.conf
│   │   └── Dockerfile
│   ├── victim-realvnc/     # RealVNC test server (port 5901)
│   │   ├── supervisord.conf
│   │   └── Dockerfile
│   └── database/           # PostgreSQL initialization
│       └── init.sql        # Database schema and seed data
├── scripts/                # Automation scripts
│   ├── setup/              # Modular setup steps (01-06)
│   ├── setup.ps1           # Master setup script (Windows)
│   ├── setup.sh            # Master setup script (Linux/macOS)
│   ├── run.ps1 / run.sh    # Start services
│   ├── stop.ps1 / stop.sh  # Stop services
│   └── rebuild.ps1 / rebuild.sh  # Rebuild containers
├── docs/                   # Additional documentation
│   ├── SETUP.md            # Detailed setup guide
│   ├── DEPLOYMENT.md       # Deployment instructions
│   ├── PROJECT_OVERVIEW.md # Architecture and design
│   └── ...                 # Other documentation files
└── docker-compose.yml      # Container orchestration configuration

---

API Endpoints (Selected)

The full API specification is available via Swagger UI (http://localhost:8000/docs) and ReDoc (http://localhost:8000/redoc).

Authentication

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/logout - User logout

Attack Simulation

• POST /api/v1/attack/start - Launch attack
• GET /api/v1/attack/types - List attack types
• GET /api/v1/attack/history - View attack history

Security Alerts

• GET /api/v1/alerts - List alerts
• GET /api/v1/alerts/{id} - Get alert details
• PUT /api/v1/alerts/{id} - Update alert status
• GET /api/v1/alerts/stats/summary - Alert statistics

Firewall

• POST /api/v1/firewall/block - Block IP address (Host-level enforcement)
• POST /api/v1/firewall/unblock - Unblock IP address
• GET /api/v1/firewall/blocked-ips - List blocked IPs
• GET /api/v1/firewall/rules - List firewall rules

---

Development Setup

To run components locally without Docker:

Backend Development

cd containers/backend
# Create and activate virtual environment
python -m venv venv
# Linux/macOS
source venv/bin/activate
# Windows PowerShell
# venv\Scripts\Activate.ps1
pip install -r requirements.txt
# Start development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Frontend Development

cd containers/frontend
npm install
npm start

Database Setup

# Start only database service
docker compose up -d database
# The database is automatically initialized with the schema from containers/database/init.sql

---

Testing

Backend Tests

cd containers/backend
pip install pytest pytest-asyncio pytest-cov
# Run tests
pytest tests/ -v
# Run tests with coverage
pytest tests/ --cov=. --cov-report=html

Frontend Tests

cd containers/frontend
# Run tests
npm test
# Run tests with coverage
npm test -- --coverage

---

Docker Deployment

Development Deployment

docker compose build
docker compose up -d

Production Deployment

For production deployment, update environment variables in docker-compose.yml:

# Build production images
docker compose build

# Start services
docker compose up -d

# View logs
docker compose logs -f

Container Management Useful Commands

docker compose ps
docker compose logs -f <service_name>
docker compose down

---

Configuration

Configuration is primarily managed using environment variables (.env files).

Environment Variables

Component	Example Key Variables
Backend	DATABASE_URL, ATTACKER_URL, SECRET_KEY, NETWORK_INTERFACE, DEBUG
Frontend	REACT_APP_API_URL, REACT_APP_APP_NAME
Detector	DATABASE_URL, NETWORK_INTERFACE

Detection Rules

Detection rules can be configured via the web interface or by direct database modification.

Example Rule JSON:

{
  "packet_size_gt": 8192,
  "suspicious_payload": true,
  "connection_frequency_gt": 10
}

---

Firewall Integration

Exfil-Sentry supports automated firewall rule management for blocking suspicious IP addresses at the host level.

# Example iptables command
iptables -A INPUT -s [suspicious_ip] -j DROP

# Example nftables command
nft add rule inet filter input ip saddr [suspicious_ip] drop

---

Monitoring and Alerting

Built-in Metrics

• Packet capture rates
• Detection rule performance
• System resource usage
• Alert generation statistics

Alert Types

• Exfiltration Detected - Large data transfers identified.
• Suspicious Traffic - Anomalous VNC patterns.
• Behavioral Anomaly - Unusual access patterns.
• Rule Triggered - Custom detection rules activated.

---

Security Considerations

• Network Isolation: VNC containers run in isolated networks for secure testing.
• Encrypted Communication: Use HTTPS for all API endpoints in production.
• Role-based Access Control: Supports Admin and Analyst roles.
• Audit Logging: Comprehensive activity tracking.
• Data Protection: Sensitive data encryption at rest.

---

Testing the System

1. Launch an Attack

Via API:

curl -X POST http://localhost:8000/api/v1/attack/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"attack_type":"clipboard_exfil", "target":"tigervnc"}'

Via Dashboard:

1. Login to http://localhost:3000.
2. Go to "Attack Simulation".
3. Select attack type and target, and click "Launch Attack".

2. Monitor Detection

# View detector logs
docker compose logs -f detector
# Check alerts via API
curl http://localhost:8000/api/v1/alerts -H "Authorization: Bearer <token>"
# View in Dashboard: Navigate to "Security Alerts" section.

3. Block Attacker

Via API:

curl -X POST "http://localhost:8000/api/v1/firewall/block?ip_address=<attacker_ip>" \
  -H "Authorization: Bearer <token>"

Via Dashboard:

1. Go to "Security Alerts".
2. Click on an alert to view details.
3. Click "Block IP".

---

Troubleshooting

Common Issues

• Docker Permission Issues (Linux): Add user to docker group: sudo usermod -aG docker $USER (requires log out/in).
• Port Conflicts: Check port usage: netstat -tlnp | grep :8000 (stop conflicting services, e.g., Apache/Nginx).
• Database Connection Issues: Check PostgreSQL logs: docker compose logs database. To reset the database: docker compose down -v then docker compose up -d.
• Frontend Build Errors: Ensure node_modules is properly installed: cd containers/frontend && npm install.
• Detector Not Running: Check network interface configuration and ensure required capabilities are granted to the container.

Performance Optimization

• Increase Docker resource limits.
• Use SSD storage for database operations.
• Monitor system resources during packet capture.

---

Database Schema

Key tables maintained in PostgreSQL:

• users - User accounts and authentication
• security_alerts - Detected threats and incidents
• vnc_sessions - VNC session tracking
• firewall_rules - Firewall configuration
• detection_rules - Detection patterns
• audit_logs - System activity logs

---

Contributing

This project is developed for the Smart India Hackathon 2025. For collaboration:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Commit your changes: git commit -m 'Add amazing feature'.
4. Push to the branch and open a Pull Request.

Development Guidelines

• Follow PEP 8 for Python code.
• Use ESLint configuration for JavaScript/React.
• Write comprehensive tests for new features.
• Update documentation for API changes.
• Follow conventional commit messages.

---

Acknowledgments

This project utilizes the following technologies:

• TigerVNC - Open source VNC implementation
• FastAPI - Modern Python web framework
• React - Frontend framework
• Zeek - Network security monitoring and packet analysis
• PostgreSQL - Relational database system
• Docker - Containerization platform
• Material-UI - React component library

---

License

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

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@exfilsentry.com

---