mirror of https://github.com/jeffcaldwellca/mkcertWeb.git synced 2026-01-12 15:49:57 -06:00

Files

Jeff Caldwell 950560c914 notifications!

2025-08-29 01:38:34 -04:00

21 KiB

Raw Permalink Blame History

mkcert Web UI

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.

✨ Key Features

🔐 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

<EFBFBD> Screenshots

Modern web interface showing certificate generation and management features

<EFBFBD>🚀 Quick Start

Using Docker (Recommended)

# Clone and start
git clone https://github.com/jeffcaldwellca/mkcertWeb.git
cd mkcertWeb
docker-compose up -d

# Access at http://localhost:3000

Local Installation

# Prerequisites: Node.js 16+, mkcert, OpenSSL
npm install
mkcert -install    # First time only
npm start

For detailed setup instructions, see DOCKER.md

⚙️ Configuration

Essential Environment Variables

# 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

# Security & Rate Limiting (NEW in v2.0)
CLI_RATE_LIMIT_MAX=10        # Max CLI operations per 15min window
API_RATE_LIMIT_MAX=100       # Max API requests per 15min window  
AUTH_RATE_LIMIT_MAX=5        # Max auth attempts per 15min window
CLI_RATE_LIMIT_WINDOW=900000 # CLI rate limit window (15 minutes)
API_RATE_LIMIT_WINDOW=900000 # API rate limit window (15 minutes)
AUTH_RATE_LIMIT_WINDOW=900000 # Auth rate limit window (15 minutes)

# 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

Advanced Configuration

For complete configuration options including rate limiting windows, SSL domains, and OIDC scopes, see the .env.example file or DOCKER.md.

📧 Email Notifications & Certificate Monitoring

The mkcert Web UI includes enterprise-grade certificate monitoring with automated email notifications for expiring certificates.

Email Configuration

# Enable 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 (use app passwords for Gmail)
EMAIL_FROM=mkcert@yourcompany.com       # From address for notifications
EMAIL_TO=admin@company.com,ops@company.com  # Comma-separated recipients

Certificate Monitoring Configuration

# Enable automatic 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 alerts
CERT_MONITOR_UPLOADED=true              # Monitor uploaded certificates too

Supported Email Providers

Gmail:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
# Note: Use App Passwords instead of your regular password

Outlook/Office 365:

SMTP_HOST=smtp-mail.outlook.com
SMTP_PORT=587
SMTP_SECURE=false

Corporate Exchange:

SMTP_HOST=mail.yourcompany.com
SMTP_PORT=587
SMTP_SECURE=false

Monitoring Schedule Examples

# Daily at 8 AM
CERT_CHECK_INTERVAL=0 8 * * *

# Every 6 hours
CERT_CHECK_INTERVAL=0 */6 * * *

# Weekly on Mondays at 9 AM
CERT_CHECK_INTERVAL=0 9 * * 1

# First day of every month at 8 AM
CERT_CHECK_INTERVAL=0 8 1 * *

API Endpoints

# Check email configuration status
curl http://localhost:3000/api/email/status

# Send test email
curl -X POST http://localhost:3000/api/email/test

# Get monitoring status
curl http://localhost:3000/api/monitoring/status

# Manually check for expiring certificates
curl -X POST http://localhost:3000/api/monitoring/check

# Get list of expiring certificates
curl http://localhost:3000/api/monitoring/expiring

📚 Usage

Getting Started

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

API Usage

# Generate certificate (v2.0 standardized response format)
curl -X POST http://localhost:3000/api/execute \
  -H "Content-Type: application/json" \
  -d '{"command":"generate","input":"localhost example.com"}'

# Response format (NEW in v2.0)
{
  "success": true,
  "output": "Created certificate for localhost and example.com",
  "command": "mkcert localhost example.com"
}

# List certificates
curl http://localhost:3000/api/certificates
# Returns: { "success": true, "certificates": [...], "total": 5 }

# Download certificate file
wget http://localhost:3000/download/localhost.pem -O localhost.pem

🔒 Security Features (Enhanced in v2.0)

Enterprise-Grade Security

🛡️ 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

Multi-Tier Rate Limiting

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)

Additional Security

🔑 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

<EFBFBD> Support

🐛 Issues: GitHub Issues
📖 Documentation: Complete docs in DOCKER.md
💬 Discussions: GitHub Discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details. └── 2025-01-20/ # Date-based organization ├── 2025-01-20T10-30-45_localhost/ │ ├── localhost.pem │ ├── localhost-key.pem │ └── localhost.pfx # Generated on-demand └── 2025-01-20T14-15-20_example/ ├── example.crt └── example.key


### 🔧 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"}'

🤝 Contributing

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

📄 License

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

🙏 Acknowledgments

mkcert - Simple tool for making locally-trusted development certificates
Express.js - Web application framework
Node.js - JavaScript runtime

📞 Support

🐛 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

📄 License

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

