[WordPress] 外掛開發安全性指南 – 上架外掛前必須通過的考驗

本篇文章更新時間：2023/03/25
如有資訊過時或語誤之處，歡迎使用 Contact 功能通知。
一介資男的 LINE 社群開站囉！歡迎入群聊聊～
如果本站內容對你有幫助，歡迎使用 BFX Pay 加密貨幣 或 新台幣 贊助支持。

看過前兩篇 [WordPress] 外掛開發入門指南 與 [WordPress] 外掛基礎知識篇 – 外掛開發者都需要來讀一次的文件 後

恭喜你，你的程式碼可運作！但是它是否安全呢？

WordPress 開發團隊嚴謹看待安全性。在網站設計中，安全性有極大的重要性，因此安全性也是必須要關注的核心。儘管核心開發人員已經有一個專門團隊專注保護平台安全，但是像你這樣的主題或外掛開發人員也很清楚，核心外部可能存在許多潛在的漏洞。由於 WordPress 提供了很多功能和靈活性，外掛和主題成了最容易被攻擊的點。

當程式碼在數百，甚至數千個網站上執行時，你應該特別小心處理輸入 WordPress 的資料以及它如何呈現給最終使用者。這個安全性問題通常在你建立的主題設定頁面、建立使用短碼或儲存和顯示與文章相關的額外資料時出現。

發展安全意識

開發時，考量新功能的安全性是非常重要的。開發過程中請使用以下原則：

• 不要相信任何資料。 不要相信用戶輸入、第三方 API 或資料庫中的資料而沒有驗證。保護你的 WordPress 主題，確保進入和離開你的主題的資料是正確的。在使用者輸入資料之前，必須進行 驗證 和 清理(sanitize)，輸出時進行編碼逸出轉譯(escape)。
• 使用 WordPress API。 許多 WordPress 核心功能提供了內建驗證和清理資料的功能。當可能發生安全性問題時，應使用 WordPress 提供的功能。
• 保持更新。 隨著技術的進步，外掛或主題中新的安全漏洞也可能隨之而來。保持警惕，透過維護你的程式碼並在必要時更新來避免安全風險。

引導原則

1. 永遠不要相信使用者輸入的資料。
2. 盡可能地進行逸出轉譯(Escape)。
3. 逸出轉譯(Escape) 所有來自不可信的來源（例如資料庫和使用者）、第三方（例如 Twitter）等。
4. 絕不要假設任何事情，驗證它。
5. 進行清理(Sanitation)輸入資料，但是驗證或拒絕是更好的做法。

檢查使用者權限（Capabilities）

如果你的外掛允許使用者提交資料，無論是在後台管理還是前端操作，都應該檢查用戶權限。

使用者角色與權限

架構高效安全層級最重要的一步是設置用戶權限系統。WordPress 透過『使用者角色與權限』（User Roles and Capabilities）功能實現了這一點。

每個登入到 WordPress 的使用者根據其使用者角色會自動被分配指定的使用者權限。

「使用者角色(User roles)」只是一種描述使用者所屬群組的方式。每個群組都有一組預先定義的權限。

例如，你網站的主要使用者將具有「管理員(Administrator)」的使用者角色，而其他使用者可能會擁有像「編輯(Editor)」或「作者(Author)」的角色。你可以指派多個使用者到同一個角色中，例如網站可能會有兩個管理員。

「用戶權限」是指你專為每個用戶或用戶角色分配的具體權限。

例如，管理員具有「manage_options」權限，這使他們可以查看、編輯和保存網站的設定。相反的，編輯人員無此權限，可以防止他們越權操作。

這些權限會在管理後台中的各個操作點進行檢查。依據分配給角色的權限，選單、功能與其他期望的體驗也許是新增或是刪除。

建立一個外掛時，請務必確保當前的使用者只擁有必要的權限，才可以執行你的程式。

權限階層

使用者角色層級越高，使用者就有越多的功能。每個使用者角色都繼承了層次結構中之前的角色。

例如，對於單站點的安裝，最高的使用者角色為「管理員」，該角色會繼承以下角色及其權限：「訂閱者」、「投稿者」、「作者」和「編輯」。

範例

不限制版本

下面的範例會在前端建立一個連結，允許將文章放入垃圾桶。因為這段程式碼沒有檢查使用者的權限，所以它允許任何訪問該網站的訪客將文章放入垃圾桶！

/**
 * Generate a Delete link based on the homepage url.
 *
 * @param string $content   Existing content.
 *
 * @return string|null
 */
function wporg_generate_delete_link( $content ) {
    // Run only for single post page.
    if ( is_single() && in_the_loop() && is_main_query() ) {
        // Add query arguments: action, post.
        $url = add_query_arg(
            [
                'action' => 'wporg_frontend_delete',
                'post'   => get_the_ID(),
            ], home_url()
        );

        return $content . ' ' . esc_html__( 'Delete Post', 'wporg' ) . '';
    }

    return null;
}

/**
 * Request handler
 */
function wporg_delete_post() {
    if ( isset( $_GET['action'] ) && 'wporg_frontend_delete' === $_GET['action'] ) {

        // Verify we have a post id.
        $post_id = ( isset( $_GET['post'] ) ) ? ( $_GET['post'] ) : ( null );

        // Verify there is a post with such a number.
        $post = get_post( (int) $post_id );
        if ( empty( $post ) ) {
            return;
        }

        // Delete the post.
        wp_trash_post( $post_id );

        // Redirect to admin page.
        $redirect = admin_url( 'edit.php' );
        wp_safe_redirect( $redirect );

        // We are done.
        die;
    }
}

/**
 * Add the delete link to the end of the post content.
 */
add_filter( 'the_content', 'wporg_generate_delete_link' );

/**
 * Register our request handler with the init hook.
 */
add_action( 'init', 'wporg_delete_post' );

限制特殊權限的版本

上述的範例允許任何訪客點擊「刪除」連結並將文章刪除。然而，我們只希望「編輯」權限及以上的使用者能夠點擊「刪除」連結。

為了實現這個目標，我們將檢查當前使用者是否具備 edit_others_posts 權限，而這個權限只有「編輯」權限及以上的使用者才具備。

/**
 * Generate a Delete link based on the homepage url.
 *
 * @param string $content   Existing content.
 *
 * @return string|null
 */
function wporg_generate_delete_link( $content ) {
    // Run only for single post page.
    if ( is_single() && in_the_loop() && is_main_query() ) {
        // Add query arguments: action, post.
        $url = add_query_arg(
            [
                'action' => 'wporg_frontend_delete',
                'post'   => get_the_ID(),
            ], home_url()
        );

        return $content . ' ' . esc_html__( 'Delete Post', 'wporg' ) . '';
    }

    return null;
}

/**
 * Request handler
 */
function wporg_delete_post() {
    if ( isset( $_GET['action'] ) && 'wporg_frontend_delete' === $_GET['action'] ) {

        // Verify we have a post id.
        $post_id = ( isset( $_GET['post'] ) ) ? ( $_GET['post'] ) : ( null );

        // Verify there is a post with such a number.
        $post = get_post( (int) $post_id );
        if ( empty( $post ) ) {
            return;
        }

        // Delete the post.
        wp_trash_post( $post_id );

        // Redirect to admin page.
        $redirect = admin_url( 'edit.php' );
        wp_safe_redirect( $redirect );

        // We are done.
        die;
    }
}

/**
 * Add delete post ability
 */
add_action('plugins_loaded', 'wporg_add_delete_post_ability');

function wporg_add_delete_post_ability() {    
    if ( current_user_can( 'edit_others_posts' ) ) {
        /**
         * Add the delete link to the end of the post content.
         */
        add_filter( 'the_content', 'wporg_generate_delete_link' );

        /**
         * Register our request handler with the init hook.
         */
        add_action( 'init', 'wporg_delete_post' );
    }
}

