Certicopter

A lightweight application to renew your SSL certificates in an automated fashion

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Setup
   • Usage
   • Recurring Renewal
   • Configuration
3. Documentation
4. Roadmap
5. Contribution
6. Contact
7. Acknowledgments
8. License

About The Project

Managing SSL certificates manually across multiple systems is time-consuming, error-prone, and can lead to service outages if certificates expire unexpectedly. This tool is designed to automate SSL certificate renewal across various environments, ensuring that your applications and services remain secure and compliant without the hassle of manual intervention.

By supporting multiple systems, it simplifies certificate management for developers, sysadmins, and DevOps teams alike.

• Prevent downtime due to expired certificates
• Maintain strong HTTPS security standards
• Save time with reliable automation
• Standardize renewal workflows across different platforms
• Centralized management certificates and logging
• No SPOF due to wildcard certificates (each instance get's a unique domain specific certificate)
• Easily scalable

(back to top)

Built With

• 
• 

Integrated systems

• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

Follow these steps to get the tool up and running:

Prerequisites

1. System Requirements

   • Python v3.13 or higher
   • Docker Engine v28.1.1 or higher
   • Git v2.49.0 or higher
   • GNU Bash v5.2.0 or higher

2. System Access

   • Access to target systems
   • API tokens or credentials for authentication
   • Windows RDS: a domain account with RDS deployment management rights (for Set-RDCertificate over WinRM)
   • Rubrik Security Cloud (*_rsc providers): an RSC service account (RSC_* credentials)

⚠️ Important: Certicopter does not provide built-in interfaces for resolving or securing credentials. All sensitive information - such as passwords, usernames, domain names, API tokens, and similar - is expected to be supplied via environment variables. The mechanism responsible for storing and providing these environment variables must be maintained by the user.

As part of the guided setup, users receive a template tailored to their requirements. This template includes a checklist of the necessary environment variables but does not handle their the provisioning or secure storage.

3. Network Requirements
   • HTTPS/HTTP access to target systems
   • DNS resolution for target domains
   • Port access (varies by system and your configuration, typically 80, 443, 8443, 9440, 9443; Windows RDS uses WinRM 5985)

Setup

1. Clone the repository

   git clone https://github.com/amanoxsolutions/certicopter.git

2. Execute the setup.sh file

• Open Git Bash and navigate to the project folder

  cd PathTo/certicopter
  ./setup.sh

⚠️ Important: If you encounter an error while trying to execute one of the shell scripts mentioned above, you may need to modify its execution permissions. As an example:

chmod +x setup.sh

If you encounter syntax errors while executing the script, it's likely due to using the wrong shell. Always open and run the script in the Git Bash shell to avoid such errors.

3. Enter all necessary information

   • DNS hosting provider (only those that are offered from Certbot -> DNS Plugins)
   • Notification email address
   • Save certificates locally or not
   • Systems used
   • Instances per system

4. Create the necessary environment variables in your secrets manager depending on your internal architecture

   • Use the env_template.env file created by the setup.sh
   • The environment variables on your side must match those in the template for the script to correctly resolve the values

📌 If you do not have a dedicated infrastructure or system for securely storing and managing your credentials (and providing them as environment variables), you can create a .env file. Then, add the 'env_file' tag to the docker-compose.yml file to use this method.

5. Enable Hosting Provider Plugin
   • Go to the SSL_Certificate_App/requirements.txt and activate the plugin depending on what hosting provider you have chosen
   • To activate it, remove the # in front of your certbot-dns-exampleprovider

Usage

1. Guided Execution (recommended)

• Execute the run.sh file in the project directory

  ./run.sh

2. Docker Standalone Execution

   docker compose up --build

📌 Set CERTICOPTER_TEST_CERT=true to issue certificates against the Let's Encrypt staging environment (untrusted, no rate limits) while testing your setup.

Recurring Renewal

To ensure your SSL certificates are automatically renewed before they expire, you should set up a recurring task (we suggest performing this in a monthly fashion). Here are the recommended approaches as examples:

1. Using a Cron Job
   • Edit your crontab: crontab -e
   • Add a monthly job:

     0 0 1 * * /path/to/certicopter/run.sh --noninteractive

📌 The above command executes the shell script on a monthly basis at midnight without the need for manual interaction.

2. Using Windows Task Scheduler
   • Open Task Scheduler
   • Create a new Task
   • Set the trigger to Monthly
   • Select all months
   • Set day to 1
   • Start time: 00:00
   • Action: Start a program
   • Program/script: C:\Program Files\Git\bin\bash.exe
   • Add arguments: -c "/c/User/path/to/certicopter/run.sh --noninteractive"

⚠️ Important:

• Ensure the scheduling interval is less than your certificate validity period (< 90 days)
• Monitor the logs for successful renewals
• Test the renewal process manually before setting up automation

(back to top)

Configuration

The application uses a JSON-based configuration file (config.json) with the following example structure (generated automatically with the guided setup process):

{
  "certicopter_global_settings": {
    "hosting_provider": "example_provider",
    "notification_email": "example.email@example.com",
    "save_certificates": "y"
  },
  "providers": {
    "nutanix|paloalto|vsphere|hycu|vamax|rds|rubrik_rsc|nutanix_rsc": {
      "instances": [
        {
          "domain_env_var": "PROVIDER_INSTANCE_1_DOMAIN",
          "username_env_var": "PROVIDER_INSTANCE_1_USERNAME",
          "password_env_var": "PROVIDER_INSTANCE_1_PASSWORD"
        },
        {
          "domain_env_var": "PROVIDER_INSTANCE_2_DOMAIN",
          "username_env_var": "PROVIDER_INSTANCE_2_USERNAME",
          "password_env_var": "PROVIDER_INSTANCE_2_PASSWORD"
        }
      ]
    }
  }  
}

📌 The exact *_env_var keys depend on the provider — e.g. paloalto uses api_token/username/password/passphrase, rds uses connection_broker/username/password/pfx_passphrase, and rubrik_rsc uses cluster_name. The guided setup writes the correct keys per provider into env_template.env.

The rubrik_rsc and nutanix_rsc providers additionally require the global Rubrik Security Cloud credentials RSC_CLIENT_ID, RSC_CLIENT_SECRET, RSC_ACCESS_TOKEN_URI, RSC_GRAPHQL_URL (read directly from the environment, not per instance).

(back to top)

Documentation

Documentation for this project can be found in the docs/ directory:

• app_architecture - Explanation how the application in general and it's components work
• coding_guidelines.md - Coding standards and best practices
• enpoints.md - API documentation and endpoints
• common_errors.md - List of most common errors that can happen during execution
• rds_provider.md - Windows Remote Desktop Services provider (WinRM / CredSSP / Set-RDCertificate)
• rsc_providers.md - Rubrik Security Cloud providers (rubrik_rsc appliance web cert + nutanix_rsc Prism Central → Rubrik, GraphQL)

Additional documentation is available in the code comments and docstrings. The main README provides only a high-level overview of the project.

(back to top)

Roadmap

• Initial release with basic functionality
• Support for multiple systems
• Automated certificate renewal
• Basic error handling and logging
• Basic testing coverage
• CI/CD pipeline
• Additional system integrations (Windows RDS, Rubrik Security Cloud)

(back to top)

Contribution

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/NewFeature)
3. Commit your Changes (git commit -m 'Added a new feature')
4. Push to the Branch (git push origin feature/NewFeature)
5. Open a Pull Request

(back to top)

Contact

Axians Amanox AG - Website - opensource@amanox.ch

Project Link: https://github.com/amanoxsolutions/certicopter

(back to top)

Acknowledgments

• Let's Encrypt
• Certbot

(back to top)

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

(back to top)