diff --git a/DEVELOPMENT-GUIDELINES.md b/DEVELOPMENT-GUIDELINES.md new file mode 100644 index 0000000..dbd8055 --- /dev/null +++ b/DEVELOPMENT-GUIDELINES.md @@ -0,0 +1,406 @@ +# TSYS FetchApply Development Guidelines + +## Overview + +This document contains development standards and best practices for the TSYS FetchApply infrastructure provisioning system. + +## Package Management Best Practices + +### Combine apt-get Install Commands + +**Rule:** Always combine multiple package installations into a single `apt-get install` command for performance. + +**Rationale:** Single command execution is significantly faster than multiple separate commands due to: +- Reduced package cache processing +- Single dependency resolution +- Fewer network connections +- Optimized package download ordering + +#### ✅ Correct Implementation +```bash +# Install all packages in one command +apt-get install -y package1 package2 package3 package4 + +# Real example from 2FA script +apt-get install -y libpam-google-authenticator qrencode +``` + +#### ❌ Incorrect Implementation +```bash +# Don't use separate commands for each package +apt-get install -y package1 +apt-get install -y package2 +apt-get install -y package3 +``` + +#### Complex Package Installation Pattern +```bash +function install_security_packages() { + print_info "Installing security packages..." + + # Update package cache once + apt-get update + + # Install all packages in single command + apt-get install -y \ + auditd \ + fail2ban \ + libpam-google-authenticator \ + lynis \ + rkhunter \ + aide \ + chkrootkit \ + clamav \ + clamav-daemon + + print_success "Security packages installed successfully" +} +``` + +## Script Development Standards + +### Error Handling +- Always use `set -euo pipefail` at script start +- Implement proper error trapping +- Use framework error handling functions +- Return appropriate exit codes + +### Function Structure +```bash +function function_name() { + print_info "Description of what function does..." + + # Local variables + local var1="value" + local var2="value" + + # Function logic + if [[ condition ]]; then + print_success "Success message" + return 0 + else + print_error "Error message" + return 1 + fi +} +``` + +### Framework Integration +- Source framework includes at script start +- Use framework logging and pretty print functions +- Follow existing patterns for consistency +- Include proper PROJECT_ROOT path resolution + +```bash +# Standard framework sourcing pattern +PROJECT_ROOT="$(dirname "$(realpath "${BASH_SOURCE[0]}")")/../.." +source "$PROJECT_ROOT/Framework-Includes/PrettyPrint.sh" +source "$PROJECT_ROOT/Framework-Includes/Logging.sh" +source "$PROJECT_ROOT/Framework-Includes/ErrorHandling.sh" +``` + +## Code Quality Standards + +### ShellCheck Compliance +- All scripts must pass shellcheck validation +- Address shellcheck warnings appropriately +- Use proper quoting for variables +- Handle edge cases and error conditions + +### Variable Naming +- Use UPPERCASE for global constants +- Use lowercase for local variables +- Use descriptive names +- Quote all variable expansions + +```bash +# Global constants +declare -g BACKUP_DIR="/root/backup" +declare -g CONFIG_FILE="/etc/ssh/sshd_config" + +# Local variables +local user_name="localuser" +local temp_file="/tmp/config.tmp" + +# Proper quoting +if [[ -f "$CONFIG_FILE" ]]; then + cp "$CONFIG_FILE" "$BACKUP_DIR/" +fi +``` + +### Function Documentation +- Include purpose description +- Document parameters if any +- Document return values +- Include usage examples for complex functions + +```bash +# Configure SSH hardening settings +# Parameters: none +# Returns: 0 on success, 1 on failure +# Usage: configure_ssh_hardening +function configure_ssh_hardening() { + print_info "Configuring SSH hardening..." + # Implementation +} +``` + +## Testing Requirements + +### Test Coverage +- Every new module must include corresponding tests +- Test both success and failure scenarios +- Validate configurations after changes +- Include integration tests for complex workflows + +### Test Categories +1. **Unit Tests:** Individual function validation +2. **Integration Tests:** Module interaction testing +3. **Security Tests:** Security configuration validation +4. **Validation Tests:** System requirement checking + +### Test Implementation Pattern +```bash +function test_function_name() { + echo "🔍 Testing specific functionality..." + + local failed=0 + + # Test implementation + if [[ condition ]]; then + echo "✅ Test passed" + else + echo "❌ Test failed" + ((failed++)) + fi + + return $failed +} +``` + +## Security Standards + +### Configuration Backup +- Always backup configurations before modification +- Use timestamped backup directories +- Provide restore instructions +- Test backup/restore procedures + +### Service Management +- Test configurations before restarting services +- Provide rollback procedures +- Validate service status after changes +- Include service dependency handling + +### User Safety +- Use `nullok` for gradual 2FA rollout +- Provide clear setup instructions +- Include emergency access procedures +- Test all access methods before enforcement + +## Documentation Standards + +### Script Headers +```bash +#!/bin/bash + +# TSYS Module Name - Brief Description +# Longer description of what this script does +# Author: TSYS Development Team +# Version: 1.0 +# Last Updated: YYYY-MM-DD + +set -euo pipefail +``` + +### Inline Documentation +- Comment complex logic +- Explain non-obvious decisions +- Document external dependencies +- Include troubleshooting notes + +### User Documentation +- Create comprehensive guides for complex features +- Include step-by-step procedures +- Provide troubleshooting sections +- Include examples and use cases + +## Performance Optimization + +### Package Management +- Single apt-get commands (as noted above) +- Cache package lists appropriately +- Use specific package versions when stability required +- Clean up package cache when appropriate + +### Network Operations +- Use connection timeouts for external requests +- Implement retry logic with backoff +- Cache downloaded resources when possible +- Validate download integrity + +### File Operations +- Use efficient file processing tools +- Minimize file system operations +- Use appropriate file permissions +- Clean up temporary files + +## Version Control Practices + +### Commit Messages +- Use descriptive commit messages +- Include scope of changes +- Reference related issues/requirements +- Follow established commit message format + +### Branch Management +- Test changes in feature branches +- Use pull requests for review +- Maintain clean commit history +- Tag releases appropriately + +### Code Review Requirements +- All changes require review +- Security changes require security team review +- Test coverage must be maintained +- Documentation must be updated + +## Deployment Practices + +### Pre-Deployment +- Run full test suite +- Validate in test environment +- Review security implications +- Update documentation + +### Deployment Process +- Use configuration validation +- Implement gradual rollout when possible +- Monitor for issues during deployment +- Have rollback procedures ready + +### Post-Deployment +- Validate deployment success +- Monitor system performance +- Update operational documentation +- Gather feedback for improvements + +## Example Implementation + +### Complete Module Template +```bash +#!/bin/bash + +# TSYS Security Module - Template +# Template for creating new security modules +# Author: TSYS Development Team + +set -euo pipefail + +# Source framework functions +PROJECT_ROOT="$(dirname "$(realpath "${BASH_SOURCE[0]}")")/../.." +source "$PROJECT_ROOT/Framework-Includes/PrettyPrint.sh" +source "$PROJECT_ROOT/Framework-Includes/Logging.sh" +source "$PROJECT_ROOT/Framework-Includes/ErrorHandling.sh" + +# Module configuration +BACKUP_DIR="/root/backup/module-$(date +%Y%m%d-%H%M%S)" +CONFIG_FILE="/etc/example.conf" + +# Create backup directory +mkdir -p "$BACKUP_DIR" + +print_header "TSYS Module Template" + +function backup_configs() { + print_info "Creating configuration backup..." + + if [[ -f "$CONFIG_FILE" ]]; then + cp "$CONFIG_FILE" "$BACKUP_DIR/" + print_success "Configuration backed up" + fi +} + +function install_packages() { + print_info "Installing required packages..." + + # Update package cache + apt-get update + + # Install all packages in single command + apt-get install -y package1 package2 package3 + + print_success "Packages installed successfully" +} + +function configure_module() { + print_info "Configuring module..." + + # Configuration logic here + + print_success "Module configured successfully" +} + +function validate_configuration() { + print_info "Validating configuration..." + + local failed=0 + + # Validation logic here + + if [[ $failed -eq 0 ]]; then + print_success "Configuration validation passed" + return 0 + else + print_error "Configuration validation failed" + return 1 + fi +} + +function main() { + # Check if running as root + if [[ $EUID -ne 0 ]]; then + print_error "This script must be run as root" + exit 1 + fi + + # Execute module steps + backup_configs + install_packages + configure_module + validate_configuration + + print_success "Module setup completed successfully!" +} + +# Run main function +main "$@" +``` + +## Continuous Improvement + +### Regular Reviews +- Review guidelines quarterly +- Update based on lessons learned +- Incorporate new best practices +- Gather team feedback + +### Tool Updates +- Keep development tools current +- Adopt new security practices +- Update testing frameworks +- Improve automation + +### Knowledge Sharing +- Document lessons learned +- Share best practices +- Provide training materials +- Maintain knowledge base + +--- + +**Last Updated:** July 14, 2025 +**Version:** 1.0 +**Author:** TSYS Development Team + +**Note:** These guidelines are living documents and should be updated as the project evolves and new best practices are identified. \ No newline at end of file diff --git a/Project-Tests/security/2fa-validation.sh b/Project-Tests/security/2fa-validation.sh new file mode 100755 index 0000000..443c2d6 --- /dev/null +++ b/Project-Tests/security/2fa-validation.sh @@ -0,0 +1,310 @@ +#!/bin/bash + +# Two-Factor Authentication Validation Test +# Validates 2FA configuration for SSH, Cockpit, and Webmin + +set -euo pipefail + +PROJECT_ROOT="$(dirname "$(realpath "${BASH_SOURCE[0]}")")/../.." + +function test_2fa_packages() { + echo "🔍 Testing 2FA package installation..." + + local packages=("libpam-google-authenticator" "qrencode") + local failed=0 + + for package in "${packages[@]}"; do + if dpkg -l | grep -q "^ii.*$package"; then + echo "✅ Package installed: $package" + else + echo "❌ Package missing: $package" + ((failed++)) + fi + done + + # Check if google-authenticator command exists + if command -v google-authenticator >/dev/null 2>&1; then + echo "✅ Google Authenticator command available" + else + echo "❌ Google Authenticator command not found" + ((failed++)) + fi + + return $failed +} + +function test_ssh_2fa_config() { + echo "🔍 Testing SSH 2FA configuration..." + + local ssh_config="/etc/ssh/sshd_config" + local failed=0 + + # Check required SSH settings + if grep -q "^ChallengeResponseAuthentication yes" "$ssh_config"; then + echo "✅ ChallengeResponseAuthentication enabled" + else + echo "❌ ChallengeResponseAuthentication not enabled" + ((failed++)) + fi + + if grep -q "^UsePAM yes" "$ssh_config"; then + echo "✅ UsePAM enabled" + else + echo "❌ UsePAM not enabled" + ((failed++)) + fi + + if grep -q "^AuthenticationMethods publickey,keyboard-interactive" "$ssh_config"; then + echo "✅ AuthenticationMethods configured for 2FA" + else + echo "❌ AuthenticationMethods not configured for 2FA" + ((failed++)) + fi + + return $failed +} + +function test_pam_2fa_config() { + echo "🔍 Testing PAM 2FA configuration..." + + local pam_sshd="/etc/pam.d/sshd" + local failed=0 + + # Check if PAM includes Google Authenticator + if grep -q "pam_google_authenticator.so" "$pam_sshd"; then + echo "✅ PAM Google Authenticator module configured" + else + echo "❌ PAM Google Authenticator module not configured" + ((failed++)) + fi + + # Check if nullok is present (allows users without 2FA setup) + if grep -q "pam_google_authenticator.so nullok" "$pam_sshd"; then + echo "✅ PAM nullok option configured (allows gradual rollout)" + else + echo "⚠️ PAM nullok option not configured (immediate enforcement)" + fi + + return $failed +} + +function test_cockpit_2fa_config() { + echo "🔍 Testing Cockpit 2FA configuration..." + + local cockpit_config="/etc/cockpit/cockpit.conf" + local cockpit_pam="/etc/pam.d/cockpit" + local failed=0 + + # Check if Cockpit is installed + if ! command -v cockpit-ws >/dev/null 2>&1; then + echo "⚠️ Cockpit not installed, skipping test" + return 0 + fi + + # Check Cockpit configuration + if [[ -f "$cockpit_config" ]]; then + echo "✅ Cockpit configuration file exists" + else + echo "❌ Cockpit configuration file missing" + ((failed++)) + fi + + # Check Cockpit PAM configuration + if [[ -f "$cockpit_pam" ]] && grep -q "pam_google_authenticator.so" "$cockpit_pam"; then + echo "✅ Cockpit PAM 2FA configured" + else + echo "❌ Cockpit PAM 2FA not configured" + ((failed++)) + fi + + return $failed +} + +function test_webmin_2fa_config() { + echo "🔍 Testing Webmin 2FA configuration..." + + local webmin_config="/etc/webmin/miniserv.conf" + local failed=0 + + # Check if Webmin is installed + if [[ ! -f "$webmin_config" ]]; then + echo "⚠️ Webmin not installed, skipping test" + return 0 + fi + + # Check Webmin 2FA settings + if grep -q "^twofactor_provider=totp" "$webmin_config"; then + echo "✅ Webmin TOTP provider configured" + else + echo "❌ Webmin TOTP provider not configured" + ((failed++)) + fi + + if grep -q "^twofactor=1" "$webmin_config"; then + echo "✅ Webmin 2FA enabled" + else + echo "❌ Webmin 2FA not enabled" + ((failed++)) + fi + + return $failed +} + +function test_user_2fa_setup() { + echo "🔍 Testing user 2FA setup preparation..." + + local users=("localuser" "root") + local failed=0 + + for user in "${users[@]}"; do + if id "$user" &>/dev/null; then + # Check if setup script exists + if [[ -f "/tmp/setup-2fa-$user.sh" ]]; then + echo "✅ 2FA setup script exists for user: $user" + else + echo "❌ 2FA setup script missing for user: $user" + ((failed++)) + fi + + # Check if instructions exist + if [[ -f "/home/$user/2fa-setup-instructions.txt" ]]; then + echo "✅ 2FA instructions exist for user: $user" + else + echo "❌ 2FA instructions missing for user: $user" + ((failed++)) + fi + else + echo "⚠️ User $user not found, skipping" + fi + done + + return $failed +} + +function test_service_status() { + echo "🔍 Testing service status..." + + local failed=0 + + # Test SSH service + if systemctl is-active sshd >/dev/null 2>&1; then + echo "✅ SSH service is running" + else + echo "❌ SSH service is not running" + ((failed++)) + fi + + # Test SSH configuration + if sshd -t 2>/dev/null; then + echo "✅ SSH configuration is valid" + else + echo "❌ SSH configuration is invalid" + ((failed++)) + fi + + # Test Cockpit service if installed + if systemctl is-enabled cockpit.socket >/dev/null 2>&1; then + if systemctl is-active cockpit.socket >/dev/null 2>&1; then + echo "✅ Cockpit service is running" + else + echo "❌ Cockpit service is not running" + ((failed++)) + fi + fi + + # Test Webmin service if installed + if systemctl is-enabled webmin >/dev/null 2>&1; then + if systemctl is-active webmin >/dev/null 2>&1; then + echo "✅ Webmin service is running" + else + echo "❌ Webmin service is not running" + ((failed++)) + fi + fi + + return $failed +} + +function test_backup_existence() { + echo "🔍 Testing backup existence..." + + local backup_dir="/root/backup" + local failed=0 + + if [[ -d "$backup_dir" ]]; then + # Look for recent 2FA backups + local recent_backups=$(find "$backup_dir" -name "2fa-*" -type d -newer /etc/ssh/sshd_config 2>/dev/null | wc -l) + + if [[ $recent_backups -gt 0 ]]; then + echo "✅ Recent 2FA backup found in $backup_dir" + else + echo "⚠️ No recent 2FA backups found" + fi + else + echo "❌ Backup directory does not exist" + ((failed++)) + fi + + return $failed +} + +function test_2fa_enforcement() { + echo "🔍 Testing 2FA enforcement level..." + + local pam_sshd="/etc/pam.d/sshd" + + # Check if nullok is used (allows users without 2FA) + if grep -q "pam_google_authenticator.so nullok" "$pam_sshd"; then + echo "⚠️ 2FA enforcement: GRADUAL (nullok allows users without 2FA)" + echo " Users can log in without 2FA during setup phase" + else + echo "✅ 2FA enforcement: STRICT (all users must have 2FA)" + echo " All users must have 2FA configured to log in" + fi + + return 0 +} + +# Main test execution +function main() { + echo "🔒 Running Two-Factor Authentication Validation Tests" + echo "==================================================" + + local total_failures=0 + + # Run all 2FA validation tests + test_2fa_packages || ((total_failures++)) + test_ssh_2fa_config || ((total_failures++)) + test_pam_2fa_config || ((total_failures++)) + test_cockpit_2fa_config || ((total_failures++)) + test_webmin_2fa_config || ((total_failures++)) + test_user_2fa_setup || ((total_failures++)) + test_service_status || ((total_failures++)) + test_backup_existence || ((total_failures++)) + test_2fa_enforcement || ((total_failures++)) + + echo "==================================================" + + if [[ $total_failures -eq 0 ]]; then + echo "✅ All 2FA validation tests passed" + echo "" + echo "📋 Next Steps:" + echo "1. Run user setup scripts: /tmp/setup-2fa-*.sh" + echo "2. Test 2FA login from another terminal" + echo "3. Remove nullok from PAM config for strict enforcement" + exit 0 + else + echo "❌ $total_failures 2FA validation tests failed" + echo "" + echo "🔧 Troubleshooting:" + echo "1. Re-run secharden-2fa.sh script" + echo "2. Check system logs: journalctl -u sshd" + echo "3. Verify package installation" + exit 1 + fi +} + +# Run main if executed directly +if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then + main "$@" +fi \ No newline at end of file diff --git a/ProjectCode/Modules/Security/secharden-2fa.sh b/ProjectCode/Modules/Security/secharden-2fa.sh index 402881e..c636bb0 100644 --- a/ProjectCode/Modules/Security/secharden-2fa.sh +++ b/ProjectCode/Modules/Security/secharden-2fa.sh @@ -1,10 +1,388 @@ #!/bin/bash +# TSYS Security Hardening - Two-Factor Authentication +# Implements 2FA for SSH, Cockpit, and Webmin services +# Uses Google Authenticator (TOTP) for time-based tokens -#secharden-2fa -#Coming very soon, 2fa for webmin/cockpit/ssh -#libpam-google-authenticator +set -euo pipefail -#https://www.ogselfhosting.com/index.php/2024/03/21/enabling-2fa-for-cockpit/ -#https://webmin.com/docs/modules/webmin-configuration/#two-factor-authentication -#https://www.digitalocean.com/community/tutorials/how-to-set-up-multi-factor-authentication-for-ssh-on-ubuntu-18-04 \ No newline at end of file +# Source framework functions +PROJECT_ROOT="$(dirname "$(realpath "${BASH_SOURCE[0]}")")/../.." +source "$PROJECT_ROOT/Framework-Includes/PrettyPrint.sh" +source "$PROJECT_ROOT/Framework-Includes/Logging.sh" +source "$PROJECT_ROOT/Framework-Includes/ErrorHandling.sh" + +# 2FA Configuration +BACKUP_DIR="/root/backup/2fa-$(date +%Y%m%d-%H%M%S)" +PAM_CONFIG_DIR="/etc/pam.d" +SSH_CONFIG="/etc/ssh/sshd_config" +COCKPIT_CONFIG="/etc/cockpit/cockpit.conf" + +# Create backup directory +mkdir -p "$BACKUP_DIR" + +print_header "TSYS Two-Factor Authentication Setup" + +# Backup existing configurations +function backup_configs() { + print_info "Creating backup of existing configurations..." + + # Backup SSH configuration + if [[ -f "$SSH_CONFIG" ]]; then + cp "$SSH_CONFIG" "$BACKUP_DIR/sshd_config.bak" + print_success "SSH config backed up" + fi + + # Backup PAM configurations + if [[ -d "$PAM_CONFIG_DIR" ]]; then + cp -r "$PAM_CONFIG_DIR" "$BACKUP_DIR/pam.d.bak" + print_success "PAM configs backed up" + fi + + # Backup Cockpit configuration if exists + if [[ -f "$COCKPIT_CONFIG" ]]; then + cp "$COCKPIT_CONFIG" "$BACKUP_DIR/cockpit.conf.bak" + print_success "Cockpit config backed up" + fi + + print_info "Backup completed: $BACKUP_DIR" +} + +# Install required packages +function install_2fa_packages() { + print_info "Installing 2FA packages..." + + # Update package cache + apt-get update + + # Install Google Authenticator PAM module + # Install QR code generator for terminal display + apt-get install -y libpam-google-authenticator qrencode + + print_success "2FA packages installed successfully" +} + +# Configure SSH for 2FA +function configure_ssh_2fa() { + print_info "Configuring SSH for 2FA..." + + # Configure SSH daemon + print_info "Updating SSH configuration..." + + # Enable challenge-response authentication + if ! grep -q "^ChallengeResponseAuthentication yes" "$SSH_CONFIG"; then + sed -i 's/^ChallengeResponseAuthentication.*/ChallengeResponseAuthentication yes/' "$SSH_CONFIG" || \ + echo "ChallengeResponseAuthentication yes" >> "$SSH_CONFIG" + fi + + # Enable PAM authentication + if ! grep -q "^UsePAM yes" "$SSH_CONFIG"; then + sed -i 's/^UsePAM.*/UsePAM yes/' "$SSH_CONFIG" || \ + echo "UsePAM yes" >> "$SSH_CONFIG" + fi + + # Configure authentication methods (key + 2FA) + if ! grep -q "^AuthenticationMethods" "$SSH_CONFIG"; then + echo "AuthenticationMethods publickey,keyboard-interactive" >> "$SSH_CONFIG" + else + sed -i 's/^AuthenticationMethods.*/AuthenticationMethods publickey,keyboard-interactive/' "$SSH_CONFIG" + fi + + print_success "SSH configuration updated" +} + +# Configure PAM for 2FA +function configure_pam_2fa() { + print_info "Configuring PAM for 2FA..." + + # Create backup of original PAM SSH config + cp "$PAM_CONFIG_DIR/sshd" "$PAM_CONFIG_DIR/sshd.bak.$(date +%Y%m%d)" + + # Configure PAM to use Google Authenticator + cat > "$PAM_CONFIG_DIR/sshd" << 'EOF' +# PAM configuration for SSH with 2FA +# Standard Un*x authentication +@include common-auth + +# Google Authenticator 2FA +auth required pam_google_authenticator.so nullok + +# Standard Un*x authorization +@include common-account + +# SELinux needs to be the first session rule +session required pam_selinux.so close +session required pam_loginuid.so + +# Standard Un*x session setup and teardown +@include common-session + +# Print the message of the day upon successful login +session optional pam_motd.so motd=/run/motd.dynamic +session optional pam_motd.so noupdate + +# Print the status of the user's mailbox upon successful login +session optional pam_mail.so standard noenv + +# Set up user limits from /etc/security/limits.conf +session required pam_limits.so + +# SELinux needs to intervene at login time +session required pam_selinux.so open + +# Standard Un*x password updating +@include common-password +EOF + + print_success "PAM configuration updated for SSH 2FA" +} + +# Configure Cockpit for 2FA +function configure_cockpit_2fa() { + print_info "Configuring Cockpit for 2FA..." + + # Create Cockpit config directory if it doesn't exist + mkdir -p "$(dirname "$COCKPIT_CONFIG")" + + # Configure Cockpit to use PAM with 2FA + cat > "$COCKPIT_CONFIG" << 'EOF' +[WebService] +# Enable 2FA for Cockpit web interface +LoginTitle = TSYS Server Management +LoginTo = 300 +RequireHost = true + +[Session] +# Use PAM for authentication (includes 2FA) +Banner = /etc/cockpit/issue.cockpit +IdleTimeout = 15 +EOF + + # Create PAM configuration for Cockpit + cat > "$PAM_CONFIG_DIR/cockpit" << 'EOF' +# PAM configuration for Cockpit with 2FA +auth requisite pam_nologin.so +auth required pam_env.so +auth required pam_faillock.so preauth +auth sufficient pam_unix.so try_first_pass +auth required pam_google_authenticator.so nullok +auth required pam_faillock.so authfail +auth required pam_deny.so + +account required pam_nologin.so +account include system-auth +account required pam_faillock.so + +session required pam_selinux.so close +session required pam_loginuid.so +session optional pam_keyinit.so force revoke +session include system-auth +session required pam_selinux.so open +session optional pam_motd.so +EOF + + print_success "Cockpit 2FA configuration completed" +} + +# Configure Webmin for 2FA (if installed) +function configure_webmin_2fa() { + print_info "Checking for Webmin installation..." + + local webmin_config="/etc/webmin/miniserv.conf" + + if [[ -f "$webmin_config" ]]; then + print_info "Webmin found, configuring 2FA..." + + # Stop webmin service + systemctl stop webmin || true + + # Enable 2FA in Webmin configuration + sed -i 's/^twofactor_provider=.*/twofactor_provider=totp/' "$webmin_config" || \ + echo "twofactor_provider=totp" >> "$webmin_config" + + # Enable 2FA requirement + sed -i 's/^twofactor=.*/twofactor=1/' "$webmin_config" || \ + echo "twofactor=1" >> "$webmin_config" + + # Start webmin service + systemctl start webmin || true + + print_success "Webmin 2FA configuration completed" + else + print_info "Webmin not found, skipping configuration" + fi +} + +# Setup 2FA for users +function setup_user_2fa() { + print_info "Setting up 2FA for system users..." + + local users=("localuser" "root") + + for user in "${users[@]}"; do + if id "$user" &>/dev/null; then + print_info "Setting up 2FA for user: $user" + + # Create 2FA setup script for user + cat > "/tmp/setup-2fa-$user.sh" << 'EOF' +#!/bin/bash +echo "Setting up Google Authenticator for user: $USER" +echo "Please follow the prompts to configure 2FA:" +echo "1. Answer 'y' to update your time-based token" +echo "2. Scan the QR code with your authenticator app" +echo "3. Save the backup codes in a secure location" +echo "4. Answer 'y' to the remaining questions for security" +echo "" +google-authenticator -t -d -f -r 3 -R 30 -W +EOF + + chmod +x "/tmp/setup-2fa-$user.sh" + + # Instructions for user setup + cat > "/home/$user/2fa-setup-instructions.txt" << EOF +TSYS Two-Factor Authentication Setup Instructions +============================================== + +Your system has been configured for 2FA. To complete setup: + +1. Install an authenticator app on your phone: + - Google Authenticator + - Authy + - Microsoft Authenticator + +2. Run the setup command: + sudo /tmp/setup-2fa-$user.sh + +3. Follow the prompts: + - Scan the QR code with your app + - Save the backup codes securely + - Answer 'y' to security questions + +4. Test your setup: + - SSH to the server + - Enter your 6-digit code when prompted + +IMPORTANT: Save backup codes in a secure location! +Without them, you may be locked out if you lose your phone. + +For support, contact your system administrator. +EOF + + chown "$user:$user" "/home/$user/2fa-setup-instructions.txt" + print_success "2FA setup prepared for user: $user" + else + print_warning "User $user not found, skipping" + fi + done +} + +# Restart services +function restart_services() { + print_info "Restarting services..." + + # Test SSH configuration + if sshd -t; then + systemctl restart sshd + print_success "SSH service restarted" + else + print_error "SSH configuration test failed" + return 1 + fi + + # Restart Cockpit if installed + if systemctl is-enabled cockpit.socket &>/dev/null; then + systemctl restart cockpit.socket + print_success "Cockpit service restarted" + fi + + # Restart Webmin if installed + if systemctl is-enabled webmin &>/dev/null; then + systemctl restart webmin + print_success "Webmin service restarted" + fi +} + +# Validation and testing +function validate_2fa_setup() { + print_info "Validating 2FA setup..." + + # Check if Google Authenticator is installed + if command -v google-authenticator &>/dev/null; then + print_success "Google Authenticator installed" + else + print_error "Google Authenticator not found" + return 1 + fi + + # Check SSH configuration + if grep -q "AuthenticationMethods publickey,keyboard-interactive" "$SSH_CONFIG"; then + print_success "SSH 2FA configuration valid" + else + print_error "SSH 2FA configuration invalid" + return 1 + fi + + # Check PAM configuration + if grep -q "pam_google_authenticator.so" "$PAM_CONFIG_DIR/sshd"; then + print_success "PAM 2FA configuration valid" + else + print_error "PAM 2FA configuration invalid" + return 1 + fi + + # Check service status + if systemctl is-active sshd &>/dev/null; then + print_success "SSH service is running" + else + print_error "SSH service is not running" + return 1 + fi + + print_success "2FA validation completed successfully" +} + +# Display final instructions +function show_final_instructions() { + print_header "2FA Setup Completed" + + print_info "Two-Factor Authentication has been configured for:" + print_info "- SSH (requires key + 2FA token)" + print_info "- Cockpit web interface" + if [[ -f "/etc/webmin/miniserv.conf" ]]; then + print_info "- Webmin administration panel" + fi + + print_warning "IMPORTANT: Complete user setup immediately!" + print_warning "1. Check /home/*/2fa-setup-instructions.txt for user setup" + print_warning "2. Run setup scripts for each user" + print_warning "3. Test 2FA before logging out" + + print_info "Backup location: $BACKUP_DIR" + print_info "To disable 2FA, restore configurations from backup" + + print_success "2FA setup completed successfully!" +} + +# Main execution +function main() { + # Check if running as root + if [[ $EUID -ne 0 ]]; then + print_error "This script must be run as root" + exit 1 + fi + + # Execute setup steps + backup_configs + install_2fa_packages + configure_ssh_2fa + configure_pam_2fa + configure_cockpit_2fa + configure_webmin_2fa + setup_user_2fa + restart_services + validate_2fa_setup + show_final_instructions +} + +# Run main function +main "$@" \ No newline at end of file diff --git a/TSYS-2FA-GUIDE.md b/TSYS-2FA-GUIDE.md new file mode 100644 index 0000000..013cfc4 --- /dev/null +++ b/TSYS-2FA-GUIDE.md @@ -0,0 +1,329 @@ +# TSYS Two-Factor Authentication Implementation Guide + +## Overview + +This guide provides complete instructions for implementing and managing two-factor authentication (2FA) on TSYS servers using Google Authenticator (TOTP). + +## What This Implementation Provides + +### Services Protected by 2FA +- **SSH Access:** Requires SSH key + 2FA token +- **Cockpit Web Interface:** Requires password + 2FA token +- **Webmin Administration:** Requires password + 2FA token (if installed) + +### Security Features +- **Time-based One-Time Passwords (TOTP):** Standard 6-digit codes +- **Backup Codes:** Emergency access codes +- **Gradual Rollout:** Optional nullok mode for phased deployment +- **Configuration Backup:** Automatic backup of all configs + +## Implementation Steps + +### Step 1: Run the 2FA Setup Script +```bash +# Navigate to the security modules directory +cd ProjectCode/Modules/Security + +# Run the 2FA setup script as root +sudo bash secharden-2fa.sh +``` + +### Step 2: Validate Installation +```bash +# Run 2FA validation tests +./Project-Tests/security/2fa-validation.sh + +# Run specific 2FA security test +./Project-Tests/run-tests.sh security +``` + +### Step 3: Setup Individual Users +For each user that needs 2FA access: + +```bash +# Check setup instructions +cat /home/username/2fa-setup-instructions.txt + +# Run user setup script +sudo /tmp/setup-2fa-username.sh +``` + +### Step 4: Test 2FA Access +1. **Test SSH access** from another terminal +2. **Test Cockpit access** via web browser +3. **Test Webmin access** if installed + +## User Setup Process + +### Installing Authenticator Apps +Users need one of these apps on their phone: +- **Google Authenticator** (Android/iOS) +- **Authy** (Android/iOS) +- **Microsoft Authenticator** (Android/iOS) +- **1Password** (with TOTP support) + +### Setting Up 2FA for a User +1. **Run setup script:** + ```bash + sudo /tmp/setup-2fa-username.sh + ``` + +2. **Follow prompts:** + - Answer "y" to update time-based token + - Scan QR code with authenticator app + - Save emergency backup codes securely + - Answer "y" to remaining security questions + +3. **Test immediately:** + ```bash + # Test SSH from another terminal + ssh username@server-ip + # You'll be prompted for 6-digit code + ``` + +## Configuration Details + +### SSH Configuration Changes +File: `/etc/ssh/sshd_config` +``` +ChallengeResponseAuthentication yes +UsePAM yes +AuthenticationMethods publickey,keyboard-interactive +``` + +### PAM Configuration +File: `/etc/pam.d/sshd` +``` +auth required pam_google_authenticator.so nullok +``` + +### Cockpit Configuration +File: `/etc/cockpit/cockpit.conf` +``` +[WebService] +LoginTitle = TSYS Server Management +LoginTo = 300 +RequireHost = true + +[Session] +Banner = /etc/cockpit/issue.cockpit +IdleTimeout = 15 +``` + +### Webmin Configuration +File: `/etc/webmin/miniserv.conf` +``` +twofactor_provider=totp +twofactor=1 +``` + +## Security Considerations + +### Gradual vs Strict Enforcement + +#### Gradual Enforcement (Default) +- Uses `nullok` option in PAM +- Users without 2FA can still log in +- Allows phased rollout +- Good for initial deployment + +#### Strict Enforcement +- Remove `nullok` from PAM configuration +- All users must have 2FA configured +- Immediate security enforcement +- Risk of lockout if misconfigured + +### Backup and Recovery + +#### Emergency Access +- **Backup codes:** Generated during setup +- **Root access:** Can disable 2FA if needed +- **Console access:** Physical/virtual console bypasses SSH + +#### Configuration Backup +- Automatic backup to `/root/backup/2fa-TIMESTAMP/` +- Includes all modified configuration files +- Can be restored if needed + +## Troubleshooting + +### Common Issues + +#### 1. User Cannot Generate QR Code +```bash +# Ensure qrencode is installed +sudo apt-get install qrencode + +# Re-run user setup +sudo /tmp/setup-2fa-username.sh +``` + +#### 2. SSH Connection Fails +```bash +# Check SSH service status +sudo systemctl status sshd + +# Test SSH configuration +sudo sshd -t + +# Check logs +sudo journalctl -u sshd -f +``` + +#### 3. 2FA Code Not Accepted +- **Check time synchronization** on server and phone +- **Verify app setup** - rescan QR code if needed +- **Try backup codes** if available + +#### 4. Locked Out of Server +```bash +# Access via console (physical/virtual) +# Disable 2FA temporarily +sudo cp /root/backup/2fa-*/pam.d.bak/sshd /etc/pam.d/sshd +sudo systemctl restart sshd +``` + +### Debug Commands + +```bash +# Check 2FA status +./Project-Tests/security/2fa-validation.sh + +# Check SSH configuration +sudo sshd -T | grep -E "(Challenge|PAM|Authentication)" + +# Check PAM configuration +cat /etc/pam.d/sshd | grep google-authenticator + +# Check user 2FA status +ls -la ~/.google_authenticator +``` + +## Management and Maintenance + +### Adding New Users +1. Ensure user account exists +2. Run setup script for new user +3. Provide setup instructions +4. Test access + +### Removing User 2FA +```bash +# Remove user's 2FA configuration +sudo rm /home/username/.google_authenticator + +# User will need to re-setup 2FA +``` + +### Disabling 2FA System-Wide +```bash +# Restore original configurations +sudo cp /root/backup/2fa-*/sshd_config.bak /etc/ssh/sshd_config +sudo cp /root/backup/2fa-*/pam.d.bak/sshd /etc/pam.d/sshd +sudo systemctl restart sshd +``` + +### Updating 2FA Configuration +```bash +# Re-run setup script +sudo bash secharden-2fa.sh + +# Validate changes +./Project-Tests/security/2fa-validation.sh +``` + +## Best Practices + +### Deployment Strategy +1. **Test in non-production** environment first +2. **Enable gradual rollout** (nullok) initially +3. **Train users** on 2FA setup process +4. **Test emergency procedures** before strict enforcement +5. **Monitor logs** for authentication issues + +### Security Recommendations +- **Enforce strict mode** after successful rollout +- **Regular backup code rotation** +- **Monitor failed authentication attempts** +- **Document emergency procedures** +- **Regular security audits** + +### User Training +- **Provide clear instructions** +- **Demonstrate setup process** +- **Explain backup code importance** +- **Test login process with users** +- **Establish support procedures** + +## Monitoring and Logging + +### Authentication Logs +```bash +# SSH authentication logs +sudo journalctl -u sshd | grep -i "authentication" + +# PAM authentication logs +sudo journalctl | grep -i "pam_google_authenticator" + +# Failed login attempts +sudo journalctl | grep -i "failed" +``` + +### Security Monitoring +- Monitor for repeated failed 2FA attempts +- Alert on successful logins without 2FA (during gradual rollout) +- Track user 2FA setup completion +- Monitor for emergency access usage + +## Integration with Existing Systems + +### LDAP/Active Directory +- 2FA works with existing authentication systems +- Users still need local 2FA setup +- Consider centralized 2FA solutions for large deployments + +### Monitoring Systems +- LibreNMS: Will continue to work with SNMP +- Wazuh: Will log 2FA authentication events +- Cockpit: Enhanced with 2FA protection + +### Backup Systems +- Ensure backup procedures account for 2FA +- Test restore procedures with 2FA enabled +- Document emergency access procedures + +## Support and Resources + +### Files Created by Setup +- `/tmp/setup-2fa-*.sh` - User setup scripts +- `/home/*/2fa-setup-instructions.txt` - User instructions +- `/root/backup/2fa-*/` - Configuration backups + +### Validation Tools +- `./Project-Tests/security/2fa-validation.sh` - Complete 2FA validation +- `./Project-Tests/run-tests.sh security` - Security test suite + +### Emergency Contacts +- System Administrator: [Contact Info] +- Security Team: [Contact Info] +- 24/7 Support: [Contact Info] + +## Compliance and Audit + +### Security Benefits +- Significantly reduces risk of unauthorized access +- Meets multi-factor authentication requirements +- Provides audit trail of authentication events +- Complies with security frameworks (NIST, ISO 27001) + +### Audit Trail +- All authentication attempts logged +- 2FA setup events recorded +- Configuration changes tracked +- Emergency access documented + +--- + +**Last Updated:** July 14, 2025 +**Version:** 1.0 +**Author:** TSYS Security Team \ No newline at end of file