Snap DNS v2.0

A modern, enterprise-ready web-based DNS management interface for BIND9 DNS servers using nsupdate for dynamic DNS updates.

Features

Core Functionality

✅ Full DNS Record Management - Create, edit, delete 11 record types (A, AAAA, CNAME, MX, TXT, SRV, NS, PTR, CAA, SSHFP, SOA)
✅ Atomic Updates - All changes reviewed before application with undo/redo support
✅ Automatic Snapshots - Zone state captured before every change for easy rollback
✅ Server-Side Persistence - Snapshots and configuration stored securely on backend
✅ Import/Export - Snapshot and configuration backup/restore capabilities

Security & Authentication

✅ Session-Based Authentication - Secure HTTP-only cookie sessions
✅ Microsoft 365 SSO - OAuth 2.0 integration with JIT user provisioning
✅ Role-Based Access Control - Admin, Editor, and Viewer roles
✅ Azure AD Role Mapping - Automatic role assignment from Entra ID app roles
✅ Server-Side TSIG Keys - Encrypted key storage (AES-256-CBC)
✅ Audit Logging - Complete history of all DNS and authentication operations

User Experience

✅ Modern React UI - Material-UI components with dark/light themes
✅ Real-Time Validation - Client and server-side DNS record validation
✅ Toast Notifications - Non-intrusive success/error notifications
✅ Advanced Search - Filter and search through DNS records
✅ Responsive Design - Works on desktop and mobile devices
✅ Hot Reload Development - Sub-second iteration during development

Administration

✅ User Management UI - Complete admin interface for user CRUD operations
✅ Audit Log Viewer - Filter, search, and export audit logs (CSV/JSON)
✅ SSO Configuration UI - Configure Microsoft 365 integration from web UI
✅ Webhook Notifications - Slack, Discord, Teams, Mattermost integrations
✅ Teams Adaptive Cards - Rich, mobile-friendly notification cards

Quick Start

Prerequisites

Docker & Docker Compose
BIND9 DNS server with TSIG keys configured
Node.js 18+ (for development)

Development Environment

# Clone repository
git clone https://github.com/ttpears/snap-dns.git
cd snap-dns

# Start test environment (includes BIND9 DNS server)
docker compose -f docker-compose.test.yml up -d

# Access application
# Frontend: http://localhost:3001
# Backend API: http://localhost:3002
# Login: admin / admin (change on first login)

Production Deployment

The production stack is two containers (frontend + backend). Configure once, then start.

1. Create your config from the template and set a session secret:

cp .env.production.example .env
# Edit .env and set at least:
#   SESSION_SECRET      — generate with:  openssl rand -base64 32
#   TSIG_ENCRYPTION_KEY — generate with:  openssl rand -base64 32  (keep it stable)
#   REACT_APP_API_URL / ALLOWED_ORIGINS — how the app is reached (see comments in the file)

2. Start it — pull pre-built images (fastest) or build from source:

# Option A — pre-built images from ghcr.io
docker compose -f docker-compose.prod.yml up -d

# Option B — build the images from source
docker compose -f docker-compose.prod.yml up -d --build

3. Access the UI at http://localhost:3001 (or your FRONTEND_PORT). First login is admin / changeme123 — change it immediately in Settings.

The stack refuses to start if SESSION_SECRET or TSIG_ENCRYPTION_KEY is unset and tells you exactly what to do. Pin a released version by setting IMAGE_TAG in .env (e.g. IMAGE_TAG=2.1.0); defaults to latest.

Behind a reverse proxy (HTTPS, recommended): set REACT_APP_API_URL and ALLOWED_ORIGINS to your HTTPS domains in .env, then either front the published ports with your proxy, or use the built-in Traefik labels — create the network (docker network create proxy), set FQDN and FQDN_API in .env, and uncomment the proxy network + labels in docker-compose.prod.yml.

Updating: docker compose -f docker-compose.prod.yml pull && docker compose -f docker-compose.prod.yml up -d (or re-run with --build for Option B).

Testing

Automated E2E Tests

Comprehensive Playwright test suite covering all DNS operations:

# Run tests in headless mode
./run-tests.sh

# Run with browser visible (for debugging)
./run-tests.sh --headed

# Run with Playwright inspector
./run-tests.sh --debug

Test Coverage:

All 11 DNS record types
CRUD operations (Create, Read, Update, Delete)
Undo/redo functionality
Bulk operations
Zone refresh
~52 test cases

Environment Variables:

TEST_URL=http://localhost:3001        # Test URL
TEST_USERNAME=admin                   # Test user
TEST_PASSWORD=admin                   # Test password (change in production)
TEST_ZONE=test.local                  # Test zone name
TEST_KEY="Test Local Zone Key"       # Test TSIG key name
HEADLESS=true                         # Run headless

See TEST_DOCUMENTATION.md for full testing guide.

Continuous Integration

GitHub Actions automatically runs on every push and pull request:

Integration Tests Workflow (.github/workflows/e2e-tests.yml):

Starts complete Docker test environment (BIND9, Backend, Frontend)
Verifies all services start and respond
Health checks for backend API and frontend
Validates test infrastructure is ready

Lint and Build Workflow (.github/workflows/lint-and-build.yml):

TypeScript type checking (frontend & backend)
Production build verification
Ensures code compiles and builds successfully

Full E2E Tests: The comprehensive Playwright test suite (~52 tests) is run locally via ./run-tests.sh as it requires configured TSIG keys and zone data not available in CI.

View results: Check the Actions tab in GitHub repository

Configuration

Environment Variables

Backend

BACKEND_PORT=3002                    # Server port
BACKEND_HOST=0.0.0.0                 # Server host
ALLOWED_ORIGINS=http://localhost:3001 # CORS origins
FRONTEND_URL=http://localhost:3001   # Frontend URL for SSO
NODE_ENV=production                  # Environment mode
SESSION_SECRET=<random-string>       # Session encryption key

