docs: add comprehensive security and authentication documentation

Add new documentation sections covering security best practices and authentication system architecture. Update Sphinx configuration and dependencies to support documentation improvements. Changes include: - New security.rst with SSH key management, network security, secrets management - New authentication.rst documenting pluggable auth system and provider setup - Updated Sphinx config to use Alabaster theme and add sphinx-tabs extension - Added docs extra dependencies in pyproject.toml for documentation builds - Updated example configs to use Ed25519 instead of deprecated DSA keys - Added .python-version file for consistent Python version management - Added CLAUDE.md project instructions for AI-assisted development - Minor Dockerfile cleanup removing commented pip install line 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-05 02:36:05 +02:00
parent 84b718e625
commit 3918a74963
12 changed files with 1337 additions and 202 deletions
@@ -0,0 +1,288 @@
+.. Reminder for header structure:
+  Level 1: ====================
+  Level 2: --------------------
+  Level 3: ++++++++++++++++++++
+  Level 4: """"""""""""""""""""
+  Level 5: ^^^^^^^^^^^^^^^^^^^^
+
+.. meta::
+  :description: Security best practices for TISBackup
+  :keywords: Documentation, TISBackup, security, best practices, authentication
+
+Security Best Practices
+=======================
+
+.. _security_best_practices:
+
+TISBackup has been designed with security in mind. This section outlines
+the security features and best practices for deploying and maintaining
+a secure backup infrastructure.
+
+SSH Key Algorithm Support
+--------------------------
+
+Modern SSH Key Algorithms
+++++++++++++++++++++++++
+
+TISBackup supports modern SSH key algorithms with the following priority:
+
+1. **Ed25519** (recommended) - Modern, fast, and secure
+2. **ECDSA** - Elliptic curve cryptography
+3. **RSA** - Traditional algorithm (use 4096 bits minimum)
+
+.. warning::
+
+  DSA keys are **no longer supported** due to known security vulnerabilities.
+  If you are using DSA keys, you must migrate to Ed25519, ECDSA, or RSA.
+
+Generating Secure SSH Keys
+++++++++++++++++++++++++++
+
+For new installations, generate an Ed25519 key:
+
+.. code-block:: bash
+
+  ssh-keygen -t ed25519 -C "tisbackup@$(hostname)"
+
+For compatibility with older systems that don't support Ed25519, use RSA with 4096 bits:
+
+.. code-block:: bash
+
+  ssh-keygen -t rsa -b 4096 -C "tisbackup@$(hostname)"
+
+Migrating from DSA Keys
++++++++++++++++++++++++
+
+If you have existing backup configurations using DSA keys:
+
+1. Generate a new Ed25519 key on the backup server
+2. Copy the new public key to all backup clients
+3. Update the ``private_key`` parameter in all backup sections
+4. Test the backups to ensure they work with the new key
+5. Remove the old DSA keys from both server and clients
+
+Flask Web Interface Security
+-----------------------------
+
+Authentication
++++++++++++++
+
+The Flask web interface now requires authentication by default.
+TISBackup supports multiple authentication methods:
+
+Basic Authentication (Default)
+"""""""""""""""""""""""""""""""
+
+By default, TISBackup uses HTTP Basic Authentication. Configure it via
+environment variables or the configuration file.
+
+**Environment variables:**
+
+.. code-block:: bash
+
+  export TISBACKUP_AUTH_USERNAME="admin"
+  export TISBACKUP_AUTH_PASSWORD="your-secure-password"
+
+**Configuration file** (:file:`/etc/tis/tisbackup_gui.ini`):
+
+.. code-block:: ini
+
+  [authentication]
+  type=basic
+  username=admin
+  # Bcrypt hash of password (recommended)
+  password_hash=$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5eSZL9fJQp.Ym
+  use_bcrypt=True
+  realm=TISBackup
+
+.. warning::
+
+  If no password is configured, TISBackup will generate a random password
+  and display it in the logs. This is not suitable for production use.
+
+Session-Based Authentication (Flask-Login)
+"""""""""""""""""""""""""""""""""""""""""""
+
+For more advanced deployments, you can use Flask-Login with a user file:
+
+.. code-block:: ini
+
+  [authentication]
+  type=flask-login
+  user_file=/etc/tis/tisbackup_users.txt
+  secret_key=<random-secret-key>
+
+OAuth2 Authentication
+""""""""""""""""""""""
+
+For enterprise deployments, OAuth2 is supported with providers like Google,
+GitHub, and GitLab:
+
+.. code-block:: ini
+
+  [authentication]
+  type=oauth
+  provider=google
+  client_id=<your-client-id>
+  client_secret=<your-client-secret>
+  redirect_uri=http://backup.example.com:8080/callback
+  allowed_domains=example.com
+
+See :file:`AUTHENTICATION.md` in the repository root for detailed
+authentication configuration.
+
+Secret Key Configuration
+++++++++++++++++++++++++
+
+The Flask application requires a secret key for session security.
+
+**Never use the default hardcoded key in production!**
+
+Configure via environment variable:
+
+.. code-block:: bash
+
+  export TISBACKUP_SECRET_KEY="your-random-secret-key-here"
+
+Or in :file:`/etc/tis/tisbackup_gui.ini`:
+
+.. code-block:: ini
+
+  [global]
+  secret_key=your-random-secret-key-here
+
+Generate a secure random key:
+
+.. code-block:: bash
+
+  python3 -c "import secrets; print(secrets.token_hex(32))"
+
+SSL/TLS Configuration
+++++++++++++++++++++
+
+For production deployments, always use HTTPS. Place the Flask application
+behind a reverse proxy like Nginx or Apache:
+
+**Nginx example:**
+
+.. code-block:: nginx
+
+  server {
+      listen 443 ssl http2;
+      server_name backup.example.com;
+
+      ssl_certificate /etc/ssl/certs/backup.crt;
+      ssl_certificate_key /etc/ssl/private/backup.key;
+
+      location / {
+          proxy_pass http://127.0.0.1:8080;
+          proxy_set_header Host $host;
+          proxy_set_header X-Real-IP $remote_addr;
+          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+          proxy_set_header X-Forwarded-Proto $scheme;
+      }
+  }
+
+Database and Backup Security
+-----------------------------
+
+File Permissions
++++++++++++++++
+
+Ensure proper file permissions on sensitive files:
+
+.. code-block:: bash
+
+  # Configuration files
+  chmod 600 /etc/tis/tisbackup-config.ini
+  chmod 600 /etc/tis/tisbackup_gui.ini
+
+  # SSH keys
+  chmod 600 /root/.ssh/id_ed25519
+  chmod 644 /root/.ssh/id_ed25519.pub
+
+  # Password files (for XenServer, etc.)
+  chmod 600 /root/xen_passwd
+
+  # Backup directory
+  chown -R root:root /backup/data
+  chmod 750 /backup/data
+
+Credential Storage
++++++++++++++++++
+
+For database credentials and other secrets:
+
+* Use strong, unique passwords for each service
+* Store credentials in configuration files with restricted permissions
+* Consider using a secrets management system for sensitive deployments
+* Rotate credentials regularly
+
+Network Security
++++++++++++++++
+
+* Restrict SSH access to the backup server IP address
+* Use firewall rules to limit access to the web interface
+* Consider VPN access for remote backup management
+* Enable fail2ban or similar tools to prevent brute-force attacks
+
+Security Monitoring
+-------------------
+
+Log Monitoring
++++++++++++++
+
+Regularly review TISBackup logs for:
+
+* Failed authentication attempts
+* Backup failures or timeouts
+* Unusual activity patterns
+* SSH connection errors
+
+.. code-block:: bash
+
+  # View recent backup logs
+  journalctl -u tisbackup_gui -n 100
+
+  # Monitor for authentication failures
+  grep "authentication failed" /var/log/tisbackup/*.log
+
+Backup Verification
+++++++++++++++++++
+
+* Regularly test backup restoration
+* Verify backup integrity using checksums
+* Monitor backup sizes for unexpected changes
+* Set up Nagios checks for backup freshness
+
+Security Updates
++++++++++++++++
+
+* Keep TISBackup updated to the latest version
+* Apply security patches to the host operating system
+* Update Python dependencies regularly:
+
+.. code-block:: bash
+
+  uv sync --upgrade
+
+Additional Security Recommendations
+------------------------------------
+
+1. **Principle of Least Privilege**: Create dedicated service accounts
+   for backups rather than using root when possible
+
+2. **Network Segmentation**: Place the backup server in a dedicated
+   network segment with restricted access
+
+3. **Backup Encryption**: Consider encrypting backups at rest,
+   especially for sensitive data
+
+4. **Off-site Storage**: Maintain encrypted off-site backups
+   for disaster recovery
+
+5. **Access Auditing**: Maintain logs of who accesses backups
+   and when they are restored
+
+6. **Incident Response**: Have a documented procedure for responding
+   to security incidents involving the backup infrastructure