File: //usr/local/wp/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/Security/NonceVerificationSniff.php
<?php
/**
* WordPress Coding Standard.
*
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/
namespace WordPressCS\WordPress\Sniffs\Security;
use PHPCSUtils\Tokens\Collections;
use PHPCSUtils\Utils\Conditions;
use PHPCSUtils\Utils\Context;
use PHPCSUtils\Utils\Lists;
use PHPCSUtils\Utils\MessageHelper;
use PHPCSUtils\Utils\Scopes;
use WordPressCS\WordPress\Helpers\ContextHelper;
use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
use WordPressCS\WordPress\Helpers\SanitizationHelperTrait;
use WordPressCS\WordPress\Helpers\UnslashingFunctionsHelper;
use WordPressCS\WordPress\Helpers\VariableHelper;
use WordPressCS\WordPress\Sniff;
/**
* Checks that nonce verification accompanies form processing.
*
* @link https://developer.wordpress.org/plugins/security/nonces/ Nonces on Plugin Developer Handbook
*
* @since 0.5.0
* @since 0.13.0 Class name changed: this class is now namespaced.
* @since 1.0.0 This sniff has been moved from the `CSRF` category to the `Security` category.
* @since 3.0.0 This sniff has received significant updates to its logic and structure.
*
* @uses \WordPressCS\WordPress\Helpers\SanitizationHelperTrait::$customSanitizingFunctions
* @uses \WordPressCS\WordPress\Helpers\SanitizationHelperTrait::$customUnslashingSanitizingFunctions
*/
class NonceVerificationSniff extends Sniff {
use SanitizationHelperTrait;
/**
* Superglobals to notify about when not accompanied by an nonce check.
*
* A value of `true` results in an error. A value of `false` in a warning.
*
* @since 0.12.0
*
* @var array
*/
protected $superglobals = array(
'$_POST' => true,
'$_FILES' => true,
'$_GET' => false,
'$_REQUEST' => false,
);
/**
* Custom list of functions which verify nonces.
*
* @since 0.5.0
*
* @var string[]
*/
public $customNonceVerificationFunctions = array();
/**
* List of the functions which verify nonces.
*
* @since 0.5.0
* @since 0.11.0 Changed from public static to protected non-static.
* @since 3.0.0 - Moved from the generic `Sniff` class to this class.
* - Visibility changed from `protected` to `private.
*
* @var array
*/
private $nonceVerificationFunctions = array(
'wp_verify_nonce' => true,
'check_admin_referer' => true,
'check_ajax_referer' => true,
);
/**
* Cache of previously added custom functions.
*
* Prevents having to do the same merges over and over again.
*
* @since 0.5.0
* @since 0.11.0 - Changed from public static to protected non-static.
* - Changed the format from simple bool to array.
* @since 3.0.0 - Property rename from `$addedCustomFunctions` to `$addedCustomNonceFunctions`.
* - Visibility changed from `protected` to `private.
* - Format changed from a multi-dimensional array to a single-dimensional array.
*
* @var array
*/
private $addedCustomNonceFunctions = array();
/**
* Information on the all scopes that were checked to find a nonce verification in a particular file.
*
* The array will be in the following format:
* ```
* array(
* 'file' => (string) The name of the file.
* 'cache' => (array) array(
* # => array( The key is the token pointer to the "start" position.
* 'end' => (int) The token pointer to the "end" position.
* 'nonce' => (int|bool) The token pointer where n nonce check
* was found, or false if none was found.
* )
* )
* )
* ```
*
* @since 3.0.0
*
* @var array<string, mixed>
*/
private $cached_results;
/**
* Returns an array of tokens this test wants to listen for.
*
* @return array
*/
public function register() {
$targets = array( \T_VARIABLE => \T_VARIABLE );
$targets += Collections::listOpenTokensBC(); // We need to skip over lists.
return $targets;
}
/**
* Processes this test, when one of its tokens is encountered.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return int|void Integer stack pointer to skip forward or void to continue
* normal file processing.
*/
public function process_token( $stackPtr ) {
// Skip over lists as whatever is in those will always be assignments.
if ( isset( Collections::listOpenTokensBC()[ $this->tokens[ $stackPtr ]['code'] ] ) ) {
$open_close = Lists::getOpenClose( $this->phpcsFile, $stackPtr );
$skip_to = $stackPtr;
if ( false !== $open_close ) {
$skip_to = $open_close['closer'];
}
return $skip_to;
}
if ( ! isset( $this->superglobals[ $this->tokens[ $stackPtr ]['content'] ] ) ) {
return;
}
if ( Scopes::isOOProperty( $this->phpcsFile, $stackPtr ) ) {
// Property with the same name as a superglobal. Not our target.
return;
}
// Determine the cache keys for this item.
$cache_keys = array(
'file' => $this->phpcsFile->getFilename(),
'start' => 0,
'end' => $stackPtr,
);
// If we're in a function, only look inside of it.
// This doesn't take arrow functions into account as those are "open".
$functionPtr = Conditions::getLastCondition( $this->phpcsFile, $stackPtr, array( \T_FUNCTION, \T_CLOSURE ) );
if ( false !== $functionPtr ) {
$cache_keys['start'] = $this->tokens[ $functionPtr ]['scope_opener'];
}
$this->mergeFunctionLists();
$needs_nonce = $this->needs_nonce_check( $stackPtr, $cache_keys );
if ( false === $needs_nonce ) {
return;
}
if ( $this->has_nonce_check( $stackPtr, $cache_keys, ( 'after' === $needs_nonce ) ) ) {
return;
}
// If we're still here, no nonce-verification function was found.
$error_code = 'Missing';
if ( false === $this->superglobals[ $this->tokens[ $stackPtr ]['content'] ] ) {
$error_code = 'Recommended';
}
MessageHelper::addMessage(
$this->phpcsFile,
'Processing form data without nonce verification.',
$stackPtr,
$this->superglobals[ $this->tokens[ $stackPtr ]['content'] ],
$error_code
);
}
/**
* Determine whether or not a nonce check is needed for the current superglobal.
*
* @since 3.0.0
*
* @param int $stackPtr The position of the current token in the stack of tokens.
* @param array $cache_keys The keys for the applicable cache (to potentially set).
*
* @return string|false String "before" or "after" if a nonce check is needed.
* FALSE when no nonce check is needed.
*/
protected function needs_nonce_check( $stackPtr, array $cache_keys ) {
$in_nonce_check = ContextHelper::is_in_function_call( $this->phpcsFile, $stackPtr, $this->nonceVerificationFunctions );
if ( false !== $in_nonce_check ) {
// This *is* the nonce check, so bow out, but do store to cache.
// @todo Change to use arg unpacking once PHP < 5.6 has been dropped.
$this->set_cache( $cache_keys['file'], $cache_keys['start'], $cache_keys['end'], $in_nonce_check );
return false;
}
if ( Context::inUnset( $this->phpcsFile, $stackPtr ) ) {
// Variable is only being unset, no nonce check needed.
return false;
}
if ( VariableHelper::is_assignment( $this->phpcsFile, $stackPtr, false ) ) {
// Overwriting the value of a superglobal.
return false;
}
$needs_nonce = 'before';
if ( ContextHelper::is_in_isset_or_empty( $this->phpcsFile, $stackPtr )
|| ContextHelper::is_in_type_test( $this->phpcsFile, $stackPtr )
|| VariableHelper::is_comparison( $this->phpcsFile, $stackPtr )
|| VariableHelper::is_assignment( $this->phpcsFile, $stackPtr, true )
|| ContextHelper::is_in_array_comparison( $this->phpcsFile, $stackPtr )
|| ContextHelper::is_in_function_call( $this->phpcsFile, $stackPtr, UnslashingFunctionsHelper::get_functions() ) !== false
|| $this->is_only_sanitized( $this->phpcsFile, $stackPtr )
) {
$needs_nonce = 'after';
}
return $needs_nonce;
}
/**
* Check if this token has an associated nonce check.
*
* @since 0.5.0
* @since 3.0.0 - Moved from the generic `Sniff` class to this class.
* - Visibility changed from `protected` to `private.
* - New `$cache_keys` parameter.
* - New `$allow_nonce_after` parameter.
*
* @param int $stackPtr The position of the current token in the stack of tokens.
* @param array $cache_keys The keys for the applicable cache.
* @param bool $allow_nonce_after Whether the nonce check _must_ be before the $stackPtr or
* is allowed _after_ the $stackPtr.
*
* @return bool
*/
private function has_nonce_check( $stackPtr, array $cache_keys, $allow_nonce_after = false ) {
$start = $cache_keys['start'];
$end = $cache_keys['end'];
// We allow for certain actions, such as an isset() check to come before the nonce check.
// If this superglobal is inside such a check, look for the nonce after it as well,
// all the way to the end of the scope.
if ( true === $allow_nonce_after ) {
$end = ( 0 === $start ) ? $this->phpcsFile->numTokens : $this->tokens[ $start ]['scope_closer'];
}
// Check against the cache.
$current_cache = $this->get_cache( $cache_keys['file'], $start );
if ( false !== $current_cache['nonce'] ) {
// If we have already found a nonce check in this scope, we just
// need to check whether it comes before this token. It is OK if the
// check is after the token though, if this was only an isset() check.
return ( true === $allow_nonce_after || $current_cache['nonce'] < $stackPtr );
} elseif ( $end <= $current_cache['end'] ) {
// If not, we can still go ahead and return false if we've already
// checked to the end of the search area.
return false;
}
$search_start = $start;
if ( $current_cache['end'] > $start ) {
// We haven't checked this far yet, but we can still save work by
// skipping over the part we've already checked.
$search_start = $this->cached_results['cache'][ $start ]['end'];
}
// Loop through the tokens looking for nonce verification functions.
for ( $i = $search_start; $i < $end; $i++ ) {
// Skip over nested closed scope constructs.
if ( isset( Collections::closedScopes()[ $this->tokens[ $i ]['code'] ] )
|| \T_FN === $this->tokens[ $i ]['code']
) {
if ( isset( $this->tokens[ $i ]['scope_closer'] ) ) {
$i = $this->tokens[ $i ]['scope_closer'];
}
continue;
}
// If this isn't a function name, skip it.
if ( \T_STRING !== $this->tokens[ $i ]['code'] ) {
continue;
}
// If this is one of the nonce verification functions, we can bail out.
if ( isset( $this->nonceVerificationFunctions[ $this->tokens[ $i ]['content'] ] ) ) {
/*
* Now, make sure it is a call to a global function.
*/
if ( ContextHelper::has_object_operator_before( $this->phpcsFile, $i ) === true ) {
continue;
}
if ( ContextHelper::is_token_namespaced( $this->phpcsFile, $i ) === true ) {
continue;
}
$this->set_cache( $cache_keys['file'], $start, $end, $i );
return true;
}
}
// We're still here, so no luck.
$this->set_cache( $cache_keys['file'], $start, $end, false );
return false;
}
/**
* Helper function to retrieve results from the cache.
*
* @since 3.0.0
*
* @param string $filename The name of the current file.
* @param int $start The stack pointer searches started from.
*
* @return array<string, mixed>
*/
private function get_cache( $filename, $start ) {
if ( is_array( $this->cached_results )
&& $filename === $this->cached_results['file']
&& isset( $this->cached_results['cache'][ $start ] )
) {
return $this->cached_results['cache'][ $start ];
}
return array(
'end' => 0,
'nonce' => false,
);
}
/**
* Helper function to store results to the cache.
*
* @since 3.0.0
*
* @param string $filename The name of the current file.
* @param int $start The stack pointer searches started from.
* @param int $end The stack pointer searched stopped at.
* @param int|bool $nonce Stack pointer to the nonce verification function call or false if none was found.
*
* @return void
*/
private function set_cache( $filename, $start, $end, $nonce ) {
if ( is_array( $this->cached_results ) === false
|| $filename !== $this->cached_results['file']
) {
$this->cached_results = array(
'file' => $filename,
'cache' => array(
$start => array(
'end' => $end,
'nonce' => $nonce,
),
),
);
return;
}
// Okay, so we know the current cache is for the current file. Check if we've seen this start pointer before.
if ( isset( $this->cached_results['cache'][ $start ] ) === false ) {
$this->cached_results['cache'][ $start ] = array(
'end' => $end,
'nonce' => $nonce,
);
return;
}
// Update existing entry.
if ( $end > $this->cached_results['cache'][ $start ]['end'] ) {
$this->cached_results['cache'][ $start ]['end'] = $end;
}
$this->cached_results['cache'][ $start ]['nonce'] = $nonce;
}
/**
* Merge custom functions provided via a custom ruleset with the defaults, if we haven't already.
*
* @since 0.11.0 Split out from the `process()` method.
*
* @return void
*/
protected function mergeFunctionLists() {
if ( $this->customNonceVerificationFunctions !== $this->addedCustomNonceFunctions ) {
$this->nonceVerificationFunctions = RulesetPropertyHelper::merge_custom_array(
$this->customNonceVerificationFunctions,
$this->nonceVerificationFunctions
);
$this->addedCustomNonceFunctions = $this->customNonceVerificationFunctions;
}
}
}