Frontend

REACT_APP_API_URL=http://localhost:3002  # Backend API URL
PUBLIC_URL=/                              # Frontend public URL
WDS_SOCKET_HOST=localhost                 # WebSocket host
WDS_SOCKET_PORT=3001                      # WebSocket port

TSIG Key Setup

TSIG keys are managed through the web UI (Settings → Keys). Keys are encrypted at rest using AES-256-CBC.

Microsoft 365 SSO Setup

Register Azure AD Application (see SSO_SETUP_GUIDE.md)
Configure in Web UI (Settings → SSO):
- Tenant ID, Client ID, Client Secret
Configure App Roles (see ENTRA_ROLE_MAPPING_GUIDE.md)
- admin, editor, viewer

Architecture

Technology Stack

Frontend: React 18.2, Material-UI 5.13, TypeScript 5.7 Backend: Node.js, Express, TypeScript, BIND9 nsupdate/dig Database: SQLite (users/sessions) Auth: bcrypt, MSAL Node Infrastructure: Docker, BIND9, Traefik/Nginx

DNS Operations

Supported Record Types: A, AAAA, CNAME, MX, TXT, SRV, NS, PTR, CAA, SSHFP, SOA

Workflow:

Select Zone & Key
Make Changes (tracked)
Review Changes (with undo/redo)
Apply Changes (atomic via nsupdate)
Auto-Snapshot (zone state saved)
Webhook Notify (optional)

User Roles

Role	Permissions
Admin	Full access - manage users, keys, zones, snapshots, audit logs, SSO config
Editor	Create, modify, delete DNS records and snapshots
Viewer	Read-only access to zones and records

Security Considerations

⚠️ Important Security Notes

✅ Implemented in v2.0:

Server-side TSIG key storage (encrypted)
Session-based authentication (HTTP-only cookies)
Role-based access control
Audit logging (all operations tracked)
SSO integration (Microsoft 365)
Real client IP logging (proxy-aware)

⚠️ Recommended for Production:

Use HTTPS (reverse proxy with SSL)
Configure Azure AD Conditional Access
Enable MFA in Azure AD
Implement rate limiting
Use security headers (helmet.js)
Network segmentation

See CLAUDE.md for detailed security analysis.

Monitoring & Operations

Audit Logs

All operations logged with timestamp, user, client IP, event type, and status.

Access: Settings → Audit Logs (admin-only) Export: CSV or JSON format

Webhook Notifications

Supported Providers: Slack, Discord, Microsoft Teams, Mattermost Triggers: DNS changes, snapshots, auth events, errors

Health Monitoring

# Check backend health
curl http://localhost:3002/api/auth/status

# Check containers
docker compose -f docker-compose.test.yml ps
docker logs snap-dns-test-backend

Development

Frontend Development

npm install
npm start              # Hot reload dev server
npm run build          # Production build

Backend Development

cd backend
npm install
npm run dev            # Auto-reload dev server
npm run build          # Production build
npm start              # Run production

Docker Development

# Hot reload dev stack (local source, no DNS server)
docker compose up -d

# Full test stack incl. BIND9 DNS server
docker compose -f docker-compose.test.yml up -d

# Production images built from source
docker compose -f docker-compose.prod.yml up -d --build

Troubleshooting

Common Issues

Cannot connect to backend

Check CORS configuration (ALLOWED_ORIGINS)
Verify REACT_APP_API_URL in frontend
Check backend logs: docker logs snap-dns-test-backend

TSIG authentication failed

Verify key matches BIND9 configuration
Check key algorithm (usually HMAC-SHA256)
Ensure key has update permissions for zone

Session expires immediately

Check SESSION_SECRET is set
Verify cookies are being set
Check FRONTEND_URL matches actual URL

SSO redirect URI mismatch

Ensure Azure AD redirect URI matches exactly
Check FRONTEND_URL environment variable
Use HTTPS in production (required for SSO)

Zone selector disabled

Ensure selected TSIG key has zones assigned
Check Settings → Keys to assign zones
Admin users have access to all keys

Documentation

CLAUDE.md - Architecture, security analysis
TODO.md - Outstanding tasks
TEST_DOCUMENTATION.md - Testing guide
SSO_SETUP_GUIDE.md - Azure AD setup
ENTRA_ROLE_MAPPING_GUIDE.md - Role configuration

Version History

v2.0.0 - Enterprise Ready

✨ Comprehensive E2E test suite (Playwright)
✨ Microsoft 365 SSO with JIT provisioning
✨ User management UI
✨ Audit log viewer with export
✨ Enhanced Teams Adaptive Cards
✨ Azure AD role mapping
🔒 Server-side TSIG keys (encrypted)
🔒 Session-based authentication
🔒 Role-based access control
🚀 Hot reload development (95% faster)
🚀 Snapshot import/export
🐛 Fixed zone selection persistence
🐛 Fixed snapshot restore
📚 Complete documentation

v1.0.0 - Initial Release

Core DNS record management
Basic authentication
Snapshot system
Docker deployment

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

Support

Issues: GitHub Issues
Documentation: See docs above
Security: Report security issues privately

Built with ❤️ for modern DNS management

Version: 2.0.0 | Status: Production Ready ✅

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
backend		backend
docs		docs
public		public
scripts		scripts
src		src
test		test
tests/e2e		tests/e2e
.dockerignore		.dockerignore
.env.example		.env.example
.env.production.example		.env.production.example
.env.test.example		.env.test.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.test.yml		docker-compose.test.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
run-tests.sh		run-tests.sh
test-setup.sh		test-setup.sh
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation