Filesystem Security

Filesystem security

When to use this skill

Use this skill whenever code touches the filesystem with paths derived from input:

• Building a file path from $_GET / $_POST / $_REQUEST.
• include, require, readfile, file_get_contents, or unlink of a dynamic file.
• Serving downloads, exports, or logs based on a request parameter.
• Deleting files selected by the user.
• Using WP_Filesystem for writes, deletes, or directory creation.

Path traversal and local file inclusion are high-impact WordPress vulnerabilities — ../../wp-config.php or a malicious uploaded .php can expose secrets or achieve RCE.

Related: see the file-upload-security skill for $_FILES handling and the object-injection-deserialization skill for uploaded data formats.

Core principles (and why they matter)

1. Never include / require a user-controlled path. That is remote/local code execution. Keep templates and includes hardcoded.
2. Constrain every file operation to a known base directory. Resolve with realpath() and assert the result starts with the allowed base path.
3. validate_file() catches traversal, drive letters, and : characters. A non-zero return value means the path is suspect.
4. Use sanitize_file_name() and wp_normalize_path(). Normalize separators and strip dangerous characters before building paths.
5. Use WordPress deletion helpers. wp_delete_file() and wp_delete_file_from_directory() are safer than raw unlink().
6. Use WP_Filesystem for writes. It handles permissions, credentials, and stream wrappers consistently across hosts.

Step-by-step implementation

1. Reject any request that wants to include/require a file based on input; use a hardcoded allowlist of template files instead.
2. For read/delete handlers:
   • Verify nonce + capability.
   • Sanitize the filename with sanitize_file_name().
   • Optionally run validate_file().
   • Build the target path under a known base directory.
   • Resolve with realpath() and confirm it stays under the base.
3. For writes/deletes, prefer WP_Filesystem with request_filesystem_credentials().
4. Never expose the full server path in errors or URLs.

Supporting references

Common AI mistakes / anti-patterns

Mistake 1 — include $_GET['page']

// ❌ Insecure: local/remote code execution.
include 'templates/' . $_GET['page'] . '.php';

// ✅ Secure: hardcoded allowlist of template files.
$allowed = array( 'dashboard', 'settings', 'logs' );
$page    = isset( $_GET['page'] ) ? sanitize_key( $_GET['page'] ) : 'dashboard';
if ( ! in_array( $page, $allowed, true ) ) {
    wp_die( esc_html__( 'Invalid page.', 'my-plugin' ), 400 );
}
include __DIR__ . '/templates/' . $page . '.php';

Mistake 2 — unlink() of a user-named file

// ❌ Insecure: arbitrary file deletion via traversal.
unlink( WP_CONTENT_DIR . '/exports/' . $_POST['file'] );

// ✅ Secure: sanitize, resolve, and confine to the base directory.
$base    = realpath( WP_CONTENT_DIR . '/exports' );
$request = sanitize_file_name( wp_unslash( $_POST['file'] ?? '' ) );
$target  = realpath( $base . '/' . $request );

if ( false === $target || strpos( $target, $base . DIRECTORY_SEPARATOR ) !== 0 ) {
    wp_die( esc_html__( 'Invalid file.', 'my-plugin' ), 400 );
}

if ( ! current_user_can( 'manage_options' ) ) {
    wp_die( esc_html__( 'Forbidden.', 'my-plugin' ), 403 );
}

wp_delete_file( $target );

Mistake 3 — readfile() without base-directory containment

// ❌ Insecure: ../../wp-config.php is reachable.
readfile( '/var/www/uploads/' . $_GET['file'] );

// ✅ Secure: resolve and confine.
$base    = realpath( wp_upload_dir()['basedir'] );
$request = sanitize_file_name( wp_unslash( $_GET['file'] ?? '' ) );
$target  = realpath( $base . '/' . $request );

if ( false === $target || strpos( $target, $base . DIRECTORY_SEPARATOR ) !== 0 ) {
    wp_die( esc_html__( 'Invalid file.', 'my-plugin' ), 400 );
}

readfile( $target );

Mistake 4 — Trusting basename() alone

// ❌ Insecure: basename does not prevent traversal to siblings.
$file = basename( $_GET['file'] );
readfile( '/var/www/uploads/' . $file );

// ✅ Secure: basename plus realpath containment.
$base    = realpath( '/var/www/uploads' );
$file    = basename( sanitize_file_name( wp_unslash( $_GET['file'] ?? '' ) ) );
$target  = realpath( $base . '/' . $file );
if ( false === $target || strpos( $target, $base . DIRECTORY_SEPARATOR ) !== 0 ) {
    wp_die( esc_html__( 'Invalid file.', 'my-plugin' ), 400 );
}
readfile( $target );

Mistake 5 — Writing files with raw PHP functions

// ❌ Insecure: no permission/credential handling, may fail on restrictive hosts.
file_put_contents( $path, $data );

// ✅ Secure: use WP_Filesystem after requesting credentials.
function my_plugin_write_file( $path, $data ) {
    global $wp_filesystem;

    if ( ! function_exists( 'request_filesystem_credentials' ) ) {
        require_once ABSPATH . 'wp-admin/includes/file.php';
    }

    $url   = admin_url( 'admin-post.php?action=my_plugin_save' );
    $creds = request_filesystem_credentials( $url );
    if ( false === $creds || ! WP_Filesystem( $creds ) ) {
        return new WP_Error( 'filesystem', __( 'Could not initialize filesystem.', 'my-plugin' ) );
    }

    return $wp_filesystem->put_contents( $path, $data, FS_CHMOD_FILE );
}

Correct code examples

A complete safe file download/delete helper using base-directory containment is in references/secure-filesystem-operations.php.

Checklist

• No include / require uses user input; templates are selected from a hardcoded allowlist.
• File paths are built under a known base directory.
• realpath() resolves the final path and containment is verified.
• Filenames pass through sanitize_file_name() and wp_normalize_path().
• validate_file() returns 0 for paths that include user input.
• File delete operations use wp_delete_file() or wp_delete_file_from_directory().
• File writes use WP_Filesystem with request_filesystem_credentials().
• State-changing handlers verify nonce + capability first.
• Full server paths are not exposed in errors or URLs.

Official references

• validate_file()
• wp_normalize_path()
• sanitize_file_name()
• wp_delete_file()
• wp_delete_file_from_directory()
• WP_Filesystem
• request_filesystem_credentials()
• wp_mkdir_p()
• realpath()
• OWASP — Path Traversal