lightsail-wordpress-migrator 1.0.0__py3-none-any.whl

lightsail_wordpress_migrator-1.0.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: lightsail-wordpress-migrator
+Version: 1.0.0
+Summary: Automated migration tool for upgrading AWS Lightsail Bitnami WordPress instances to modern Amazon Linux 2023 / Debian Lightsail blueprints.
+Author: Jonathan Glass
+License: MIT
+Project-URL: Homepage, https://github.com/jonathanbglass/lightsail-wordpress-migrator
+Project-URL: Repository, https://github.com/jonathanbglass/lightsail-wordpress-migrator.git
+Project-URL: Issues, https://github.com/jonathanbglass/lightsail-wordpress-migrator/issues
+Keywords: aws,lightsail,wordpress,bitnami,migration,cloudwatch,fail2ban,devops
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: paramiko>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# 🚀 AWS Lightsail WordPress Migrator
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+An automated migration tool designed to upgrade legacy **Bitnami WordPress** Amazon Lightsail instances to modern **Amazon Linux 2023 / Debian Native Lightsail Blueprints** (`wordpress_ls_1_0`).
+
+---
+
+## 📖 The Problem
+
+AWS Lightsail deprecated its legacy Bitnami WordPress blueprint in favor of a modern native stack running Debian/AL2023 with systemd, native MariaDB, and standard Apache. 
+
+Migrating manually is painful and error-prone because:
+1. **Incompatible Directory Layouts**: Legacy Bitnami uses `/opt/bitnami/...` and `ctlscript.sh`, whereas native instances use standard `/var/www/html` and `systemctl`.
+2. **Database Collation Incompatibilities**: MySQL 8.0 exports using `utf8mb4_0900_ai_ci` fail on target MariaDB databases without translation.
+3. **Apache Permalinks / `.htaccess` 404s**: Bitnami disables `.htaccess` runtime reading by default. When migrating to native Apache, missing `.htaccess` files break all subpages and return `404 Not Found`.
+4. **Dynamic Firewall Restrictions**: Managing temporary port 22 access without leaving SSH open permanently to `0.0.0.0/0`.
+5. **No IAM Instance Profiles on Lightsail**: Streaming server and application logs to CloudWatch requires provisioning dedicated minimal IAM credentials.
+
+**Lightsail WordPress Migrator automates this entire lifecycle with zero manual database editing.**
+
+---
+
+## ✨ Features
+
+- 🔄 **Full End-to-End Migration**: Automates database dump, `wp-content` archival, target instance provisioning, and data import.
+- ⚡ **Direct S3 Transfer**: Uses presigned S3 URLs so high-volume assets transfer directly between Lightsail instances without routing through your local laptop.
+- 🛡️ **Zero-Exposure Firewall Automation**: Dynamically opens port 22 for the runner's exact `/32` public IP, and **guarantees closure** via `finally` blocks upon completion or failure.
+- 🌐 **Automated Static IP Cutover (`--reassign-static-ip`)**: Automatically discovers static IPs attached to the source, reassigns them to the target upon completion, and updates WordPress URLs for seamless DNS cutover.
+- 🔧 **Collation Translation**: Automatically converts MySQL 8 collations (`utf8mb4_0900_ai_ci` / `utf8mb4_0900_as_cs`) to MariaDB-compatible `utf8mb4_unicode_520_ci`.
+- 📄 **Automatic `.htaccess` Generation**: Configures standard WordPress rewrite rules and `www-data` ownership to ensure flawless subpage permalink routing.
+- 🔒 **Optional Security Hardening (`--harden-security`)**:
+  - **Fail2ban**: Deploys jails for SSH brute-force (`sshd`), WordPress login/XML-RPC defense (`apache-wplogin`), and vulnerability probe/traversal blocking (`apache-scanprobe`).
+  - **Apache Availability Hardening**: Deploys timeout and keepalive limits to protect small instances from slowloris / connection exhaustion attacks.
+- 📊 **Optional CloudWatch Ingestion (`--cloudwatch`)**: Provisions a dedicated least-privilege IAM user and configures `amazon-cloudwatch-agent` to stream Apache access/error logs, PHP-FPM, WordPress debug logs, and Fail2ban logs.
+- 🔍 **Interactive Discovery & Dry-Run Mode**: Discovers running Lightsail instances and validates credentials, disk space, static IPs, and SSH keys before making any changes.
+
+---
+
+## 🛠️ Architecture
+
+```
+                                  ┌──────────────────────────┐
+                                  │      S3 Staging Bucket   │
+                                  │  (Presigned Direct Link) │
+                                  └─────────────▲────────────┘
+                                                │
+                          1. Export DB & Assets │ 2. Direct S3 Pull
+                                                │
+┌───────────────────────────────┐               │              ┌───────────────────────────────┐
+│     Source Lightsail Host     │───────────────┴─────────────▶│     Target Lightsail Host     │
+│   (Legacy Bitnami / MySQL)    │                              │  (Native AL2023/Debian/Maria) │
+│                               │                              │                               │
+│ • Bitnami stack detection     │                              │ • Collation normalization     │
+│ • Database dump via socket/TCP│                              │ • Apache .htaccess generation │
+│ • wp-content tarball          │                              │ • File permissions (www-data) │
+│ • Pre-migration snapshot      │                              │ • Static IP cutover           │
+│ • Attached Static IP discovery│                              │ • Fail2ban & Security tuning  │
+└───────────────────────────────┘                              │ • CloudWatch Logs agent       │
+                                                               └───────────────────────────────┘
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+#### Option A: Clone & Run (Zero install)
+```bash
+git clone https://github.com/jonathanbglass/lightsail-wordpress-migrator.git
+cd lightsail-wordpress-migrator
+pip install boto3 paramiko
+```
+
+#### Option B: Install via pip
+```bash
+pip install .
+```
+
+---
+
+### 2. Usage
+
+#### Interactive Mode (Recommended)
+If you don't pass arguments, the migrator interactively lists your instances, checks for attached static IPs, and prompts for confirmation:
+```bash
+python migrate.py
+# or if installed via pip:
+lightsail-wp-migrate
+```
+
+#### CLI One-Liner (Non-Interactive with Static IP Reassignment)
+```bash
+python migrate.py \
+  --source "MyWordPressBitnami" \
+  --target "MyWordPress-Native" \
+  --profile default \
+  --region us-east-1 \
+  --reassign-static-ip \
+  --harden-security \
+  --cloudwatch \
+  --yes
+```
+
+#### Safe Dry-Run (Pre-flight validation)
+```bash
+python migrate.py \
+  --source "MyWordPressBitnami" \
+  --target "MyWordPress-Native" \
+  --dry-run
+```
+
+---
+
+## ⚙️ CLI Options Reference
+
+| Flag | Default | Description |
+| :--- | :--- | :--- |
+| `--source`, `-s` | `None` | Name of existing Bitnami Lightsail instance (prompted if omitted). |
+| `--target`, `-t` | `<source>-2` | Name of target Lightsail instance. |
+| `--profile`, `-p` | `$AWS_PROFILE` or `default` | AWS CLI credential profile. |
+| `--region`, `-r` | `$AWS_DEFAULT_REGION` or `us-east-1` | AWS region. |
+| `--source-key` | Auto-discovered in `~/.ssh` | Path to source SSH private key (`.pem`). |
+| `--target-key` | Source key | Path to target SSH private key (`.pem`). |
+| `--bundle-id` | `nano_3_0` | Lightsail bundle size (e.g. `nano_3_0`, `micro_3_0`, `small_3_0`). |
+| `--s3-bucket` | Auto-derived | S3 bucket for staging transfer artifacts. |
+| `--snapshot / --no-snapshot` | `True` | Create a pre-migration snapshot of source. |
+| `--reassign-static-ip` | `False` | Automatically detach static IP from source and attach to target upon migration completion. |
+| `--static-ip` | `Auto-detect` | Explicit name of Lightsail Static IP to reassign. |
+| `--harden-security / --no-harden-security` | `True` | Install and configure Fail2ban and Apache availability protections. |
+| `--cloudwatch` | `False` | Provision IAM user and stream logs to CloudWatch. |
+| `--dry-run` | `False` | Test credentials, inspect instances, and verify static IPs without making changes. |
+| `--yes`, `-y` | `False` | Skip interactive confirmation prompts. |
+| `--verbose`, `-v` | `False` | Enable debug logging output. |
+
+---
+
+## 🔒 Security Hardening Details
+
+When `--harden-security` is enabled (default), the following defenses are provisioned on the target:
+
+1. **Fail2ban Jails (`/etc/fail2ban/jail.local`)**:
+   - `sshd`: Systemd backend, max 5 retries, 1-hour ban.
+   - `apache-wplogin`: Rate limits `wp-login.php` and `xmlrpc.php` brute force (max 8 attempts in 5 mins -> 1-hour ban).
+   - `apache-scanprobe`: Blocks automated vulnerability scanners querying `.env`, `.git`, `wp-config.php`, `phpmyadmin`, or directory traversal (5 attempts -> 6-hour ban).
+2. **Apache Availability Limits (`/etc/apache2/conf-available/availability-hardening.conf`)**:
+   - Caps `Timeout 60`, `KeepAliveTimeout 2`, and `MaxKeepAliveRequests 50` to safeguard low-memory / 2 vCPU Lightsail instances from connection exhaustion.
+
+---
+
+## 📋 Post-Migration Checklist
+
+After migration completes:
+
+1. **Verify Website & Permalinks**: Open `http://<TARGET_IP_OR_STATIC_IP>` and click several subpages to confirm `.htaccess` routing works.
+2. **Verify WordPress Admin**: Log into `http://<TARGET_IP_OR_STATIC_IP>/wp-admin` to confirm all plugins, themes, and media uploads are present.
+3. **DNS & Static IP**:
+   - If `--reassign-static-ip` was used, the static IP is already attached to the new target. Ensure your DNS `A` records point to it.
+   - Otherwise, attach a static IP in the AWS Lightsail console and update DNS.
+4. **Issue Free SSL via Let's Encrypt**:
+   Once your domain resolves to the new instance, run standard Certbot:
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y certbot python3-certbot-apache
+   sudo certbot --apache
+   ```
+5. **Retire Old Instance**: Once verified, stop or delete the old Bitnami instance.
+
+---
+
+## 🧪 Testing
+
+Run the test suite with Python's built-in `unittest` runner:
+```bash
+python -m unittest discover -s tests
+```
+
+Or with `pytest`:
+```bash
+pytest tests/
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

