ssl-managment/.junie/guidelines.md

SSL Management Project Guidelines

This document provides guidelines for developing and maintaining the SSL Management project, which is a Python-based tool for managing SSL certificates for UniFi devices such as UDM-SE. The tool helps automate the process of obtaining, validating, and deploying SSL certificates to UniFi devices.

Build/Configuration Instructions

Prerequisites

1. Python 3.6+: The project is written in Python and requires Python 3.6 or higher.
2. OpenSSL: Required for certificate operations. Must be installed and available in your PATH.
3. Virtual Environment: The project uses a virtual environment for dependency isolation.
4. Linux Environment: The script is designed to run on Linux systems such as Ubuntu 24.04. While development can occur on any platform, deployment is expected on a Linux server.

Setup

1. Clone the repository:

   git clone <repository-url>
   cd ssl-managment
   

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. No external Python packages are required as the project uses standard library modules.

Configuration

The SSL Manager uses a configuration file (config.json) to store default settings. The configuration file should be placed in the project root directory. Here's an example of the configuration file:

{
  "cert_dir": "~/.ssl-certs",
  "default_port": 443,
  "connection_timeout": 3.0,
  "default_validity_days": 365,
  "key_size": 2048,
  "unifi": {
    "host": "unifi.example.com",
    "username": "admin",
    "password": "password",
    "site": "default",
    "ssh_port": 22,
    "ssh_username": "root",
    "ssh_password": "",
    "ssh_key_path": "~/.ssh/id_rsa"
  }
}

Configuration options:

• cert_dir: Directory where certificates and keys will be stored
• default_port: Default port to use when checking certificate expiration
• connection_timeout: Timeout in seconds for SSL connections
• default_validity_days: Default validity period in days for generated certificates
• key_size: Key size in bits for generated certificates
• unifi: UniFi device connection parameters
  • host: Hostname or IP address of the UniFi device
  • username: Username for authenticating with the UniFi device
  • password: Password for authenticating with the UniFi device
  • site: Site name for the UniFi device (default: 'default')
  • ssh_port: SSH port for the UniFi device (default: 22)
  • ssh_username: Username for SSH authentication with the UniFi device
  • ssh_password: Password for SSH authentication (leave empty to use SSH key)
  • ssh_key_path: Path to the SSH private key file for authentication

Usage

The SSL Manager provides three main commands. All commands support the following global options:

• --config: Path to the config file (default: config.json)
• --cert-dir: Directory to store certificates (overrides config)

1. Check Certificate Expiration:

   python src/ssl_manager.py check example.com [--port PORT]
   

   The --port option overrides the default_port from the config file.

2. Generate Self-Signed Certificate:

   python src/ssl_manager.py generate example.com [--days DAYS]
   

   The --days option overrides the default_validity_days from the config file.

3. Validate Certificate Chain:

   python src/ssl_manager.py validate path/to/certificate.crt [--ca-path path/to/ca.crt]
   

Testing Information

Running Tests

Tests are written using the Python unittest framework. To run all tests:

cd ssl-managment  # Ensure you're in the project root
python -m unittest discover tests

To run a specific test file:

python -m tests.test_ssl_manager

Adding New Tests

1. Create a new test file in the tests directory, following the naming convention test_*.py.

2. Import the necessary modules and the SSLManager class:

   import os
   import sys
   import unittest
   from unittest.mock import patch
   
   # Add the src directory to the Python path
   sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../src')))
   
   from ssl_manager import SSLManager
   

3. Create a test class that inherits from unittest.TestCase:

   class TestYourFeature(unittest.TestCase):
       def setUp(self):
           # Set up test fixtures
           self.ssl_manager = SSLManager()
   
       def test_your_feature(self):
           # Test your feature
           result = self.ssl_manager.your_method()
           self.assertEqual(result, expected_value)
   

4. Use mocking to avoid actual network or system calls:

   @patch('ssl_manager.subprocess.run')
   def test_with_mock(self, mock_run):
       mock_run.return_value = MagicMock(returncode=0)
       # Test with mock
   

Test Example

Here's a simple test that verifies the SSLManager initializes correctly:

def test_init_creates_cert_dir(self):
    """Test that the constructor creates the certificate directory."""
    test_path = os.path.expanduser("~/test-ssl-certs")
    
    # Remove the directory if it exists
    if os.path.exists(test_path):
        os.rmdir(test_path)
    
    # Create a new SSLManager with the test path
    ssl_manager = SSLManager(cert_dir=test_path)
    
    # Verify the directory was created
    self.assertTrue(os.path.exists(test_path))
    self.assertTrue(os.path.isdir(test_path))
    
    # Clean up
    os.rmdir(test_path)

Development Guidelines

Code Style

1. PEP 8: Follow the PEP 8 style guide for Python code.
2. Docstrings: Use docstrings for all modules, classes, and functions. Follow the Google style for docstrings.
3. Type Hints: Use type hints for function parameters and return values.

Project Structure

• src/: Contains the source code
  • ssl_manager.py: Main module with the SSLManager class
• tests/: Contains test files
  • test_ssl_manager.py: Tests for the SSLManager class

Best Practices

1. Error Handling: Use try-except blocks to handle exceptions gracefully.
2. Logging: Use the Python logging module for logging instead of print statements.
3. Testing: Write tests for all new features and bug fixes.
4. Documentation: Update documentation when making changes to the code.

Deployment and Automation

Cross-Machine Deployment

The SSL Management tool can be developed on one machine and deployed to another server for production use. When deploying across machines:

1. Ensure the target server meets all the prerequisites (Python 3.6+, OpenSSL, etc.)
2. Transfer the entire project directory to the target server
3. Set up the virtual environment on the target server
4. Configure the config.json file with the appropriate settings for the target environment
5. Test the deployment by running a simple command like python src/ssl_manager.py check <hostname>

Automated Certificate Updates

To automate certificate updates using cron:

1. Create a shell script wrapper for the SSL Manager:

   #!/bin/bash
   # File: update_certificates.sh
   
   # Change to the project directory
   cd /path/to/ssl-managment
   
   # Activate the virtual environment
   source .venv/bin/activate
   
   # Run the SSL Manager to update certificates
   python src/ssl_manager.py generate your-unifi-device.example.com --days 90
   
   # Additional commands to deploy the certificate to the UniFi device can be added here
   

2. Make the script executable:

   chmod +x update_certificates.sh
   

3. Add a cron job to run the script periodically (e.g., every 60 days):

   # Edit the crontab
   crontab -e
   
   # Add a line like this to run at 2:30 AM on the 1st of every other month
   30 2 1 */2 * /path/to/update_certificates.sh >> /var/log/certificate-updates.log 2>&1
   

4. Verify the cron job is set up correctly:

   crontab -l
   

Troubleshooting

Common Issues

1. OpenSSL Command Not Found

   Ensure OpenSSL is installed and in your PATH.

2. Permission Denied When Creating Certificates

   Check that you have write permissions to the certificate directory.

3. Import Errors in Tests

   Make sure you're running tests from the project root directory.

Debugging

• Set the SSL_DEBUG=1 environment variable for verbose output
• Check the OpenSSL version with openssl version
• Verify certificate paths are correct and accessible