chore: Enhance documentation for E2E testing:

- Added clarity and structure to README files, including recent updates and getting started sections.
- Improved manual verification documentation for CrowdSec authentication, emphasizing expected outputs and success criteria.
- Updated debugging guide with detailed output examples and automatic trace capture information.
- Refined best practices for E2E tests, focusing on efficient polling, locator strategies, and state management.
- Documented triage report for DNS Provider feature tests, highlighting issues fixed and test results before and after improvements.
- Revised E2E test writing guide to include when to use specific helper functions and patterns for better test reliability.
- Enhanced troubleshooting documentation with clear resolutions for common issues, including timeout and token configuration problems.
- Updated tests README to provide quick links and best practices for writing robust tests.

Author: actions-user

ARCHITECTURE.md

@@ -30,16 +30,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - See [Notification Guide](docs/features/notifications.md) for setup instructions
 
 ### CI/CD
+
 - **Supply Chain**: Optimized verification workflow to prevent redundant builds
   - Change: Removed direct Push/PR triggers; now waits for 'Docker Build' via `workflow_run`
 
 ### Security
+
 - **Supply Chain**: Enhanced PR verification workflow stability and accuracy
   - **Vulnerability Reporting**: Eliminated false negatives ("0 vulnerabilities") by enforcing strict failure conditions
   - **Tooling**: Switched to manual Grype installation ensuring usage of latest stable binary
   - **Observability**: Improved debugging visibility for vulnerability scans and SARIF generation
 
 ### Performance
+
 - **E2E Tests**: Reduced feature flag API calls by 90% through conditional polling optimization (Phase 2)
   - Conditional skip: Exits immediately if flags already in expected state (~50% of cases)
   - Request coalescing: Shares in-flight API requests between parallel test workers
@@ -51,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Prevents timeout errors in Firefox/WebKit caused by strict label matching
 
 ### Fixed
+
 - **TCP Monitor Creation**: Fixed misleading form UX that caused silent HTTP 500 errors when creating TCP monitors
   - Corrected URL placeholder to show `host:port` format instead of the incorrect `tcp://host:port` prefix
   - Added dynamic per-type placeholder and helper text (HTTP monitors show a full URL example; TCP monitors show `host:port`)
@@ -72,6 +76,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Test Performance**: Reduced system settings test execution time by 31% (from 23 minutes to 16 minutes)
 
 ### Changed
+
 - **Testing Infrastructure**: Enhanced E2E test helpers with better synchronization and error handling
 - **CI**: Optimized E2E workflow shards [Reduced from 4 to 3]
 

CHANGELOG.md

@@ -45,8 +45,6 @@ brew install lefthook
 go install github.com/evilmartians/lefthook@latest
 ```
 
-
-
 ```bash
 # Option 1: Homebrew (macOS/Linux)
 brew install golangci-lint