lightsail_wordpress_migrator-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+lightsail_wordpress_migrator-1.0.0.dist-info/licenses/LICENSE,sha256=yE-kQmyQHsUPEPu35lKlL3RxREDFJc_jRG90eeYKnS4,1071
+lightsail_wp_migrate/__init__.py,sha256=Qu4LMWYHneRbEXpvLR-th0AWnajJi2wdJVfwu9N0JCA,230
+lightsail_wp_migrate/aws.py,sha256=Stw8xJjKL6ovQtyjxD54DOfxUYeFecaiiNkzX4T6w5o,14815
+lightsail_wp_migrate/cli.py,sha256=YDVv5bOLFyhBYM_pqPjG3z0sfFImZs3wcn-sN20rdZs,9758
+lightsail_wp_migrate/orchestrator.py,sha256=TbdD6nM5HMgJ5deoojsKlnXccqr6tKcIxQsnTCfEE4o,14939
+lightsail_wp_migrate/security.py,sha256=rJ4fxpCoNbmEUCL5ZkVAtFneByt-5aR3PtxIbP7xPWI,3686
+lightsail_wp_migrate/ssh.py,sha256=1UaA1wnShL2kqhkJwQwsiE2sNHNZ-4qQHH3uTVlfgiU,3779
+lightsail_wp_migrate/utils.py,sha256=Mo1Hm7IAn9X6jIt_7csoAmdaNPskXkhybWRPrPOrGEA,1968
+lightsail_wp_migrate/wordpress.py,sha256=bYeYiBbuiM1rlDbkHX2JPDTga1pxKUtYUXaT4yT7p_w,5676
+lightsail_wordpress_migrator-1.0.0.dist-info/METADATA,sha256=_SsikXdEw7PN-Q2ScbnU8Xn08rJkm_mMy2eKGPSWxR8,11607
+lightsail_wordpress_migrator-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+lightsail_wordpress_migrator-1.0.0.dist-info/entry_points.txt,sha256=xm9InEEYGH2cCVUrqL8xQcwCQHRTgk2ih0-Vfodj__g,71
+lightsail_wordpress_migrator-1.0.0.dist-info/top_level.txt,sha256=9SRli7g5gPsHtMUb-uV45P9ccKmvWJdUkdX0aTMb0Xs,21
+lightsail_wordpress_migrator-1.0.0.dist-info/RECORD,,