🙏 Acknowledgments

mkcert - Simple tool for making locally-trusted development certificates
Express.js - Web application framework
Node.js - JavaScript runtime

📞 Support

🐛 Issues: GitHub Issues
📖 Documentation: README.md and DOCKER.md
💬 Discussions: GitHub Discussions wget --post-data='{"domains":["localhost","127.0.0.1","*.local.dev"],"format":"pem"}'
--header='Content-Type: application/json'
http://localhost:3000/api/generate
-O /tmp/cert-response.json

Generate CRT format certificate

wget --post-data='{"domains":["example.local","api.example.local"],"format":"crt"}'
--header='Content-Type: application/json'
http://localhost:3000/api/generate
-O /tmp/cert-response.json


#### Download Certificate Bundle
```bash
# Download as bundle (no external tools needed)
wget http://localhost:3000/api/download/bundle/2025-07-25_2025-07-25T10-30-45_localhost/localhost_127-0-0-1 \
     -O certificate-bundle.zip

Check System Status

# Check if mkcert is installed and CA exists
wget -qO- http://localhost:3000/api/status | python3 -m json.tool

List All Certificates

# Get certificate inventory
wget -qO- http://localhost:3000/api/certificates | python3 -m json.tool

File Structure (v2.0 Modular Architecture)

mkcertWeb/
├── server.js                 # Main application entry point (modular)
├── package.json             # Node.js dependencies and scripts  
├── src/                     # Modular application source (NEW in v2.0)
│   ├── config/             # Configuration management
│   │   └── index.js        # Centralized environment configuration
│   ├── security/           # Security utilities
│   │   └── index.js        # Command validation, path sanitization
│   ├── middleware/         # Express middleware
│   │   ├── auth.js         # Authentication middleware factory
│   │   └── rateLimiting.js # Rate limiting middleware factory
│   ├── routes/             # Route handlers (organized by functionality)
│   │   ├── auth.js         # Authentication routes
│   │   ├── certificates.js # Certificate management routes
│   │   ├── files.js        # File upload/download routes
│   │   └── system.js       # System and API information routes
│   └── utils/              # Utility functions
│       ├── certificates.js # Certificate parsing helpers
│       ├── fileValidation.js # File validation utilities
│       └── responses.js    # Standardized response utilities
├── public/                  # Frontend static assets
│   ├── index.html          # Main web interface
│   ├── login.html          # Authentication login page
│   ├── styles.css          # Terminal-style CSS with red/green theme
│   ├── script.js           # Frontend JavaScript functionality
│   └── assets/             # Static assets (screenshots, etc.)
├── certificates/            # Certificate storage (organized by date)
│   ├── root/               # Legacy certificates (read-only)
│   └── YYYY-MM-DD/         # Date-based organization
├── .env.example            # Environment configuration template
├── CHANGELOG.md            # Version history and release notes (updated for v2.0)
├── DEDUPLICATION_COMPLETE.md # Architecture improvement documentation (NEW)
├── TESTING.md              # Testing procedures and validation (updated)
├── DOCKER.md               # Docker deployment guide (updated)
└── package-lock.json       # Dependency lock file

Security & Best Practices

Security Model (Enhanced in v2.0)

Enterprise Security: Command injection protection, path traversal prevention, and comprehensive input validation
Development & Production Ready: Secure for both local development and production deployments
Flexible Authentication: Basic authentication and enterprise SSO with OpenID Connect
Multi-Tier Rate Limiting: Comprehensive protection against abuse with configurable limits
- CLI Operations: 10 per 15 minutes (certificate generation, CA management)
- API Requests: 100 per 15 minutes (general API endpoints)
- Authentication: 5 attempts per 15 minutes (brute force protection)
- General Access: 200 per 15 minutes (overall protection)
Secure File Handling: All file operations validated against path traversal and malicious filenames
Command Validation: Strict allowlist prevents shell injection attacks
Session Security: HTTP-only cookies with CSRF protection and secure OIDC flows
Audit Logging: Comprehensive security event logging for monitoring
Graceful Error Handling: Prevents information disclosure through consistent error responses

Network Security

HTTP Only: Suitable for localhost development (consider HTTPS proxy for production)
Local Binding: Binds to localhost by default (configurable)
No External Dependencies: No outbound network calls required during operation

File Permissions

# Recommended permissions for production deployment
find /opt/mkcertui -type f -name "*.pem" -exec chmod 600 {} \;  # Private keys
find /opt/mkcertui -type f -name "*.crt" -exec chmod 644 {} \;  # Certificates
find /opt/mkcertui -type d -exec chmod 755 {} \;               # Directories

Development

Local Development

# 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)

# Custom domain HTTPS
SSL_DOMAIN=myapp.local npm run https

Testing

See TESTING.md for comprehensive testing procedures including:

Installation verification
Certificate generation testing
Authentication testing (both basic and OIDC)
API endpoint validation
Security testing
OIDC SSO integration testing
Browser integration testing

Configuration

Environment Variables

# Server Configuration
PORT=3000                    # Server port (default: 3000)
HTTPS_PORT=3443             # HTTPS server port (default: 3443)
NODE_ENV=production          # Environment mode (development/production)
CERT_DIR=/custom/path        # Custom certificate storage directory

# HTTPS Configuration
ENABLE_HTTPS=true           # Enable HTTPS server (true/false)
SSL_DOMAIN=localhost        # Domain name for SSL certificate
FORCE_HTTPS=false           # Redirect HTTP to HTTPS (true/false)

# Authentication Configuration
ENABLE_AUTH=false           # Enable user authentication (true/false)
AUTH_USERNAME=admin         # Username for authentication (when ENABLE_AUTH=true)
AUTH_PASSWORD=admin         # Password for authentication (when ENABLE_AUTH=true)
SESSION_SECRET=your-secret  # Session secret key - CHANGE IN PRODUCTION!

# UI Configuration
DEFAULT_THEME=dark          # Default theme mode for new users (dark/light)

Authentication Setup

To enable user authentication and secure access to the web interface:

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:
```
npm start
```
Access the application:
- Visit http://localhost:3000 (or your configured URL)
- You'll be redirected to a login page
- Enter your configured username and password

Security Notes:

When ENABLE_AUTH=false, authentication is completely disabled and users have direct access
When ENABLE_AUTH=true, all API routes are protected and require valid session authentication
Always use a strong, unique SESSION_SECRET in production environments
Consider using HTTPS when authentication is enabled for additional security

Theme Configuration

The application supports both dark and light themes with a toggle button. You can set the default theme for new users:

# Set default theme in .env
DEFAULT_THEME=light  # Start with light mode for new users
DEFAULT_THEME=dark   # Start with dark mode for new users (default)

Theme Behavior:

Users can toggle between themes using the button in the header
Theme preference is saved in browser localStorage
If no stored preference exists, the server's DEFAULT_THEME setting is used
Supports both the main application and login page
Available via API endpoint: GET /api/config/theme

Customization

# Custom certificate storage location
export CERT_DIR=/var/lib/mkcertui/certificates
mkdir -p $CERT_DIR
chown mkcertui:mkcertui $CERT_DIR

Troubleshooting

Common Issues

mkcert not found

# Verify installation
which mkcert
mkcert -version

# Check PATH
echo $PATH

Permission Denied

# Check file permissions
ls -la certificates/
# Ensure proper ownership
sudo chown -R $(whoami):$(whoami) certificates/

Port Already in Use

# Check what's using port 3000
sudo netstat -tlnp | grep :3000
# Use different port
PORT=3001 npm start

CA Installation Issues

# Manual CA installation
mkcert -install
# Verify CA location
mkcert -CAROOT
# Check CA files exist
ls -la $(mkcert -CAROOT)

Browser Trust Issues

Clear browser cache and cookies
Restart browser after CA installation
Check browser certificate settings
Verify system certificate store

Log Analysis

# Check application logs
journalctl -u mkcertui -f

# Check nginx logs (if using reverse proxy)
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

Contributing

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature-name
Install dependencies: npm install
Make changes and test thoroughly
Run tests: npm test (see TESTING.md)
Submit a pull request

Code Style

ESLint configuration for consistent code style
Comprehensive error handling
Clear API documentation
Responsive UI design

Resources

mkcert: GitHub Repository
Node.js: Official Documentation
Express.js: Framework Documentation
SSL/TLS: Mozilla SSL Configuration

21 KiB Raw Permalink Blame History Unescape Escape

mkcert Web UI

✨ Key Features

<EFBFBD> Screenshots

<EFBFBD>🚀 Quick Start

Using Docker (Recommended)

Local Installation

⚙️ Configuration

Essential Environment Variables

Advanced Configuration

📧 Email Notifications & Certificate Monitoring

Email Configuration

Certificate Monitoring Configuration

Supported Email Providers

Monitoring Schedule Examples

API Endpoints

📚 Usage

Getting Started

API Usage

🔒 Security Features (Enhanced in v2.0)

Enterprise-Grade Security

Multi-Tier Rate Limiting

Additional Security

<EFBFBD> Support

📄 License

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

📄 License

🙏 Acknowledgments

📞 Support

Generate CRT format certificate

Check System Status

List All Certificates

File Structure (v2.0 Modular Architecture)

Security & Best Practices

Security & Best Practices

Security Model (Enhanced in v2.0)

Network Security

File Permissions

Development

Local Development

Testing

Configuration

Environment Variables

Authentication Setup

Theme Configuration

Customization

Troubleshooting

Common Issues

mkcert not found

Permission Denied

Port Already in Use

CA Installation Issues

Browser Trust Issues

Log Analysis

Contributing

Development Setup

Code Style

Resources

21 KiB

Raw Permalink Blame History