GHSA-CWV4-H3J5-W3CF: Root-cause XSS Fix for rama Directory Listings

Vulnerability

GHSA-CWV4-H3J5-W3CF describes stored and reflected cross-site scripting in rama's directory listing component when dynamic HTML file index pages are enabled. The vulnerable behavior is consistent with server-side generation of HTML from untrusted directory entry names and request-derived path data without context-appropriate output encoding.

The pre-patch implementation in open_file.rs collected filesystem and embedded directory entry names into DirEntry values and then passed them to generate_directory_html(entries, uri). In the vulnerable code shown by the commit, file names were obtained directly from the filesystem or embedded assets via to_string_lossy().to_string(), and no escaping is visible at the collection or rendering boundary in the old path. That creates both stored XSS via attacker-controlled filenames and reflected XSS via request path or breadcrumb rendering if those values are interpolated into HTML.

let file_name = entry.file_name();
let file_name_str = file_name.to_string_lossy().to_string();
...
entries.push(DirEntry::new(file_name_str, is_dir, modified, size));
...
let html = generate_directory_html(entries, uri);

The advisory and patch commit indicate the affected surface is specifically the HTML directory listing mode, not generic file serving. Relevant sources: patch commit, GitHub advisory, and report summary.

Patch

The patch restructures HTML directory listing into a dedicated feature-gated module, open_file_html.rs, and routes HTML listing requests through html::serve_html_listing(...). This is not just a refactor: the new module-level documentation explicitly states the intended security properties of the renderer.

//! Every untrusted value (file names, breadcrumb labels, the current
//! path) is routed through the `html!` macro family, which auto-escapes
//! via [`crate::html::IntoHtml::escape_and_write`]. Per-row `href`
//! values are constructed via [`rama_net::uri::Uri::path_mut`] so unsafe
//! bytes inside filenames are percent-encoded by the URI builder rather
//! than spliced into the attribute raw.

Two concrete remediation strategies are documented in the new file from the commit:

• HTML text content for untrusted values is auto-escaped through the framework's HTML rendering macros.
• href attribute values are built through URI mutation APIs so path segments are percent-encoded instead of concatenated as raw attribute text.

The patch also tightens feature handling around HTML listing mode. In mod.rs, parsing html-file-list now goes through a helper that returns an error when the html feature is disabled, preventing accidental configuration of an unavailable rendering path.

fn html_file_list_from_str() -> Result<DirectoryServeMode, OpaqueError> {
    #[cfg(feature = "html")]
    {
        Ok(DirectoryServeMode::HtmlFileList)
    }
    #[cfg(not(feature = "html"))]
    {
        Err(OpaqueError::from_static_str(
            "invalid DirectoryServeMode str: html file list requires html feature",
        ))
    }
}

Finally, HTML-specific response imports and logic are now consistently gated behind #[cfg(feature = "html")], reducing the chance of divergent behavior between build configurations.

Review

Pros

• The fix appears to address the actual sink: HTML generation of directory listings. That is the correct layer for XSS remediation.
• The new renderer documentation is security-specific and names both required protections: HTML escaping for text nodes and percent-encoding for link paths.
• Using framework HTML macros and URI builders is stronger than ad hoc string replacement because it aligns encoding with output context.
• The patch covers both filesystem-backed and embedded directory entries by preserving the same collection flow and centralizing rendering in one HTML module.
• Feature gating is improved so HTML listing mode cannot be silently selected when the HTML feature is absent.

Cons

• The provided diff excerpt is incomplete for the body of open_file_html.rs, so the review cannot directly verify every rendering call site or confirm there are no raw string concatenations elsewhere in the template.
• The patch documentation mentions escaping and URI encoding, but the review would benefit from explicit regression tests for filenames containing characters such as <, >, ", ', and path payloads that exercise breadcrumb rendering.
• It is not possible from the excerpt alone to confirm whether all HTML contexts are handled uniformly, especially if any values are inserted into attributes other than href, inline scripts, or style contexts.

Verdict

Root-cause.

Based on the commit summary and the new module's security-focused implementation notes, the patch appears to remediate the root cause by applying context-appropriate output encoding at render time for both visible HTML content and generated links. This is materially better than input filtering or blacklist-based sanitization and matches the vulnerability described in the advisory.

Residual risk is mainly verification risk, not design risk: because the excerpt does not include the full renderer body, engineers should still inspect the final HTML template and add regression tests around malicious filenames and request paths. If the implementation matches the documented use of html! escaping and URI path builders throughout, the fix should be considered complete for the reported stored and reflected XSS vectors.