資料驗證

不可信的資料來自多個來源（使用者、第三方網站，甚至你自己的資料庫！）所有資料在使用前都需要檢查。

請記住：即使是管理員也是用戶，用戶會輸入錯誤的資料，無論是故意還是偶然。你的工作是保護使用者不受自己（或別人）的傷害。

驗證 輸入是將資料根據預定格式（或模式）進行測試並得出明確結果（有效或無效）的過程。相對於逸出轉譯化，驗證是一種更具體的方法，但兩者都有其作用。

簡單的驗證範例：

• 確認必填欄位不留空
• 檢查輸入的電話號碼是否只包含數字和連結符號
• 確認輸入的字串是否為有效的選項之一
• 確認數量欄位是否大於 0

資料驗證應盡可能在最早期進行。 這意味著在執行任何操作之前對資料進行驗證。

驗證的哲學

關於驗證，有幾種不同的哲學觀點在聊「如何驗證」，每種觀點都適用於不同的情境。

安全名單、白名單

只接受資料從已知且可信的列表輸入。

當不信任的資料與安全列表進行比較時，重要的是確保使用嚴格的類型檢查。否則，攻擊者可能會以某種方式包裝輸入，以使其通過安全列表，但仍具有惡意效果。

比較運算元

$untrusted_input = '1 malicious string';  // will evaluate to integer 1 during loose comparisons

if ( 1 === $untrusted_input ) {  // 使用「==」 比對的話會回傳 true, 但 「===」會回傳 false
    echo '
Valid data';
} else {
    wp_die( 'Invalid data' );
}

in_array()

$untrusted_input = '1 malicious string';  // will evaluate to integer 1 during loose comparisons
$safe_values     = array( 1, 5, 7 );

if ( in_array( $untrusted_input, $safe_values, true ) ) {  // 第三個參數 `true` 會打開強型別檢查
    echo '
Valid data';
} else {
    wp_die( 'Invalid data' );
}

switch()

$untrusted_input = '1 malicious string';  // will evaluate to integer 1 during loose comparisons

switch ( true ) {
    case 1 === $untrusted_input:  // 使用自己的強型別檢查比使用 switch 的方法好
        echo '
Valid data';
        break;

    default:
        wp_die( 'Invalid data' );
}

黑名單

拒絕來自已知不受信任的資料列表。通常不是一個好主意。

格式檢查

測試資料是否符合正確的格式，只有當符合格式時才予以接受。

if ( ! ctype_alnum( $data ) ) {
  wp_die( "Invalid format" );
}

if ( preg_match( "/[^0-9.-]/", $data ) ) {
  wp_die( "Invalid format" );
}

格式校正

接受大部分資料，但移除或是逸出轉譯可能的危險部分。

$trusted_integer = (int) $untrusted_integer;
$trusted_alpha = preg_replace( '/[^a-z]/i', "", $untrusted_alpha );
$trusted_slug = sanitize_title( $untrusted_slug );

範例一

讓我們來設計一個輸入欄位，用來輸入 US 美國的郵遞區號：

在這裡，我們告訴瀏覽器只允許輸入最多十個字符，但是在輸入哪些字符上沒有限制。他們可以輸入 11221 或 eval()。

這就是驗證的作用。在處理表單時，我們寫程式來檢查每個字串的正確資料類型，如果不正確，就將其丟棄。

例如：為了檢查my-zipcode字段，我們可以進行以下操作：

/**
 * Validate a US zip code.
 *
 * @param string $zip_code   RAW zip code to check.
 *
 * @return bool              true if valid, false otherwise.
 */
function wporg_is_valid_us_zip_code( string $zip_code ):bool {
    // Scenario 1: empty.
    if ( empty( $zip_code ) ) {
        return false;
    }

    // Scenario 2: more than 10 characters.
    // The `maxlength` attribute is only enforced by 
    // the browser, so we still need to validate the
    // length of the input on the server to protect
    // against a manual submission.
    if ( 10 < strlen( trim( $zip_code ) ) ) {
        return false;
    }

    // Scenario 3: incorrect format.
    if ( ! preg_match( '/^d{5}(-?d{4})?$/', $zip_code ) ) {
        return false;
    }

    // Passed successfully.
    return true;
}

