The Complete Production SOP: How to Deploy and Run Path Traversal Defense & Canonical Path Sanitizer in Autonomous AI Agents

---
name: "path-traversal-canonical-sanitizer"
description: "Prevent unauthorized file system access by strictly validating and canonicalizing paths."
metadata:
  author: "OWASP"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "prevent path traversal"
  - "sanitize file download path"
  - "validate path stays in base directory"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Path Traversal Defense & Canonical Path Sanitizer

Defends file serving and download endpoints against directory traversal attacks (../): resolving canonical realpaths, validating paths stay within root base directories, and stripping null bytes.

## Execution SOP & Rules
1. Resolve target path to absolute canonical path using path.resolve() or os.path.realpath().
2. Verify canonical path starts with base directory: resolvedPath.startsWith(baseDirectory + path.sep).
3. Reject or strip directory separator characters (/ and \) from filenames intended for storage.
4. Use random UUIDs or database IDs on the filesystem rather than user-provided filenames.

import path from 'node:path';
import fs from 'node:fs';

export function resolveSafePath(baseDir: string, untrustedPath: string): string {
  const safeBase = path.resolve(baseDir);
  const resolved = path.resolve(safeBase, untrustedPath);
  
  // Ensure base boundary with platform-specific separator to prevent prefix collision
  if (!resolved.startsWith(safeBase + path.sep) && resolved !== safeBase) {
    throw new Error('ACCESS_DENIED: Path traversal detected');
  }

  // Check realpath to defeat symlink bypasses if file/dir exists
  if (fs.existsSync(resolved)) {
    const canonical = fs.realpathSync(resolved);
    if (!canonical.startsWith(safeBase + path.sep) && canonical !== safeBase) {
      throw new Error('ACCESS_DENIED: Symlink traversal detected');
    }
    return canonical;
  }

  return resolved;
}

import { describe, it, expect } from 'vitest';
import { resolveSafePath } from '../src/utils/safePath';
import path from 'node:path';

describe('resolveSafePath Traversal Defense', () => {
  const base = path.resolve('tmp/storage');

  it('should allow valid relative paths within base directory', () => {
    const target = resolveSafePath(base, 'reports/2026/report.pdf');
    expect(target).toBe(path.join(base, 'reports/2026/report.pdf'));
  });

  it('should reject dot-dot directory traversal', () => {
    expect(() => resolveSafePath(base, '../../etc/passwd')).toThrow('ACCESS_DENIED');
  });

  it('should reject sibling directory prefix collision', () => {
    // tmp/storage vs tmp/storage_confidential
    expect(() => resolveSafePath(base, '../storage_confidential/secret.key')).toThrow('ACCESS_DENIED');
  });
});