TISbackup/docs-sphinx-rst/source/security.rst

.. 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