feat: add UFW firewall configuration step

- Add ConfigureFirewall variant to ConfigureStep enum
- Create configure-firewall.yml.tera template with SSH port variable
- Add ssh_port field to InventoryContext for template rendering
- Create ConfigureFirewallStep in application layer
- Add firewall template rendering to AnsibleTemplateRenderer
- Integrate firewall step into ConfigureCommandHandler
- Update module exports for new firewall step

Co-authored-by: josecelano <[email protected]>

Author: Copilot

src/application/command_handlers/configure/handler.rs

@@ -8,7 +8,8 @@ use super::errors::ConfigureCommandHandlerError;
 use crate::adapters::ansible::AnsibleClient;
 use crate::application::command_handlers::common::StepResult;
 use crate::application::steps::{
-    ConfigureSecurityUpdatesStep, InstallDockerComposeStep, InstallDockerStep,
+    ConfigureFirewallStep, ConfigureSecurityUpdatesStep, InstallDockerComposeStep,
+    InstallDockerStep,
 };
 use crate::domain::environment::repository::{EnvironmentRepository, TypedEnvironmentRepository};
 use crate::domain::environment::state::{ConfigureFailureContext, ConfigureStep};
@@ -24,6 +25,7 @@ use crate::shared::error::Traceable;
 /// 1. Install Docker
 /// 2. Install Docker Compose
 /// 3. Configure automatic security updates
+/// 4. Configure UFW firewall
 ///
 /// # State Management
 ///