然後，在處理表單時，你的程式碼應該檢查 wporg_zip_code 欄位，並根據結果執行相應的動作：

if ( isset( $_POST['wporg_zip_code'] ) && wporg_is_valid_us_zip_code( $_POST['wporg_zip_code'] ) ) {
    // $_POST['wporg_zip_code'] is valid; carry on
}

注意，這個具體的例子是在檢查提供的資料是否為正確的格式；它並不是在檢查資料是否為有效的郵遞區號。為了達到這個目的，你需要再寫一個函式來將其與一個有效郵遞區號列表進行比較。

範例二

假設你的程式碼會查詢資料庫中的文章，而你希望允許使用者對查詢結果進行排序。

$allowed_keys = array( 'author', 'post_author', 'date', 'post_date' );
$orderby      = sanitize_key( $_POST['orderby'] );
if ( in_array( $orderby, $allowed_keys, true ) ) {
    // $orderby is valid; carry on
}

此範例程式碼會透過比對鍵值排序的陣列，確認傳入鍵值排序（紀錄在 orderby 輸入參數中）的有效性，以防止使用者傳入任意且可能有害的資料。

在將傳入的鍵值排序與陣列比對前，會先使用 WordPress 內建的 sanitize_key() 函式處理鍵值。此函式確保（除其他處理之外）鍵值全為小寫，因為 in_array() 進行區分大小寫的搜尋。

將 true 傳入 in_array() 第三個參數即啟用嚴格型別檢查，讓該函式不僅比較值，也比較值的型別。透過此方式，程式碼可以確信傳入的鍵值排序是字串類型，而非其他類型的資料。

驗證資料會使用的函式

大部分的驗證都是在自定義的程式碼中進行，但也有一些輔助功能。這些輔助功能是此清理(Sanitation)頁面上列出的功能之外的。

• balanceTags( $html ) 或 force_balance_tags( $html ) – 用於嘗試確保 HTML 標籤平衡，有開頭有結尾，用以產生有效的 XML 輸出。
• count() 用於檢查陣列中有多少項目
• in_array() 用於檢查某個項目是否存在於陣列中
• is_email() 用於驗證電子郵件地址是否有效。
• in_array() 用於檢查某個項目是否存在於陣列中
• mb_strlen() 或 strlen() 用於檢查字串的預期字元數
• preg_match()、strpos() 用於在其他字串中檢查某些字串是否存在
• sanitize_html_class( $class, $fallback ) – 對 HTML 中的 Class 屬性值進行逸出轉譯，確保只包含有效字元。將字串逸出轉譯成 A-Z、a-z、0-9、'-' 等字元，如此逸出轉譯產生空字串，則會返回提供的替代值。
• tag_escape( $html_tag_name ) – 對 HTML 標籤名稱進行逸出轉譯。
• term_exists() 用於檢查標籤、類別或其他分類法詞彙是否存在。
• username_exists() 用於檢查使用者名稱是否存在。
• validate_file() 用於驗證輸入的檔案路徑是否為真實路徑（但並不驗證檔案是否存在）。

請查看 WordPress 開發參考文件 以了解更多像這樣的功能。搜尋名稱類似 *_exists()、*_validate() 和 is_*()的函式。並非所有這些都是驗證函式，但其中許多都很有用。

清理 (Sanitizing) 資料

「Sanitizing input」指的是保護、清理、過濾輸入資料的過程。「Validation 驗證」比「Sanitization 清理」更具體，因此通常優先考慮使用 Validation 驗證。但是，當「更具體細節」的驗證方式不可行時，「Sanitization 清理」便是次佳的選擇。

範例

假設我們有一個輸入的欄位名稱是 title：