lightsail_wordpress_migrator-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lightsail_wordpress_migrator-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lightsail-wp-migrate = lightsail_wp_migrate.cli:main

lightsail_wordpress_migrator-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Glass
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lightsail_wordpress_migrator-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lightsail_wp_migrate

lightsail_wp_migrate/__init__.py

@@ -0,0 +1,8 @@
+"""
+lightsail-wordpress-migrator
+Automated migration tool for upgrading AWS Lightsail Bitnami WordPress instances
+to modern Amazon Linux 2023 / Debian Lightsail blueprints.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Jonathan Glass"

lightsail_wp_migrate/aws.py

@@ -0,0 +1,357 @@
+"""
+AWS resource automation: Lightsail, S3, IAM, and CloudWatch.
+"""
+
+import time
+import json
+import logging
+import ipaddress
+import tempfile
+import os
+import boto3
+from typing import List, Dict, Any, Optional, Tuple
+from .ssh import run_remote, sftp_put
+
+log = logging.getLogger("lightsail-wp-migrate")
+
+
+class AWSManager:
+    def __init__(self, profile: Optional[str] = None, region: str = "us-east-1"):
+        self.profile = profile
+        self.region = region
+        self.session = boto3.Session(profile_name=profile, region_name=region)
+        self.ls = self.session.client("lightsail")
+        self.s3 = self.session.client("s3")
+        self.iam = self.session.client("iam")
+        self.sts = self.session.client("sts")
+
+    def get_account_id(self) -> str:
+        return self.sts.get_caller_identity()["Account"]
+
+    def list_wordpress_instances(self) -> List[Dict[str, Any]]:
+        """List all Lightsail instances in the region."""
+        resp = self.ls.get_instances()
+        return resp.get("instances", [])
+
+    def get_instance(self, instance_name: str) -> Dict[str, Any]:
+        resp = self.ls.get_instance(instanceName=instance_name)
+        return resp["instance"]
+
+    def get_instance_ip(self, instance_name: str) -> str:
+        inst = self.get_instance(instance_name)
+        ip = inst.get("publicIpAddress")
+        if not ip:
+            raise RuntimeError(f"Instance '{instance_name}' has no public IP assigned.")
+        return ip
+
+    def list_static_ips(self) -> List[Dict[str, Any]]:
+        resp = self.ls.get_static_ips()
+        return resp.get("staticIps", [])
+
+    def get_static_ip_for_instance(self, instance_name: str) -> Optional[Dict[str, Any]]:
+        """Find static IP attached to a given instance."""
+        for sip in self.list_static_ips():
+            if sip.get("isAttached") and sip.get("attachedTo") == instance_name:
+                return sip
+        return None
+
+    def reassign_static_ip(self, static_ip_name: str, target_instance_name: str) -> str:
+        """Detach static IP from current instance and attach to target instance."""
+        log.info("🌐 Reassigning Static IP '%s' to target instance '%s' ...", static_ip_name, target_instance_name)
+        try:
+            self.ls.detach_static_ip(staticIpName=static_ip_name)
+            time.sleep(3)
+        except Exception as e:
+            log.warning("Notice while detaching static IP: %s", e)
+
+        self.ls.attach_static_ip(staticIpName=static_ip_name, instanceName=target_instance_name)
+        time.sleep(3)
+
+        # Look up IP address
+        for sip in self.list_static_ips():
+            if sip["name"] == static_ip_name:
+                ip_addr = sip.get("ipAddress", "")
+                log.info("Static IP '%s' (%s) successfully attached to '%s'.", static_ip_name, ip_addr, target_instance_name)
+                return ip_addr
+
+        return ""
+
+    def is_ssh_open_for(self, instance_name: str, my_cidr: str) -> bool:
+        my_net = ipaddress.ip_network(my_cidr, strict=False)
+        ports = self.ls.get_instance_port_states(instanceName=instance_name).get("portStates", [])
+        for rule in ports:
+            if not (rule.get("fromPort") <= 22 <= rule.get("toPort")):
+                continue
+            if rule.get("protocol") not in ("tcp", "all"):
+                continue
+            if rule.get("state") != "open":
+                continue
+            for cidr in rule.get("cidrs", []):
+                try:
+                    if my_net.subnet_of(ipaddress.ip_network(cidr, strict=False)):
+                        return True
+                except Exception:
+                    continue
+        return False
+
+    def open_ssh_firewall(self, instance_name: str, cidr: str) -> bool:
+        if self.is_ssh_open_for(instance_name, cidr):
+            log.info("Port 22 on '%s' is already open for %s.", instance_name, cidr)
+            return False
+        log.info("Opening port 22 on '%s' for %s ...", instance_name, cidr)
+        self.ls.open_instance_public_ports(
+            instanceName=instance_name,
+            portInfo={
+                "fromPort": 22,
+                "toPort": 22,
+                "protocol": "tcp",
+                "cidrs": [cidr],
+            },
+        )
+        return True
+
+    def close_ssh_firewall(self, instance_name: str, cidr: str, was_opened: bool) -> None:
+        if not was_opened:
+            return
+        log.info("Closing port 22 on '%s' for %s ...", instance_name, cidr)
+        try:
+            self.ls.close_instance_public_ports(
+                instanceName=instance_name,
+                portInfo={
+                    "fromPort": 22,
+                    "toPort": 22,
+                    "protocol": "tcp",
+                    "cidrs": [cidr],
+                },
+            )
+        except Exception as exc:
+            log.warning("Could not close port 22 on '%s': %s", instance_name, exc)
+
+    def create_snapshot(self, instance_name: str, snapshot_name: Optional[str] = None) -> str:
+        name = snapshot_name or f"{instance_name}-pre-migration-{int(time.time())}"
+        log.info("📸 Creating pre-migration snapshot '%s' ...", name)
+        self.ls.create_instance_snapshot(
+            instanceName=instance_name,
+            instanceSnapshotName=name,
+        )
+        return name
+
+    def create_target_instance(
+        self,
+        instance_name: str,
+        availability_zone: str,
+        blueprint_id: str = "wordpress_ls_1_0",
+        bundle_id: str = "nano_3_0",
+        key_pair_name: str = "LightsailDefaultKeyPair",
+    ) -> None:
+        try:
+            existing = self.ls.get_instance(instanceName=instance_name)
+            state = existing["instance"]["state"]["name"]
+            log.info("Target instance '%s' already exists (state=%s). Skipping creation.", instance_name, state)
+            return
+        except self.ls.exceptions.NotFoundException:
+            pass
+
+        log.info("🚀 Creating native Lightsail instance '%s' (%s, %s)...", instance_name, blueprint_id, bundle_id)
+        self.ls.create_instances(
+            instanceNames=[instance_name],
+            availabilityZone=availability_zone,
+            blueprintId=blueprint_id,
+            bundleId=bundle_id,
+            keyPairName=key_pair_name,
+        )
+
+    def wait_for_instance(self, instance_name: str, target_state: str = "running", timeout: int = 600, poll: int = 10) -> None:
+        log.info("Waiting for '%s' to reach '%s' state ...", instance_name, target_state)
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            resp = self.ls.get_instance(instanceName=instance_name)
+            state = resp["instance"]["state"]["name"]
+            if state == target_state:
+                log.info("Instance '%s' is now %s.", instance_name, state)
+                return
+            time.sleep(poll)
+        raise TimeoutError(f"Timed out waiting for instance '{instance_name}' to reach '{target_state}'.")
+
+    def ensure_s3_bucket(self, bucket_name: str) -> None:
+        try:
+            self.s3.head_bucket(Bucket=bucket_name)
+        except Exception:
+            log.info("Creating S3 staging bucket '%s' in %s ...", bucket_name, self.region)
+            if self.region == "us-east-1":
+                self.s3.create_bucket(Bucket=bucket_name)
+            else:
+                self.s3.create_bucket(
+                    Bucket=bucket_name,
+                    CreateBucketConfiguration={"LocationConstraint": self.region},
+                )
+
+    def get_presigned_put_url(self, bucket: str, key: str, expires_in: int = 3600) -> str:
+        return self.s3.generate_presigned_url("put_object", Params={"Bucket": bucket, "Key": key}, ExpiresIn=expires_in)
+
+    def get_presigned_get_url(self, bucket: str, key: str, expires_in: int = 3600) -> str:
+        return self.s3.generate_presigned_url("get_object", Params={"Bucket": bucket, "Key": key}, ExpiresIn=expires_in)
+
+    def setup_cloudwatch_agent(
+        self,
+        ssh_tgt: Any,
+        instance_name: str,
+        log_group_prefix: str,
+        retention_days: int = 14,
+        include_fail2ban: bool = False,
+    ) -> None:
+        """Provision dedicated IAM user and install CloudWatch agent on target instance."""
+        log.info("📊 Setting up CloudWatch Logs agent on target instance ...")
+        prefix = log_group_prefix.rstrip("/")
+
+        # 1. Install agent
+        run_remote(
+            ssh_tgt,
+            "if ! dpkg -l amazon-cloudwatch-agent &>/dev/null; then "
+            "wget -q https://s3.amazonaws.com/amazoncloudwatch-agent/debian/amd64/latest/amazon-cloudwatch-agent.deb -O /tmp/cwa.deb && "
+            "sudo dpkg -i /tmp/cwa.deb && rm /tmp/cwa.deb; "
+            "else echo 'CloudWatch agent already installed'; fi",
+        )
+
+        # 2. Config JSON
+        collect_list = [
+            {
+                "file_path": "/var/log/apache2/access.log",
+                "log_group_name": f"{prefix}/apache/access",
+                "log_stream_name": instance_name,
+                "timestamp_format": "[%d/%b/%Y:%H:%M:%S %z]",
+                "retention_in_days": retention_days,
+            },
+            {
+                "file_path": "/var/log/apache2/error.log",
+                "log_group_name": f"{prefix}/apache/error",
+                "log_stream_name": instance_name,
+                "timestamp_format": "[%a %b %d %H:%M:%S.%f %Y]",
+                "retention_in_days": retention_days,
+            },
+            {
+                "file_path": "/var/www/html/wp-content/debug.log",
+                "log_group_name": f"{prefix}/wordpress/debug",
+                "log_stream_name": instance_name,
+                "timestamp_format": "%Y-%m-%d %H:%M:%S",
+                "retention_in_days": retention_days,
+            },
+            {
+                "file_path": "/var/log/syslog",
+                "log_group_name": f"{prefix}/os/syslog",
+                "log_stream_name": instance_name,
+                "timestamp_format": "%b %d %H:%M:%S",
+                "retention_in_days": retention_days,
+            },
+            {
+                "file_path": "/var/log/auth.log",
+                "log_group_name": f"{prefix}/os/auth",
+                "log_stream_name": instance_name,
+                "timestamp_format": "%b %d %H:%M:%S",
+                "retention_in_days": retention_days,
+            },
+        ]
+        if include_fail2ban:
+            collect_list.append({
+                "file_path": "/var/log/fail2ban.log",
+                "log_group_name": f"{prefix}/fail2ban",
+                "log_stream_name": instance_name,
+                "timestamp_format": "%Y-%m-%d %H:%M:%S,%f",
+                "retention_in_days": retention_days,
+            })
+
+        agent_config = {
+            "agent": {"run_as_user": "root", "region": self.region},
+            "logs": {
+                "logs_collected": {"files": {"collect_list": collect_list}},
+                "log_stream_name": "default",
+                "force_flush_interval": 15,
+            },
+        }
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            json.dump(agent_config, f, indent=2)
+            tmp_json = f.name
+        sftp_put(ssh_tgt, tmp_json, "/tmp/cwa_config.json")
+        os.unlink(tmp_json)
+        run_remote(
+            ssh_tgt,
+            "sudo mkdir -p /opt/aws/amazon-cloudwatch-agent/etc && "
+            "sudo mv /tmp/cwa_config.json /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json",
+        )
+
+        # 3. Dedicated IAM user
+        iam_user = f"wp-logs-{instance_name}"[:64]
+        try:
+            self.iam.create_user(UserName=iam_user)
+            log.info("Created dedicated IAM user '%s'.", iam_user)
+        except self.iam.exceptions.EntityAlreadyExistsException:
+            log.info("IAM user '%s' already exists; reusing.", iam_user)
+
+        policy_doc = json.dumps({
+            "Version": "2012-10-17",
+            "Statement": [
+                {
+                    "Effect": "Allow",
+                    "Action": [
+                        "logs:CreateLogGroup",
+                        "logs:CreateLogStream",
+                        "logs:PutLogEvents",
+                        "logs:DescribeLogStreams",
+                        "logs:PutRetentionPolicy",
+                    ],
+                    "Resource": f"arn:aws:logs:{self.region}:*:log-group:{prefix}*:*",
+                },
+                {"Effect": "Allow", "Action": "logs:DescribeLogGroups", "Resource": "*"},
+            ],
+        })
+        self.iam.put_user_policy(UserName=iam_user, PolicyName="CloudWatchLogsWrite", PolicyDocument=policy_doc)
+
+        keys = self.iam.list_access_keys(UserName=iam_user)["AccessKeyMetadata"]
+        if len(keys) >= 2:
+            oldest = sorted(keys, key=lambda k: k["CreateDate"])[0]
+            self.iam.delete_access_key(UserName=iam_user, AccessKeyId=oldest["AccessKeyId"])
+
+        new_key = self.iam.create_access_key(UserName=iam_user)["AccessKey"]
+        time.sleep(10)  # IAM eventual consistency
+
+        creds_content = (
+            "[AmazonCloudWatchAgent]\n"
+            f"aws_access_key_id = {new_key['AccessKeyId']}\n"
+            f"aws_secret_access_key = {new_key['SecretAccessKey']}\n"
+            f"region = {self.region}\n"
+        )
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".ini", delete=False) as f:
+            f.write(creds_content)
+            tmp_creds = f.name
+        sftp_put(ssh_tgt, tmp_creds, "/tmp/aws_creds.ini")
+        os.unlink(tmp_creds)
+        run_remote(
+            ssh_tgt,
+            "sudo mkdir -p /root/.aws && "
+            "sudo mv /tmp/aws_creds.ini /root/.aws/credentials && "
+            "sudo chmod 600 /root/.aws/credentials",
+        )
+
+        common_cfg = (
+            "[credentials]\n"
+            "  shared_credential_profile = \"AmazonCloudWatchAgent\"\n"
+            "  shared_credential_file = \"/root/.aws/credentials\"\n"
+        )
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".toml", delete=False) as f:
+            f.write(common_cfg)
+            tmp_cfg = f.name
+        sftp_put(ssh_tgt, tmp_cfg, "/tmp/common-config.toml")
+        os.unlink(tmp_cfg)
+        run_remote(ssh_tgt, "sudo mv /tmp/common-config.toml /opt/aws/amazon-cloudwatch-agent/etc/common-config.toml")
+
+        # 4. Start agent
+        run_remote(
+            ssh_tgt,
+            "sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl "
+            "-a fetch-config -m onPremise "
+            "-c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json -s 2>&1",
+            check=False,
+        )
+        run_remote(ssh_tgt, "sudo systemctl enable amazon-cloudwatch-agent", check=False)
+        log.info("CloudWatch Logs agent configured and enabled.")