@@ -161,6 +163,11 @@ impl ConfigureCommandHandler {
             .execute()
             .map_err(|e| (e.into(), current_step))?;
 
+        let current_step = ConfigureStep::ConfigureFirewall;
+        ConfigureFirewallStep::new(Arc::clone(&self.ansible_client))
+            .execute()
+            .map_err(|e| (e.into(), current_step))?;
+
         // Transition to Configured state
         let configured = environment.clone().configured();
 

src/application/steps/mod.rs

@@ -36,7 +36,7 @@ pub use rendering::{
     RenderAnsibleTemplatesError, RenderAnsibleTemplatesStep, RenderOpenTofuTemplatesStep,
 };
 pub use software::{InstallDockerComposeStep, InstallDockerStep};
-pub use system::{ConfigureSecurityUpdatesStep, WaitForCloudInitStep};
+pub use system::{ConfigureFirewallStep, ConfigureSecurityUpdatesStep, WaitForCloudInitStep};
 pub use validation::{
     ValidateCloudInitCompletionStep, ValidateDockerComposeInstallationStep,
     ValidateDockerInstallationStep,

src/application/steps/system/configure_firewall.rs

@@ -0,0 +1,136 @@
+//! UFW firewall configuration step
+//!
+//! This module provides the `ConfigureFirewallStep` which handles configuration
+//! of UFW (Uncomplicated Firewall) on remote hosts via Ansible playbooks.
+//! This step ensures that the firewall is configured with restrictive default
+//! policies while maintaining SSH access to prevent lockout.
+//!
+//! ## Key Features
+//!
+//! - Configures UFW with restrictive default policies (deny incoming, allow outgoing)
+//! - Preserves SSH access on the configured port
+//! - Uses Tera template for dynamic SSH port resolution
+//! - Comprehensive SSH lockout prevention measures
+//! - Verification steps to ensure firewall is active and SSH is accessible
+//!
+//! ## Configuration Process
+//!
+//! The step executes the "configure-firewall" Ansible playbook which handles:
+//! - UFW installation and setup
+//! - Reset UFW to clean state
+//! - Set restrictive default policies
+//! - Allow SSH access BEFORE enabling firewall (critical for preventing lockout)
+//! - Enable UFW firewall
+//! - Verify firewall status and SSH access
+//!
+//! ## SSH Lockout Prevention
+//!
+//! This is a **high-risk operation** that could result in SSH lockout if not
+//! handled correctly. Safety measures include:
+//!
+//! 1. **Correct Sequencing**: SSH rules are added BEFORE enabling firewall
+//! 2. **Dual SSH Protection**: Both port-specific and service-name rules
+//! 3. **Port Configuration**: Uses actual SSH port from user configuration
+//! 4. **Verification Steps**: Ansible tasks verify SSH access is preserved
+//! 5. **Comprehensive Logging**: Detailed logging of each firewall step
+
+use std::sync::Arc;
+use tracing::{info, instrument, warn};
+
+use crate::adapters::ansible::AnsibleClient;
+use crate::shared::command::CommandError;
+
+/// Step that configures UFW firewall on a remote host via Ansible
+///
+/// This step configures a restrictive UFW firewall policy while ensuring
+/// SSH access is maintained. The SSH port is resolved during template rendering
+/// and embedded in the final Ansible playbook. The configuration follows the
+/// principle of "allow SSH BEFORE enabling firewall" to prevent lockout.
+pub struct ConfigureFirewallStep {
+    ansible_client: Arc<AnsibleClient>,
+}
+
+impl ConfigureFirewallStep {
+    /// Create a new firewall configuration step
+    ///
+    /// # Arguments
+    ///
+    /// * `ansible_client` - Ansible client for running playbooks
+    ///
+    /// # Note
+    ///
+    /// SSH port configuration is resolved during template rendering phase,
+    /// not at step execution time. The rendered playbook contains the
+    /// resolved SSH port value.
+    #[must_use]
+    pub fn new(ansible_client: Arc<AnsibleClient>) -> Self {
+        Self { ansible_client }
+    }
+
+    /// Execute the firewall configuration
+    ///
+    /// # Safety
+    ///
+    /// This method is designed to prevent SSH lockout by:
+    /// 1. Resetting UFW to clean state
+    /// 2. Allowing SSH access BEFORE enabling firewall
+    /// 3. Using the correct SSH port from user configuration
+    ///
+    /// The SSH port is resolved during template rendering and embedded in the
+    /// playbook, so this method executes a playbook with pre-configured values.
+    ///
+    /// # Errors
+    ///
+    /// Returns `CommandError` if:
+    /// - Ansible playbook execution fails
+    /// - UFW commands fail
+    /// - SSH rules cannot be applied
+    /// - Firewall verification fails
+    #[instrument(
+        name = "configure_firewall",
+        skip_all,
+        fields(
+            step_type = "system",
+            component = "firewall",
+            method = "ansible"
+        )
+    )]
+    pub fn execute(&self) -> Result<(), CommandError> {
+        warn!(
+            step = "configure_firewall",
+            action = "configure_ufw",
+            "Configuring UFW firewall - CRITICAL: SSH access will be restricted to configured port"
+        );
+
+        // Run Ansible playbook (SSH port already resolved during template rendering)
+        self.ansible_client.run_playbook("configure-firewall")?;
+
+        info!(
+            step = "configure_firewall",
+            status = "success",
+            "UFW firewall configured successfully with SSH access preserved"
+        );
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+    use std::sync::Arc;
+
+    use super::*;
+
+    #[test]
+    fn it_should_create_configure_firewall_step() {
+        let ansible_client = Arc::new(AnsibleClient::new(PathBuf::from("test_inventory.yml")));
+        let step = ConfigureFirewallStep::new(ansible_client);
+
+        // Test that the step can be created successfully
+        assert_eq!(
+            std::mem::size_of_val(&step),
+            std::mem::size_of::<Arc<AnsibleClient>>()
+        );
+    }
+}

src/application/steps/system/mod.rs

@@ -7,16 +7,18 @@
  * Current steps:
  * - Cloud-init completion waiting
  * - Automatic security updates configuration
+ * - UFW firewall configuration
  *
  * Future steps may include:
  * - User account setup and management
- * - Firewall configuration
  * - Log rotation configuration
  * - System service management
  */
 
+pub mod configure_firewall;
 pub mod configure_security_updates;
 pub mod wait_cloud_init;
 
+pub use configure_firewall::ConfigureFirewallStep;
 pub use configure_security_updates::ConfigureSecurityUpdatesStep;
 pub use wait_cloud_init::WaitForCloudInitStep;

src/domain/environment/state/configure_failed.rs

@@ -47,6 +47,8 @@ pub enum ConfigureStep {
     InstallDockerCompose,
     /// Configuring automatic security updates
     ConfigureSecurityUpdates,
+    /// Configuring UFW firewall
+    ConfigureFirewall,
 }
 
 /// Error state - Application configuration failed

src/infrastructure/external_tools/ansible/template/renderer/mod.rs

@@ -198,6 +198,15 @@ impl AnsibleTemplateRenderer {
             .render(inventory_context, &build_ansible_dir)
             .map_err(|source| ConfigurationTemplateError::InventoryRenderingFailed { source })?;
 
+        // Render dynamic firewall playbook template with SSH port variable
+        self.render_tera_template(
+            "configure-firewall.yml.tera",
+            "configure-firewall.yml",
+            inventory_context,
+            &build_ansible_dir,
+        )
+        .await?;
+
         // Copy static Ansible files (config and playbooks)
         self.copy_static_templates(&self.template_manager, &build_ansible_dir)
             .await?;
@@ -372,6 +381,87 @@ impl AnsibleTemplateRenderer {
         tracing::debug!("Successfully copied static file {}", file_name);
         Ok(())
     }
+
+    /// Renders a Tera template with the provided context
+    ///
+    /// # Arguments
+    ///
+    /// * `template_name` - Name of the template file (e.g., "configure-firewall.yml.tera")
+    /// * `output_name` - Name of the output file (e.g., "configure-firewall.yml")
+    /// * `context` - Template context for variable substitution
+    /// * `destination_dir` - Directory where the rendered file will be written
+    ///
+    /// # Returns
+    ///
+    /// * `Result<(), ConfigurationTemplateError>` - Success or error from the template rendering operation
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - Template file cannot be found or read
+    /// - Template content is invalid
+    /// - Variable substitution fails
+    /// - Output file cannot be written
+    async fn render_tera_template(
+        &self,
+        template_name: &str,
+        output_name: &str,
+        context: &InventoryContext,
+        destination_dir: &Path,
+    ) -> Result<(), ConfigurationTemplateError> {
+        tracing::debug!("Rendering Tera template: {}", template_name);
+
+        let template_path = Self::build_template_path(template_name);
+
+        // Get the template file path
+        let source_path = self
+            .template_manager
+            .get_template_path(&template_path)
+            .map_err(|source| ConfigurationTemplateError::TemplatePathFailed {
+                file_name: template_name.to_string(),
+                source,
+            })?;
+
+        // Read template content
+        let template_content = tokio::fs::read_to_string(&source_path)
+            .await
+            .map_err(|source| ConfigurationTemplateError::TeraTemplateReadFailed {
+                file_name: template_name.to_string(),
+                source,
+            })?;
+
+        // Create File object for template processing
+        let template_file =
+            crate::domain::template::file::File::new(template_name, template_content).map_err(
+                |source| ConfigurationTemplateError::FileCreationFailed {
+                    file_name: template_name.to_string(),
+                    source,
+                },
+            )?;
+
+        // Render template with context
+        let mut engine = crate::domain::template::TemplateEngine::new();
+        let rendered_content = engine
+            .render(template_file.filename(), template_file.content(), context)
+            .map_err(|source| ConfigurationTemplateError::InventoryTemplateCreationFailed {
+                source,
+            })?;
+
+        // Write rendered content to output file
+        let output_path = destination_dir.join(output_name);
+        crate::domain::template::write_file_with_dir_creation(&output_path, &rendered_content)
+            .map_err(|source| ConfigurationTemplateError::InventoryTemplateRenderFailed {
+                source,
+            })?;
+
+        tracing::debug!(
+            "Successfully rendered Tera template {} to {}",
+            template_name,
+            output_path.display()
+        );
+
+        Ok(())
+    }
 }
 
 #[cfg(test)]

src/infrastructure/external_tools/ansible/template/wrappers/inventory/context/mod.rs

@@ -42,6 +42,9 @@ pub struct InventoryContext {
     ansible_host: AnsibleHost,
     ansible_ssh_private_key_file: SshPrivateKeyFile,
     ansible_port: AnsiblePort,
+    /// Alias for ansible_port used in playbook templates
+    #[serde(rename = "ssh_port")]
+    ssh_port: AnsiblePort,
 }
 
 /// Builder for `InventoryContext` with fluent interface
@@ -103,6 +106,7 @@ impl InventoryContextBuilder {
             ansible_host,
             ansible_ssh_private_key_file,
             ansible_port,
+            ssh_port: ansible_port, // Same value for playbook templates
         })
     }
 }
@@ -123,6 +127,7 @@ impl InventoryContext {
             ansible_host,
             ansible_ssh_private_key_file,
             ansible_port,
+            ssh_port: ansible_port, // Same value for playbook templates
         })
     }