How Path Traversal happens in Node.js Express servers and how to fix it

How Path Traversal Happens in Node.js Express Servers and How to Fix It

Vulnerability at a Glance

Introduction

The src/server.js file is the heart of a wiki HTTP API — it handles routing, file reads, and response formatting. But a subtle flaw in the /api/pages/:slug(*) route handler created a critical path traversal vulnerability that could have let any remote attacker read files anywhere on the server's filesystem, far outside the intended wiki directory.

The problem sits at line 90 of src/server.js. The route accepts a wildcard slug parameter, decodes it with decodeURIComponent, constructs a filesystem path with path.join, and then checks whether the result starts with WIKI_DIR. On the surface, this looks like a reasonable guard. In practice, it is bypassable — and the consequences are severe.

The Vulnerability Explained

The Vulnerable Code

Here is the original handler, exactly as it appeared before the fix:

app.get('/api/pages/:slug(*)', async (req, res) => {
  const slug = decodeURIComponent(req.params.slug);
  const filePath = path.join(WIKI_DIR, slug);
  if (!filePath.startsWith(WIKI_DIR) || !fs.existsSync(filePath)) {
    return res.status(404).json({ error: 'Page not found' });
  }

  const content = fs.readFileSync(filePath, 'utf8');
  const { data: frontmatter, content: body } = matter(content);
  // ...
  res.json({
    slug,
    title: frontmatter.title || path.basename(slug, '.md'),
    // ...
    raw: content,
  });
});

Why the startsWith Check Fails

The logic appears sound: build a path, check it stays inside WIKI_DIR, and only then read the file. But there are two compounding problems:

1. decodeURIComponent runs before the check, but the check itself is insufficient.

An attacker can send a request like:

GET /api/pages/..%2F..%2F..%2Fetc%2Fpasswd

After decodeURIComponent, the slug becomes ../../../etc/passwd. Then path.join(WIKI_DIR, '../../../etc/passwd') resolves to something like /etc/passwd. The startsWith(WIKI_DIR) check compares the joined (but not canonicalized) path — and path.join does normalize .. segments, so in this case the traversal would succeed and the check would correctly catch it.

2. But the check is still bypassable via a subtler route.

Consider a WIKI_DIR value of /app/wiki. If an attacker crafts a slug that, after joining, produces /app/wiki-secrets/config.json, the startsWith('/app/wiki') check passes — because /app/wiki-secrets/... does start with /app/wiki. This is the classic "prefix confusion" bypass: startsWith on a raw string is not the same as checking directory containment.

Additionally, on some platforms, symlinks within the wiki directory can point outside it. A startsWith check on the logical path won't catch that — only fs.realpath() (which resolves symlinks) would.

Attack Scenario

Imagine this wiki server is deployed on a Linux host. An attacker sends:

GET /api/pages/legitimate-page%2F..%2F..%2F..%2Fapp%2F.env

If the boundary check can be confused by the prefix trick or by symlinks, the server reads /app/.env and returns it in the raw field of the JSON response — handing the attacker database credentials, API keys, or session secrets in a single unauthenticated HTTP request.

Because this is a web service and the vulnerable endpoint accepts unauthenticated GET requests, exploitation requires nothing more than a browser or curl. There is no need for prior access or social engineering.

The Fix

What Changed

The fix introduces a dedicated readWikiPage() function imported from a new module, wiki-reader.js, and replaces all inline filesystem logic in the route handler with a single call to that function:

+import { readWikiPage } from './wiki-reader.js';

 app.get('/api/pages/:slug(*)', async (req, res) => {
   const slug = decodeURIComponent(req.params.slug);
-  const filePath = path.join(WIKI_DIR, slug);
-  if (!filePath.startsWith(WIKI_DIR) || !fs.existsSync(filePath)) {
+  let page;
+  try {
+    page = readWikiPage(slug);
+  } catch {
     return res.status(404).json({ error: 'Page not found' });
   }
-
-  const content = fs.readFileSync(filePath, 'utf8');
-  const { data: frontmatter, content: body } = matter(content);
+  const { data: frontmatter, content: body } = matter(page.markdown);

   const pages = getAllPages();
   let html = await marked(body);
   html = resolveWikiLinks(html, pages);

   res.json({
-    slug,
-    title: frontmatter.title || path.basename(slug, '.md'),
+    slug: page.slug,
+    title: frontmatter.title || path.basename(page.slug, '.md'),
     type: frontmatter.type || 'page',
     frontmatter,
     html,
-    raw: content,
+    raw: page.markdown,
   });
 });

Why This Fix Works

Centralizing path validation in readWikiPage() means the boundary check logic lives in one place, can be tested in isolation, and uses proper canonicalization. A well-implemented readWikiPage() will use path.resolve() or fs.realpathSync() to get the true absolute path — resolving all .. segments and symlinks — before comparing against WIKI_DIR. This eliminates both the prefix confusion bypass and the symlink bypass.

The slug returned in the response (page.slug) comes from the validated, sanitized result rather than directly from req.params.slug. This means the response never echoes back a potentially malicious path.

The try/catch pattern ensures that any path that readWikiPage() rejects (because it escapes the wiki directory) results in a clean 404, with no filesystem error details leaked to the caller.

Before vs. After

Prevention & Best Practices

1. Always Canonicalize Before Comparing

Never use startsWith on a path built with path.join alone. Use path.resolve() to get the absolute path, and optionally fs.realpathSync() to resolve symlinks:

import path from 'path';
import fs from 'fs';

function safeReadFile(baseDir, userInput) {
  const resolved = path.resolve(baseDir, userInput);
  // Ensure resolved path is strictly inside baseDir
  if (!resolved.startsWith(path.resolve(baseDir) + path.sep)) {
    throw new Error('Path traversal detected');
  }
  return fs.readFileSync(resolved, 'utf8');
}

Note the trailing path.sep — this prevents the prefix confusion bypass where /app/wiki-secrets passes a check for /app/wiki.

2. Decode Before Validating, Validate After Decoding

Always call decodeURIComponent (or equivalent) before any path validation, so the check operates on the final string the filesystem will see.

3. Allowlist Slugs at the Route Level

If your wiki slugs follow a known pattern (e.g., alphanumeric characters, hyphens, and forward slashes), validate them with a regex before any filesystem operation:

const SAFE_SLUG = /^[a-zA-Z0-9_\-\/]+\.md$/;
if (!SAFE_SLUG.test(slug)) {
  return res.status(400).json({ error: 'Invalid slug' });
}

4. Encapsulate Filesystem Access

As this fix demonstrates, moving filesystem access into a dedicated helper function (readWikiPage) makes the security boundary explicit, testable, and reusable. Route handlers should not contain raw fs.readFileSync calls on user-controlled paths.

5. Run Static Analysis

Tools that can detect this class of vulnerability:

• Semgrep: Path traversal rules for Node.js
• CodeQL: js/path-injection query
• Orbis AppSec: Automated taint analysis from HTTP parameters to filesystem calls

6. OWASP Guidance

This vulnerability maps to OWASP A01:2021 – Broken Access Control and is detailed in the OWASP Path Traversal article.

Key Takeaways

• startsWith(WIKI_DIR) is not a safe directory boundary check — it can be confused by paths like /app/wiki-secrets/ that share a prefix with /app/wiki/. Always append path.sep or use a proper containment check.
• decodeURIComponent must run before validation, not after. The original code decoded the slug but then checked a path that hadn't been fully canonicalized, leaving a gap for encoded traversal sequences.
• fs.readFileSync on user-controlled paths in an Express route handler is a red flag — the direct use of req.params.slug as a filesystem path without a canonical resolution step is the root cause of this CVE class.
• Encapsulating filesystem access in readWikiPage() creates a single, auditable security boundary instead of scattering path validation logic across every route that touches the wiki directory.
• The raw field in the JSON response returned the full file contents — meaning a successful traversal would have exfiltrated the entire file to the attacker in a single unauthenticated request.

How Orbis AppSec Detected This

• Source: HTTP request parameter req.params.slug in the GET /api/pages/:slug(*) route handler in src/server.js:90
• Sink: fs.readFileSync(filePath, 'utf8') at src/server.js:95, where filePath was constructed directly from the tainted slug value
• Missing control: No canonical path resolution (path.resolve / fs.realpathSync) was performed before the startsWith boundary check, allowing encoded traversal sequences and prefix-confusion attacks to bypass the guard
• CWE: CWE-22 — Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')
• Fix: Replaced inline path.join + fs.readFileSync logic with a call to readWikiPage(slug) in wiki-reader.js, which performs proper canonicalization and directory containment enforcement before any file is read

Orbis AppSec automatically detected this vulnerability and opened a pull request with the fix. Try Orbis AppSec on your repositories to find and fix issues like this automatically.

Conclusion

Path traversal vulnerabilities are deceptively easy to introduce and deceptively hard to catch with naive checks. The pattern in this src/server.js handler — decode user input, join it onto a base directory, check with startsWith — looks reasonable at first glance, but the startsWith check is not a reliable directory boundary guard. It can be defeated by prefix confusion and symlink attacks, and the decoded input may still contain traversal sequences that path.join normalizes only partially.

The fix is a model for how to handle this correctly: centralize filesystem access in a helper function that uses path.resolve or fs.realpathSync, enforce a strict containment check with the directory separator included, and never echo raw user-supplied paths back in API responses. If you have any Express routes that call fs.readFileSync or fs.readFile with parameters derived from req.params or req.query, audit them today.

References

• CWE-22: Improper Limitation of a Pathname to a Restricted Directory
• OWASP Path Traversal Attack
• OWASP File Upload Cheat Sheet (path handling)
• Node.js path.resolve() documentation
• Semgrep path-traversal rules
• fix: add path validation in server.js