firmitas 0.1.5a1

Simple notification service for X.509-standard TLS certificate statuses

firmitas

Simple notification service for X.509-standard TLS certificate statuses

__usage__

1. Clone the repository to your local storage and make it the present working directory.

   $ git clone https://gitlab.com/t0xic0der/firmitas.git
   

   $ cd firmitas
   

2. Ensure that uv and Virtualenv are installed and up-to-date on the system.

   $ sudo dnf install --assumeyes uv virtualenv
   

3. Create a virtual environment within the cloned local directory and enable it.

   $ virtualenv venv
   

   $ source venv/bin/activate
   

4. Install the project and its dependencies in the enabled virtual environment.

   (venv) $ uv sync --active
   

5. Make a copy of the project configuration file and make your changes to it.

   (venv) $ cp firmitas/conf/standard.py firmitas/conf/myconfig.py
   

   The project configuration file houses the following variables that can be modified according to the requirements of the project user.
   • repoloca - The location of the ticketing repository. This is required for source code forges that require the absolute location of the remote ticketing repository on Fedora Forge to be able to access the API and create notification tickets.
   • reponame - The name of the ticketing repository in the owner/repo format. This is required for the notification service to discover the remote ticketing repository on Fedora Forge to be able to access the API and create notification tickets.
   • username - The username to masquerade as in order to create notification tickets. This is required for the Forgejo instances that require the username with whom an API token is associated for the project to be authenticated on their behalf.
   • password - The password or API token belonging to the aforementioned username. This is required for the Forgejo instance that require the password associated with the above stated privileged user to authenticate the project on their behalf.
   • daysqant - The minimum number of days remaining from the validity expiry date to make notifications for. As a sane default, it is set to open up a notification ticket when the TLS certificate is 30 days away from its validation expiry date.
   • tagslist - The list of associated integer labels identifiers to the tag the notification tickets with. Administrators are required to first create the repository labels and then reference their integer identifier in the configuration file.
   • maxretry - The maximum number of retries to make when the process of opening up a notification ticket fails. As a sane default, it is set to allow up to 5 retries, and it is a good practice to have a value greater than one to compensate for spotty connections.
   • certloca - The location where the X.509 standard TLS certificates are stored. Note that this refers to a locally available storage location and not a remotely available storage location. The default is set as "/var/tmp/firmitas/certhere" directory.
   • hostloca - The location where the mapping file of service hostnames, maintainers, certificate statistics and notification statistics are stored. As with the previous configuration variable, even this one refers to a locally available storage location.
   • logrconf - The configuration variable that sets the logging behaviour for the project. As a sane default, the logging level has been set to "DEBUG" to allow for greater verbosity in details and a custom format to the console handler.
   • certdict - The global variable used across the project to share the details of the certificates to be probed into, the statistics of issuing authority, serial number, dates information and much more. Do not change it as this gets overridden.
6. Make a copy of the mapping configuration file and make your changes to it.

   (venv) $ cp firmitas/conf/certlist.yml firmitas/conf/mytlscts.yml
   

   The mapping configuration file houses a list of service hostnames having the following variables that can be either modified according to the requirements of the project user or computed by the project during its runtime.
   • path: The location of the X.509 standard TLS certificate file relative to the "certloca" variable previously set in the project configuration file. This helps the project to locate the X.509 standard TLS certificate file is read and acted upon.
   • user: The username on the Forgejo instance that was previously set on the "repoloca" variable in the project configuration file. If the username is not available on the Forgejo instance, the notification ticket creation process will error out.
   • certstat: This consists of a list of variables that must not be set manually as they would be overridden by the project during its runtime. Here is a list of those variables with their associated meanings and significance.
     • cstarted: A variable of boolean type. This is computed as TRUE if the current datetime is greater than the "not valid before" datetime of the stated X.509 standard TLS certificate and FALSE if the current datetime is lesser than the "not valid before" datetime of the same.
     • cstopped: A variable of boolean type. This is computed as TRUE if the current datetime is greater than the "not valid after" datetime of the stated X.509 standard TLS certificate and FALSE if the current datetime is less than the "not valid after" datetime of the same.
     • daystobt: A variable of integer type. This is computed as the difference in the number of days from the current datetime to the datetime from when the stated X.509 standard TLS certificate becomes valid. This can either be a positive integer if the "not valid before" datetime has not been reached or a negative integer if the "not valid before" datetime has been passed.
     • daystodd: A variable of integer type. This is computed as the difference in the number of days from the current datetime to the datetime to when the stated X.509 standard TLS certificate becomes expired. This can either be a positive integer if the "not valid after" datetime has not been reached or a negative integer if the "not valid after" datetime has been passed.
     • issuauth: A variable of string type. This stores the found name of the issuing authority for the stated X.509 standard TLS certificate. This can be useful if the same issuing authority is planned to be used to regenerate a new one from.
     • serialno: A variable of string type. This stores the found serial number of the stated X.509 standard TLS certificate. This can be useful to de-validate the existing certificate before opting in to regenerate a new one.
     • strtdate: A variable of datetime type. This is computed as the datetime data consisting of the "not valid before" datetime value.
     • stopdate: A variable of datetime type. This is computed as the datetime data consisting of the "not valid after" datetime value.
   • notistat: This consists of a list of variables that must not be set manually as they would be overridden by the project during its runtime. Here is a list of those variables with their associated meanings and significance.
     • done: A variable of boolean type. This stores the flag to state if the notification about the expiry of the stated X.509 standard TLS certificate has been made. The variable is set to TRUE if the notification has been created and FALSE otherwise.
     • link: A variable of string type. This stores the location of the notification ticket on Fedora Forge (or any other Forgejo instance, for that matter) as stated in the variables of the project configuration file.
     • time: A variable of datetime type. This stores the datetime information of when the previously stated notification ticket was created. This can be useful to track down if there are any repeated notifications made.
7. Make sure that the location of the custom mapping configuration file is pointed correctly at in the custom project configuration file.
8. View the console help menu of the project service by running the following command.

   (venv) $ uv run firmitas --help
   

   Output

   Usage: firmitas [OPTIONS]
   
   Options:
     -c, --conffile PATH  Read configuration from the specified Python file
     --version            Show the version and exit.
     --help               Show this message and exit.
   

9. With the configuration variables set appropriately, run the project service by executing the following command.

   (venv) $ uv run firmitas --conffile firmitas/conf/myconfig.py
   

   Refrain from making any changes in the existing entries of the mapping configuration file after the first successful run unless it is absolutely necessary to do so as the project service writes and references notification creation status from that file. Any unmonitored change to the existing entries in said file after the first successful run of the project service could lead to unintended consequences such as duplicate notification entries, untracked notification tickets pertaining to services etc.

__license__

This project is licensed under GNU General Public License 3.0 or later.