A secure, modern web interface for managing SSL certificates using the mkcert CLI tool. Generate, download, and manage local development certificates with enterprise-grade security and an intuitive web interface.
- 🔐 SSL Certificate Generation: Create certificates for multiple domains and IP addresses
- 🛡️ Enterprise Security: Command injection protection, path traversal prevention, and comprehensive rate limiting
- 📋 Multiple Formats: Generate PEM, CRT, and PFX (PKCS#12) certificates
- 🔒 Flexible Authentication: Basic auth and enterprise SSO with OpenID Connect
- 📧 Email Notifications: Automated SMTP alerts for expiring certificates
- 📊 Certificate Monitoring: Automatic monitoring with configurable warning periods
- 🏗️ Modular Architecture: Clean, maintainable codebase with utility-based design
- 🌐 HTTPS Support: Auto-generated SSL certificates for secure access
- 📊 Certificate Management: View, download, archive, and restore certificates
- 🎨 Modern UI: Dark/light themes with responsive design
- 🐳 Docker Ready: Complete containerization with docker-compose
- 📈 Monitoring Ready: Standardized logging and structured API responses
Modern web interface showing certificate generation and management features
# Clone and start
git clone https://github.com/jeffcaldwellca/mkcertWeb.git
cd mkcertWeb
docker-compose up -d
# Access at http://localhost:3000# Prerequisites: Node.js 16+, mkcert, OpenSSL
npm install
mkcert -install # First time only
npm startFor detailed setup instructions, see DOCKER.md
# Server Configuration
PORT=3000 # HTTP server port
ENABLE_HTTPS=true # Enable HTTPS server
HTTPS_PORT=3443 # HTTPS server port
# Authentication
ENABLE_AUTH=true # Enable user authentication
AUTH_USERNAME=admin # Username for basic authentication
AUTH_PASSWORD=admin123 # Password for basic authentication
# OpenID Connect SSO (Optional)
ENABLE_OIDC=false # Enable OIDC SSO authentication
OIDC_ISSUER= # OIDC provider URL
OIDC_CLIENT_ID= # OIDC client ID
OIDC_CLIENT_SECRET= # OIDC client secret
# Email Notifications
EMAIL_NOTIFICATIONS_ENABLED=true
SMTP_HOST=smtp.gmail.com # Your SMTP server
SMTP_PORT=587 # SMTP port (587 for TLS, 465 for SSL)
SMTP_SECURE=false # Use SSL (true for port 465)
SMTP_USER=your-email@domain.com # SMTP username
SMTP_PASSWORD=your-app-password # SMTP password
EMAIL_FROM=mkcert@yourcompany.com # From address for notifications
EMAIL_TO=admin@company.com,ops@company.com # Comma-separated recipients
# Certificate Monitoring
CERT_MONITORING_ENABLED=true
CERT_CHECK_INTERVAL=0 8 * * * # Cron schedule (daily at 8 AM)
CERT_WARNING_DAYS=30 # Days before expiry to send warnings
CERT_CRITICAL_DAYS=7 # Days before expiry for critical alertsGmail:
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
# Note: Use App Passwords instead of your regular passwordOutlook/Office 365:
SMTP_HOST=smtp-mail.outlook.com
SMTP_PORT=587
SMTP_SECURE=falseCorporate Exchange:
SMTP_HOST=mail.yourcompany.com
SMTP_PORT=587
SMTP_SECURE=falseFor complete configuration options including rate limiting and advanced settings, see the .env.example file.
- Access: Navigate to
http://localhost:3000 - Login: Use configured credentials (default: admin/admin)
- Generate: Enter domains (one per line) and select format
- Download: Get certificates in PEM, CRT, or PFX format
- Manage: View, archive, or restore certificates
# Generate certificate
curl -X POST http://localhost:3000/api/execute \
-H "Content-Type: application/json" \
-d '{"command":"generate","input":"localhost example.com"}'
# List certificates
curl http://localhost:3000/api/certificates
# Download certificate file
wget http://localhost:3000/download/localhost.pem -O localhost.pem
# Email and monitoring API endpoints
curl http://localhost:3000/api/email/status
curl http://localhost:3000/api/monitoring/status
curl http://localhost:3000/api/monitoring/expiring- 🛡️ Command Injection Protection: Strict allowlist-based command validation prevents malicious shell injection
- 🔐 Path Traversal Prevention: Comprehensive file access validation prevents directory traversal attacks
- 📝 Input Sanitization: All user inputs validated and sanitized before processing
- 🚫 Filename Validation: Prevents malicious filename patterns and null byte attacks
- CLI Operations: 10 per 15 minutes (prevents command abuse)
- API Requests: 100 per 15 minutes (prevents API flooding)
- Authentication: 5 attempts per 15 minutes (prevents brute force)
- General Access: 200 requests per 15 minutes (overall protection)
- 🔑 Enterprise SSO: OpenID Connect integration with role-based access
- 🌐 HTTPS Support: Auto-generated trusted certificates with secure headers
- 📊 Audit Logging: Comprehensive logging of security events and blocked attempts
- 🔄 Auto-Recovery: Graceful error handling prevents service disruption
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/status |
System status and mkcert installation |
POST |
/api/generate |
Generate new certificates |
GET |
/api/certificates |
List all certificates |
GET |
/download/:filename |
Download certificate files |
GET |
/api/email/status |
Email configuration status |
POST |
/api/email/test |
Send test email |
GET |
/api/monitoring/status |
Certificate monitoring status |
GET |
/api/monitoring/expiring |
List expiring certificates |
curl -X POST http://localhost:3000/api/generate
-H "Content-Type: application/json"
-d '{"domains":["localhost","127.0.0.1"],"format":"pem"}'mkcertWeb/
├── server.js # Main application entry point
├── package.json # Dependencies and scripts
├── src/ # Modular application source
│ ├── config/ # Configuration management
│ ├── security/ # Security utilities
│ ├── middleware/ # Express middleware
│ ├── routes/ # Route handlers
│ ├── services/ # Email and monitoring services
│ └── utils/ # Utility functions
├── public/ # Frontend static assets
├── certificates/ # Certificate storage
├── .env.example # Environment configuration template
└── DOCKER.md # Docker deployment guide
### 🔧 Certificate Management
- **📋 View Details**: Domain coverage, expiry dates, file sizes
- **⬇️ Download**: Individual files, ZIP bundles, or PFX format
- **🔑 PFX Generation**: Create password-protected PKCS#12 files on-demand
- **🗑️ Delete**: Remove certificates (root certificates are protected)
- **📊 System Status**: View Root CA information and installation status
### 🌐 Advanced Usage
For production deployments, reverse proxy configurations, and advanced Docker setups, see [DOCKER.md](DOCKER.md).
## 🔗 API Reference
The application provides REST API endpoints for programmatic access. When authentication is enabled, establish a session first via `POST /login`.
### Key Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/status` | System status and mkcert installation |
| `POST` | `/api/generate` | Generate new certificates |
| `GET` | `/api/certificates` | List all certificates |
| `GET` | `/api/download/bundle/:folder/:certname` | Download certificate bundle |
| `POST` | `/api/generate/pfx/*` | Generate PFX file on-demand |
Example certificate generation:
```bash
# Generate certificate via API
curl -X POST http://localhost:3000/api/generate \
-H "Content-Type: application/json" \
-d '{"domains":["localhost","127.0.0.1"],"format":"pem"}'
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Commit changes:
git commit -am 'Add new feature' - Push to branch:
git push origin feature/new-feature - Submit a pull request
This project is licensed under the GPLv3 License - see the LICENSE file for details.
- mkcert - Simple tool for making locally-trusted development certificates
- Express.js - Web application framework
- Node.js - JavaScript runtime
- 🐛 Issues: GitHub Issues
- 📖 Documentation: README.md and DOCKER.md
- 💬 Discussions: GitHub Discussions
- Push to branch:
git push origin feature/new-feature - Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- mkcert - Simple tool for making locally-trusted development certificates
- Express.js - Web application framework
- Node.js - JavaScript runtime
# Clone and setup
git clone https://github.com/jeffcaldwellca/mkcertWeb.git
cd mkcertWeb
npm install
# Development modes
npm start # HTTP only (http://localhost:3000)
npm run https # HTTP + HTTPS (http://localhost:3000 & https://localhost:3443)
npm run https-only # HTTPS only with HTTP redirect (https://localhost:3443)
npm run dev # HTTP with auto-restart (nodemon)
npm run https-dev # HTTPS with auto-restart (nodemon)-
Copy the example configuration:
cp .env.example .env
-
Enable authentication in
.env:ENABLE_AUTH=true AUTH_USERNAME=your-username AUTH_PASSWORD=your-secure-password SESSION_SECRET=your-very-long-random-secret-key
-
Start the server and access at http://localhost:3000
Security Notes:
- When
ENABLE_AUTH=false, authentication is completely disabled - When
ENABLE_AUTH=true, all API routes are protected and require valid session authentication - Always use a strong, unique
SESSION_SECRETin production environments - Consider using HTTPS when authentication is enabled for additional security
See TESTING.md for comprehensive testing procedures including installation verification, certificate generation testing, authentication testing, API endpoint validation, and security testing.
| Issue | Solution |
|---|---|
| mkcert not found | which mkcert && mkcert -version |
| Permission Denied | sudo chown -R $(whoami):$(whoami) certificates/ |
| Port Already in Use | PORT=3001 npm start |
| CA Installation Issues | mkcert -install && ls -la $(mkcert -CAROOT) |
| Browser Trust Issues | Clear cache, restart browser after CA installation |