我們在這裡不能使用驗證（Validation），因為文字欄位太一般了：它可以是任何內容。因此，我們使用 sanitize_text_field() 函式對輸入資料進行過濾。

$title = sanitize_text_field( $_POST['title'] );
update_post_meta( $post->ID, 'title', $title );

前述提到的 sanitize_text_field() 做以下幾件事情：

1. 檢查無效的 UTF-8
2. 將單一的 less-than 字元(<) 轉成實體格式（HTML entity）
3. 去除所有的 HTML 標籤
4. 移除換行、tab 和多餘的空白
5. 去除八進制字元。

Sanitization 清理可以使用的函式

這裡列出一些方法可以用來幫你「清理」資料：

• sanitize_email()
• sanitize_file_name()
• sanitize_hex_color()
• sanitize_hex_color_no_hash()
• sanitize_html_class()
• sanitize_key()
• sanitize_meta()
• sanitize_mime_type()
• sanitize_option()
• sanitize_sql_orderby()
• sanitize_term()
• sanitize_term_field()
• sanitize_text_field()
• sanitize_textarea_field()
• sanitize_title()
• sanitize_title_for_query()
• sanitize_title_with_dashes()
• sanitize_user()
• sanitize_url()
• wp_kses()
• wp_kses_post()

逸出轉譯資料

「逸出轉譯」是一種保護輸出資料的過程，通過排除不需要的資料，例如格式不正確的 HTML 標籤，從而保護你的資料，在呈現給終端用戶之前確保其安全性。

大部分 WordPress 的函式都會妥善處理好輸出的資料，不需要額外的逸出轉譯處理。

逸出轉譯的函式

WordPress 有許多輔助功能可用於大多數常見的情境。

仔細注意每個功能的行為，因為有些會刪除 HTML 標籤，有些則允許 HTML 標籤存在。你必須根據輸出的內容與上下文，使用最適合的方法，且總是輸出時才進行轉譯，而不是之前。

• esc_html() – 將HTML元素排除於內容中，可在任何時候使用。這方法會去除 HTML。

• esc_js() – 使用在內嵌形式呈現的 JavaScript

• esc_url() – 使用在任何形式下的 URL 連結資源，包含 src 或 href 屬性

• esc_url_raw() – 使用在 URL 儲存資料庫或其他需要非編碼 URL 的情況下。

• esc_xml() – 使用在 XML 格式區塊中。

• esc_attr() – 將其用於所有印出 HTML 元素屬性中的內容。

• esc_textarea() – 用於 Textarea 多行輸入的元素中，轉譯其文字內容。

• wp_kses() – 使用此方法來安全地轉譯所有不信任的 HTML（如文章、留言等），並且保留 HTML 的格式。

• wp_kses_post() – 另一個版本的 wp_kses()，可允許所有在文章內容中允許的 HTML 元素。

• wp_kses_data() – 另一個版本的 wp_kses()，可允許所有在留言內容中允許的 HTML 元素。

客製化逸出轉譯的範例

如果你需要以特定的方式逸出轉譯，那麼函式 wp_kses()（發音為“kisses”）就很有用。

該函式確保你的輸出中只包含指定的 HTML 元素、屬性和屬性值，並規範化 HTML 實體。

 array(
            'href'  => array(),
            'title' => array(),
        ),
        'br'     => array(),
        'em'     => array(),
        'strong' => array(),
    )
); ?>

在這個例子中，除了 、
、 和 以外的所有標籤都會被去除。此外，如果傳遞了一個 標籤，則轉譯會確保只返回 href 和 title 的屬性。

// 可以，但不是很好。
$url = esc_url( $url );
$text = esc_html( $text );
echo '' . $text . '';

// 好多了！
echo '' . esc_html( $text ) . '';

esc_html_e( 'Hello World', 'text_domain' );
// 相同於下面
echo esc_html( __( 'Hello World', 'text_domain' ) );

echo $int;

echo '
';

echo '
';

echo '
';

echo '';

echo '';

echo '';
echo '';