@@ -84,17 +82,20 @@ For local development, install go 1.26.0+ from [go.dev/dl](https://go.dev/dl/).
 When the project's Go version is updated (usually by Renovate):
 
 1. **Pull the latest changes**
+
    ```bash
    git pull
    ```
 
 2. **Update your local Go installation**
+
    ```bash
    # Run the Go update skill (downloads and installs the new version)
    .github/skills/scripts/skill-runner.sh utility-update-go-version
    ```
 
 3. **Rebuild your development tools**
+
    ```bash
    # This fixes lefthook hook errors and IDE issues
    ./scripts/rebuild-go-tools.sh

CONTRIBUTING.md

@@ -94,6 +94,7 @@ services:
       retries: 3
       start_period: 40s
 ```
+
 > **Docker Socket Access:** Charon runs as a non-root user. If you mount the Docker socket for container discovery, the container needs permission to read it. Find your socket's group ID and add it to the compose file:
 >
 > ```bash
@@ -107,26 +108,34 @@ services:
 >       - "998"
 > ```
 
-### 2️⃣ Generate encryption key:
+### 2️⃣ Generate encryption key
+
 ```bash
 openssl rand -base64 32
 ```
-### 3️⃣ Start Charon:
+
+### 3️⃣ Start Charon
+
 ```bash
 docker-compose up -d
 ```
-### 4️⃣ Access the dashboard:
+
+### 4️⃣ Access the dashboard
+
 Open your browser and navigate to `http://localhost:8080` to access the dashboard and create your admin account.
+
 ```code
 http://localhost:8080
 ```
-### Getting Started:
-Full setup instructions and documentation are available at [https://wikid82.github.io/Charon/docs/getting-started.html](https://wikid82.github.io/Charon/docs/getting-started.html).
 
+### Getting Started
+
+Full setup instructions and documentation are available at [https://wikid82.github.io/Charon/docs/getting-started.html](https://wikid82.github.io/Charon/docs/getting-started.html).
 
 --- ## ✨ Top 10 Features
 
 ### 🎯 **Point & Click Management**
+
 No config files. No terminal commands. Just click, type your domain name, and you're live. If you can use a website, you can run Charon.
 
 ### 🔐 **Automatic HTTPS Certificates**
@@ -160,6 +169,7 @@ See exactly what's happening with live request logs, uptime monitoring, and inst
 ### 📥 **Migration Made Easy**
 
 Already invested in another reverse proxy? Bring your work with you by importing your existing configurations with one click:
+
 - **Caddyfile** — Migrate from other Caddy setups
 - **Nginx** — Import from Nginx based configurations (Coming Soon)
 - **Traefik** - Import from Traefik based configurations (Coming Soon)

README.md

@@ -41,16 +41,19 @@ container image. The binaries were compiled against Go 1.25.6, which contains th
 Charon's own application code, compiled with Go 1.26.1, is unaffected.
 
 **Who**
+
 - Discovered by: Automated scan (Grype)
 - Reported: 2026-03-20
 - Affects: CrowdSec Agent component within the container; not directly exposed through Charon's
   primary application interface
 
 **Where**
+
 - Component: CrowdSec Agent (bundled `cscli` and `crowdsec` binaries)
 - Versions affected: Charon container images with CrowdSec binaries compiled against Go < 1.25.7
 
 **When**
+
 - Discovered: 2026-03-20
 - Disclosed (if public): Not yet publicly disclosed
 - Target fix: When `golang:1.26.2-alpine` is published on Docker Hub
@@ -82,16 +85,19 @@ configuration includes the `DEFAULT` keyword, potentially allowing downgrade to
 suites. Affects Alpine 3.23.3 packages `libcrypto3` and `libssl3` at version 3.5.5-r0.
 
 **Who**
+
 - Discovered by: Automated scan (Grype)
 - Reported: 2026-03-20
 - Affects: Container runtime environment; Caddy reverse proxy TLS negotiation could be affected
   if default key group configuration is used
 
 **Where**
+
 - Component: Alpine 3.23.3 base image (`libcrypto3` 3.5.5-r0, `libssl3` 3.5.5-r0)
 - Versions affected: Alpine 3.23.3 prior to a patched `openssl` APK release
 
 **When**
+
 - Discovered: 2026-03-20
 - Disclosed (if public): 2026-03-13 (OpenSSL advisory)
 - Target fix: When Alpine Security publishes a patched `openssl` APK
@@ -103,7 +109,7 @@ does not use the `DEFAULT` keyword, which limits practical exploitability. The p
 present in the base image regardless of Caddy's configuration.
 
 **Planned Remediation**
-Monitor https://security.alpinelinux.org/vuln/CVE-2026-2673 for a patched Alpine APK. Once
+Monitor <https://security.alpinelinux.org/vuln/CVE-2026-2673> for a patched Alpine APK. Once
 available, update the pinned `ALPINE_IMAGE` digest in the Dockerfile, or add an explicit
 `RUN apk upgrade --no-cache libcrypto3 libssl3` to the runtime stage.
 
@@ -126,16 +132,19 @@ tracked separately above). All issues resolve when CrowdSec is rebuilt against G
 Charon's own application code is unaffected.
 
 **Who**
+
 - Discovered by: Automated scan (Trivy, Grype)
 - Reported: 2025-12-01 (original cluster); expanded 2026-03-20
 - Affects: CrowdSec Agent component within the container; not directly exposed through Charon's
   primary application interface
 
 **Where**
+
 - Component: CrowdSec Agent (bundled `cscli` and `crowdsec` binaries)
 - Versions affected: All Charon versions shipping CrowdSec binaries compiled against Go < 1.26.2
 
 **When**
+
 - Discovered: 2025-12-01
 - Disclosed (if public): Not yet publicly disclosed
 - Target fix: When `golang:1.26.2-alpine` is published on Docker Hub
@@ -168,16 +177,19 @@ loop with no termination condition when given a specially crafted input, causing
 (CWE-1284).
 
 **Who**
+
 - Discovered by: 7aSecurity audit (commissioned by OSTIF)
 - Reported: 2026-02-17
 - Affects: Any component in the container that calls `crc32_combine`-family functions with
   attacker-controlled input; not directly exposed through Charon's application interface
 
 **Where**
+
 - Component: Alpine 3.23.3 base image (`zlib` package, version 1.3.1-r2)
 - Versions affected: zlib < 1.3.2; all current Charon images using Alpine 3.23.3
 
 **When**
+
 - Discovered: 2026-02-17 (NVD published 2026-02-17)
 - Disclosed (if public): 2026-02-17
 - Target fix: When Alpine 3.23 publishes a patched `zlib` APK (requires zlib 1.3.2)
@@ -188,7 +200,7 @@ to the `crc32_combine`-family functions. This code path is not invoked by Charon
 or backend API. The vulnerability is non-blocking under the project's CI severity policy.
 
 **Planned Remediation**
-Monitor https://security.alpinelinux.org/vuln/CVE-2026-27171 for a patched Alpine APK. Once
+Monitor <https://security.alpinelinux.org/vuln/CVE-2026-27171> for a patched Alpine APK. Once
 available, update the pinned `ALPINE_IMAGE` digest in the Dockerfile, or add an explicit
 `RUN apk upgrade --no-cache zlib` to the runtime stage. Remove the `.trivyignore` entry at
 that time.
@@ -211,14 +223,17 @@ Seven HIGH-severity CVEs in Debian Trixie base image system libraries (`glibc`,
 available from the Debian Security Team.
 
 **Who**
+
 - Discovered by: Automated scan (Trivy)
 - Reported: 2026-02-04
 
 **Where**
+
 - Component: Debian Trixie base image (`libc6`, `libc-bin`, `libtasn1-6`, `libtiff`)
 - Versions affected: Charon container images built on Debian Trixie base (prior to Alpine migration)
 
 **When**
+
 - Discovered: 2026-02-04
 - Patched: 2026-03-20
 - Time to patch: 44 days
@@ -256,14 +271,17 @@ by CrowdSec for expression evaluation. Malicious regular expressions in CrowdSec
 parsers could cause CPU exhaustion and service degradation through exponential backtracking.
 
 **Who**
+
 - Discovered by: Automated scan (Trivy)
 - Reported: 2026-01-11
 
 **Where**
+
 - Component: CrowdSec (via `expr-lang/expr` dependency)
 - Versions affected: CrowdSec versions using `expr-lang/expr` < v1.17.7
 
 **When**
+
 - Discovered: 2026-01-11
 - Patched: 2026-01-11
 - Time to patch: 0 days

SECURITY.md

@@ -24,8 +24,10 @@ Example: `0.1.0-alpha`, `1.0.0-beta.1`, `2.0.0-rc.2`
 1. **Create and push a release tag**:
 
    ```bash
+
   git tag -a v1.0.0 -m "Release v1.0.0"
   git push origin v1.0.0
+
    ```
 
 2. **GitHub Actions automatically**:
@@ -51,10 +53,12 @@ Use it only when you need local/version-file parity checks:
   echo "1.0.0" > .version
    ```
 
-2. **Validate `.version` matches the latest tag**:
+1. **Validate `.version` matches the latest tag**:
 
    ```bash
+
   bash scripts/check-version-match-tag.sh
+
    ```
 
 ### Deterministic Rollout Verification Gates (Mandatory)

VERSION.md

@@ -53,6 +53,7 @@ logger.Infof("API Key: %s", apiKey)
 ```
 
 Charon's masking rules:
+
 - Empty: `[empty]`
 - Short (< 16 chars): `[REDACTED]`
 - Normal (≥ 16 chars): `abcd...xyz9` (first 4 + last 4)
@@ -68,6 +69,7 @@ if !validateAPIKeyFormat(apiKey) {
 ```
 
 Requirements:
+
 - Length: 16-128 characters
 - Charset: Alphanumeric + underscore + hyphen
 - No spaces or special characters
@@ -99,6 +101,7 @@ Rotate secrets regularly:
 ### What to Log
 
 ✅ **Safe to log**:
+
 - Timestamps
 - User IDs (not usernames if PII)
 - IP addresses (consider GDPR implications)
@@ -108,6 +111,7 @@ Rotate secrets regularly:
 - Performance metrics
 
 ❌ **Never log**:
+
 - Passwords or password hashes
 - API keys or tokens (use masking)
 - Session IDs (full values)
@@ -139,6 +143,7 @@ logger.Infof("Login attempt: username=%s password=%s", username, password)
 ### Log Aggregation
 
 If using external log services (CloudWatch, Splunk, Datadog):
+
 - Ensure logs are encrypted in transit (TLS)
 - Ensure logs are encrypted at rest
 - Redact sensitive data before shipping
@@ -333,6 +338,7 @@ limiter := rate.NewLimiter(rate.Every(36*time.Second), 100)
 ```
 
 **Critical endpoints** (require stricter limits):
+
 - Login: 5 attempts per 15 minutes
 - Password reset: 3 attempts per hour
 - API key generation: 5 per day
@@ -369,13 +375,15 @@ return c.JSON(401, gin.H{"error": "invalid API key: abc123"})
 **Applicable if**: Processing data of EU residents
 
 **Requirements**:
+
 1. **Data minimization**: Collect only necessary data
 2. **Purpose limitation**: Use data only for stated purposes
 3. **Storage limitation**: Delete data when no longer needed
 4. **Security**: Implement appropriate technical measures (encryption, masking)
 5. **Breach notification**: Report breaches within 72 hours
 
 **Implementation**:
+
 - ✅ Charon masks API keys in logs (prevents exposure of personal data)
 - ✅ Secure file permissions (0600) protect sensitive data
 - ✅ Log retention policies prevent indefinite storage
@@ -390,12 +398,14 @@ return c.JSON(401, gin.H{"error": "invalid API key: abc123"})
 **Applicable if**: Processing, storing, or transmitting credit card data
 
 **Requirements**:
+
 1. **Requirement 3.4**: Render PAN unreadable (encryption, masking)
 2. **Requirement 8.2**: Strong authentication
 3. **Requirement 10.2**: Audit trails
 4. **Requirement 10.7**: Retain audit logs for 1 year
 
 **Implementation**:
+
 - ✅ Charon uses masking for sensitive credentials (same principle for PAN)
 - ✅ Secure file permissions align with access control requirements
 - ⚠️ Charon doesn't handle payment cards directly (delegated to payment processors)
@@ -409,12 +419,14 @@ return c.JSON(401, gin.H{"error": "invalid API key: abc123"})
 **Applicable if**: SaaS providers, cloud services
 
 **Trust Service Criteria**:
+
 1. **CC6.1**: Logical access controls (authentication, authorization)
 2. **CC6.6**: Encryption of data in transit
 3. **CC6.7**: Encryption of data at rest
 4. **CC7.2**: Monitoring and detection (logging, alerting)
 
 **Implementation**:
+
 - ✅ API key validation ensures strong credentials (CC6.1)
 - ✅ File permissions (0600) protect data at rest (CC6.7)
 - ✅ Masked logging enables monitoring without exposing secrets (CC7.2)
@@ -429,12 +441,14 @@ return c.JSON(401, gin.H{"error": "invalid API key: abc123"})
 **Applicable to**: Any organization implementing ISMS
 
 **Key Controls**:
+
 1. **A.9.4.3**: Password management systems
 2. **A.10.1.1**: Cryptographic controls
 3. **A.12.4.1**: Event logging
 4. **A.18.1.5**: Protection of personal data
 
 **Implementation**:
+
 - ✅ API key format validation (minimum 16 chars, charset restrictions)
 - ✅ Key rotation procedures documented
 - ✅ Secure storage with file permissions (0600)
@@ -491,6 +505,7 @@ grep -i "api[_-]key\|token\|password" playwright-report/index.html
 **Recommended schedule**: Annual or after major releases
 
 **Focus areas**:
+
 1. Authentication bypass
 2. Authorization vulnerabilities
 3. SQL injection