wp_localize_script( 'handle', 'name',
    array(
        'prefix_nonce' => wp_create_nonce( 'plugin-name' ),
        'ajaxurl'      => admin_url( 'admin-ajax.php' ),
        'errorMsg'     => __( 'An error occurred', 'plugin-name' ),
    )
);

echo '', $data, '';

echo '', esc_textarea( $data ), '';

echo '
', $phrase, '
';

echo '', $var, '';

echo '', ent2ncr( $var ), '';

$complete_url = wp_nonce_url( $bare_url, 'trash-post_'.$post->ID );

$complete_url = wp_nonce_url( $bare_url, 'trash-post_'.$post->ID, 'my_nonce' );

wp_nonce_field( 'delete-comment_'.$comment_id );

$nonce = wp_create_nonce( 'my-action_'.$post->ID );

check_admin_referer( 'delete-comment_'.$comment_id );

check_admin_referer( 'delete-comment_'.$comment_id, 'my_nonce' );

check_ajax_referer( 'process-comment' );

wp_verify_nonce( $_REQUEST['my_nonce'], 'process-comment'.$comment_id );

add_filter( 'nonce_life', function () { return 4 * HOUR_IN_SECONDS; } );

function wporg_additional_check ( $action, $result ) {
    ...
}
add_action( 'check_admin_referer', 'wporg_additional_check', 10, 2 );

function my_nonce_message ($translation) {
    if ($translation === 'Are you sure you want to do this?') {
       return 'No! No! No!';
    } 

    return $translation;
}

add_filter('gettext', 'my_nonce_message');

$wpdb->get_var( $wpdb->prepare(
    "SELECT something FROM table WHERE foo = %s and status = %d",
    $name, // an unescaped string (function will do the sanitization for you)
    $status // an untrusted integer (function will do the sanitization for you)
) );

$allowed_html = array(
    'a' => array(
        'href' => array(),
        'title' => array()
    ),
    'br' => array(),
    'em' => array(),
    'strong' => array(),
);

echo wp_kses( $custom_content, $allowed_html );

/**
 * Generate a Delete link based on the homepage url.
 *
 * @param string $content   Existing content.
 *
 * @return string|null
 */
function wporg_generate_delete_link( $content ) {
    // Run only for single post page.
    if ( is_single() && in_the_loop() && is_main_query() ) {
        // Add query arguments: action, post, nonce
        $url = add_query_arg(
            [
                'action' => 'wporg_frontend_delete',
                'post'   => get_the_ID(),
                'nonce'  => wp_create_nonce( 'wporg_frontend_delete' ),
            ], home_url()
        );

        return $content . ' ' . esc_html__( 'Delete Post', 'wporg' ) . '';
    }

    return null;
}

/**
 * Request handler
 */
function wporg_delete_post() {
    if ( isset( $_GET['action'] )
         && isset( $_GET['nonce'] )
         && 'wporg_frontend_delete' === $_GET['action']
         && wp_verify_nonce( $_GET['nonce'], 'wporg_frontend_delete' ) ) {

        // Verify we have a post id.
        $post_id = ( isset( $_GET['post'] ) ) ? ( $_GET['post'] ) : ( null );

        // Verify there is a post with such a number.
        $post = get_post( (int) $post_id );
        if ( empty( $post ) ) {
            return;
        }

        // Delete the post.
        wp_trash_post( $post_id );

        // Redirect to admin page.
        $redirect = admin_url( 'edit.php' );
        wp_safe_redirect( $redirect );

        // We are done.
        die;
    }
}

/**
 * Add delete post ability
 */
add_action('plugins_loaded', 'wporg_add_delete_post_ability');

function wporg_add_delete_post_ability() {    
    if ( current_user_can( 'edit_others_posts' ) ) {
        /**
         * Add the delete link to the end of the post content.
         */
        add_filter( 'the_content', 'wporg_generate_delete_link' );

        /**
         * Register our request handler with the init hook.
         */
        add_action( 'init', 'wporg_delete_post' );
    }
}
```