>, regs: array>, leads: array>, classes: array} */ public static function of( Source $s ): array { $units = []; $leads = []; foreach ( $s->units as $index => $unit ) { $facts = self::unit( $s, $unit ); foreach ( $facts['leads'] as $lead ) { $lead['unit'] = $index; $leads[] = $lead; } unset( $facts['leads'] ); $units[ $index ] = $facts; } $classes = []; foreach ( $s->classes as $key => $class ) { $classes[ $key ] = [ 'name' => $class['name'], 'extends' => null === $class['extends'] ? null : ltrim( $class['extends'], '\\' ), ]; } $regs = []; for ( $i = 0; $i < $s->n; $i++ ) { if ( T_STRING !== $s->id( $i ) || ! $s->is( $i + 1, '(' ) || in_array( $s->id( $i - 1 ), self::NOT_A_CALL, true ) ) { continue; } $fn = strtolower( $s->text( $i ) ); if ( ! in_array( $fn, self::REGISTRARS, true ) ) { continue; } $reg = self::registration( $s, $fn, $i ); if ( null === $reg ) { continue; } $reg['unit'] = self::unit_at( $s, $i ); $reg['line'] = $s->line( $i ); if ( 'ability_filter' === ( $reg['kind'] ?? null ) ) { $leads[] = [ 'check' => 'CODE-017', 'kb' => 'abilities-api-permission', 'line' => $reg['line'], 'severity' => 'medium', 'what' => $fn . "( '" . $reg['hook'] . "' )", 'unit' => $reg['unit'], ]; continue; } $regs[] = $reg; } return [ 'units' => $units, 'regs' => $regs, 'leads' => $leads, 'classes' => $classes, ]; } /** * How a function shows in a lead: Class::method, a function's name, or a closure's line. * * @param array{kind: string, name: string, class: ?string, line: int} $unit The function. */ public static function label( array $unit ): string { switch ( $unit['kind'] ) { case 'method': return $unit['class'] . '::' . $unit['name']; case 'function': return $unit['name']; case 'file': return ''; } return ( 'arrow' === $unit['kind'] ? 'fn@' : 'closure@' ) . $unit['line']; } /** * @param array{kind: string, name: string, class: ?string, params: array, decl: int, start: int, end: int, line: int} $unit The function. * @return array */ private static function unit( Source $s, array $unit ): array { $facts = [ 'label' => self::label( $unit ), 'kind' => $unit['kind'], 'name' => strtolower( $unit['name'] ), 'class' => $unit['class'], 'line' => $unit['line'], 'decl' => $unit['decl'], 'cap' => false, 'nonce' => false, 'is_admin' => false, 'reads' => false, 'changes' => [], 'calls' => [], 'returns_true' => self::returns_true( $s, $unit ), 'leads' => [], ]; $own = []; $upload = null; $type_check = false; $admin = false; $roles = false; for ( $i = $unit['start']; $i < $unit['end']; $i++ ) { if ( isset( $s->skip[ $i ] ) ) { $i = $s->skip[ $i ] - 1; continue; } $id = $s->id( $i ); if ( T_VARIABLE === $id ) { $name = $s->text( $i ); if ( in_array( $name, Rules::SUPERGLOBALS, true ) ) { $facts['reads'] = true; } if ( $s->is( $i + 1, '=' ) && T_STRING === $s->id( $i + 2 ) && in_array( strtolower( $s->text( $i + 2 ) ), [ 'get_current_user_id', 'wp_get_current_user' ], true ) ) { $own[ $name ] = true; } continue; } if ( T_CONSTANT_ENCAPSED_STRING === $id ) { $value = (string) $s->literal( $i ); if ( 'administrator' === $value ) { $admin = true; } if ( in_array( $value, [ 'sslverify', 'verify_peer' ], true ) && T_DOUBLE_ARROW === $s->id( $i + 1 ) && self::is_off( $s, $i + 2 ) && ! self::tls_off_is_harmless( $s, $i ) ) { $facts['leads'][] = self::lead( 'CODE-009', 'supply-chain-integrity', $s->line( $i ), "'" . $value . "' => false", 'low' ); } continue; } if ( T_OBJECT_OPERATOR === $id && T_STRING === $s->id( $i + 1 ) ) { $method = strtolower( $s->text( $i + 1 ) ); if ( 'roles' === $method ) { $roles = true; } if ( ! $s->is( $i + 2, '(' ) ) { continue; } $object = $s->text( $i - 1 ); if ( in_array( $method, Rules::REST_METHODS, true ) ) { $facts['reads'] = true; } elseif ( 'has_cap' === $method ) { $facts['cap'] = true; } elseif ( isset( Rules::METHOD_CHANGES[ $method ] ) || ( 'delete' === $method && '$wp_filesystem' === $object ) ) { $kind = Rules::METHOD_CHANGES[ $method ] ?? 'file'; if ( 'file' !== $kind || '$wp_filesystem' === $object ) { $facts['changes'][] = self::change( $kind, '->' . $method . '()', $s->line( $i ) ); } } if ( '$this' === $object ) { $facts['calls'][] = [ 'type' => 'method', 'class' => $unit['class'], 'name' => $method, ]; } continue; } if ( T_DOUBLE_COLON === $id && in_array( $s->id( $i - 1 ), [ T_STRING, T_STATIC ], true ) && T_STRING === $s->id( $i + 1 ) && $s->is( $i + 2, '(' ) ) { $owner = strtolower( $s->text( $i - 1 ) ); $class = in_array( $owner, [ 'self', 'static' ], true ) ? $unit['class'] : $s->text( $i - 1 ); if ( 'parent' === $owner ) { $class = 'parent:' . (string) $unit['class']; } $facts['calls'][] = [ 'type' => 'method', 'class' => $class, 'name' => strtolower( $s->text( $i + 1 ) ), ]; continue; } if ( T_STRING !== $id || ! $s->is( $i + 1, '(' ) || in_array( $s->id( $i - 1 ), self::NOT_A_CALL, true ) ) { continue; } $fn = strtolower( $s->text( $i ) ); $args = $s->args( $i + 1 ); if ( in_array( $fn, Rules::CAP_CHECKS, true ) ) { $facts['cap'] = true; } elseif ( in_array( $fn, Rules::NONCE_CHECKS, true ) ) { $facts['nonce'] = true; } elseif ( 'is_admin' === $fn ) { $facts['is_admin'] = $facts['is_admin'] || self::in_condition( $s, $i ); } elseif ( in_array( $fn, [ 'filter_input', 'filter_input_array' ], true ) || ( 'file_get_contents' === $fn && isset( $args[0] ) && 'php://input' === $s->only_literal( $args[0] ) ) ) { $facts['reads'] = true; } elseif ( in_array( $fn, Rules::TYPE_CHECKS, true ) ) { $type_check = true; } elseif ( 'preg_match' === $fn && isset( $args[0] ) && 1 === preg_match( '/jpe?g|png|gif|pdf|webp|csv|zip/i', (string) $s->only_literal( $args[0] ) ) ) { $type_check = true; } elseif ( 'curl_setopt' === $fn && isset( $args[2] ) && 1 === preg_match( '/^CURLOPT_SSL_VERIFY(?:PEER|HOST)$/', $s->norm( $args[1][0], $args[1][1] ) ) && self::is_off( $s, $args[2][0] ) && 1 === $args[2][1] - $args[2][0] ) { $facts['leads'][] = self::lead( 'CODE-009', 'supply-chain-integrity', $s->line( $i ), 'curl_setopt( ' . $s->norm( $args[1][0], $args[1][1] ) . ', false )', 'low' ); } elseif ( 'add_filter' === $fn && isset( $args[1] ) && 'https_ssl_verify' === $s->only_literal( $args[0] ) && '__return_false' === $s->only_literal( $args[1] ) ) { $facts['leads'][] = self::lead( 'CODE-009', 'supply-chain-integrity', $s->line( $i ), "add_filter( 'https_ssl_verify', '__return_false' )", 'low' ); } if ( 'move_uploaded_file' === $fn ) { $upload = [ $s->line( $i ), 'move_uploaded_file()' ]; } elseif ( in_array( $fn, self::UPLOADS, true ) && self::type_test_off( $s, $args ) ) { $upload = [ $s->line( $i ), $fn . '() with test_type off' ]; } if ( isset( Rules::CHANGES[ $fn ] ) && ! self::harmless_change( $s, $fn, $args, $own ) ) { $facts['changes'][] = self::change( Rules::CHANGES[ $fn ], $fn . '()', $s->line( $i ) ); } if ( count( $facts['calls'] ) < 40 ) { $facts['calls'][] = [ 'type' => 'fn', 'name' => $fn, ]; } } $facts['cap'] = $facts['cap'] || ( $admin && $roles ); $facts['changes'] = array_slice( $facts['changes'], 0, 12 ); $facts['calls'] = array_slice( $facts['calls'], 0, 60 ); if ( null !== $upload && ! $type_check ) { $facts['leads'][] = self::lead( 'CODE-006', 'file-upload', $upload[0], $upload[1] ); } return $facts; } /** * Writes that aren't changes another user could abuse: the current user's own meta, and log * lines appended to a file. * * @param array $args The call's arguments. * @param array $own Variables holding the current user or their id. */ private static function harmless_change( Source $s, string $callee, array $args, array $own ): bool { if ( 'file_put_contents' === $callee ) { return isset( $args[2] ) && false !== strpos( $s->norm( $args[2][0], $args[2][1] ), 'FILE_APPEND' ); } if ( ! in_array( $callee, [ 'update_user_meta', 'delete_user_meta', 'update_user_option', 'delete_user_option' ], true ) || ! isset( $args[0] ) ) { return false; } $who = $s->norm( $args[0][0], $args[0][1] ); if ( in_array( strtolower( $who ), [ 'get_current_user_id()', 'wp_get_current_user()->id', '$current_user->id' ], true ) ) { return true; } $var = T_VARIABLE === $s->id( $args[0][0] ) ? $s->text( $args[0][0] ) : null; return null !== $var && isset( $own[ $var ] ) && in_array( $who, [ $var, $var . '->ID' ], true ); } /** * Certificate checks turned off where nothing can be intercepted (CODE-009): a request to the * site's own address, as core's loopback requests are, or a connection opened only to read the * certificate (capture_peer_cert), in the same statement. */ private static function tls_off_is_harmless( Source $s, int $i ): bool { $start = $i; while ( $start > 0 && ! $s->is( $start - 1, ';' ) && ! $s->is( $start - 1, '{' ) && ! $s->is( $start - 1, '}' ) ) { --$start; } $end = $i; while ( $end < $s->n && ! $s->is( $end, ';' ) ) { ++$end; } for ( $k = $start; $k < $end; $k++ ) { if ( 'capture_peer_cert' === $s->literal( $k ) ) { return true; } if ( T_STRING === $s->id( $k ) && $s->is( $k + 1, '(' ) && in_array( strtolower( $s->text( $k ) ), [ 'site_url', 'home_url', 'admin_url', 'rest_url', 'get_rest_url', 'get_site_url', 'get_home_url', 'network_site_url', 'network_home_url', 'network_admin_url', 'includes_url' ], true ) ) { return true; } } return false; } /** * Whether is_admin() at $i sits in an if condition: `if ( is_admin() …`, `… && ! is_admin()`. */ private static function in_condition( Source $s, int $i ): bool { $k = $i - 1; while ( $s->is( $k, '!' ) ) { --$k; } if ( in_array( $s->id( $k ), [ T_BOOLEAN_AND, T_BOOLEAN_OR, T_LOGICAL_AND, T_LOGICAL_OR ], true ) ) { return true; } return $s->is( $k, '(' ) && in_array( $s->id( $k - 1 ), [ T_IF, T_ELSEIF ], true ); } /** * Whether a function only says yes: `return true;`, `return __return_true();`, or `fn() => true`. * * @param array{kind: string, start: int, end: int} $unit The function. */ private static function returns_true( Source $s, array $unit ): bool { $body = strtolower( $s->norm( $unit['start'], $unit['end'] ) ); if ( 'arrow' === $unit['kind'] ) { return 'true' === $body; } return in_array( $body, [ 'returntrue;', 'return__return_true();' ], true ); } /** * `false` or `0` at $i. */ private static function is_off( Source $s, int $i ): bool { return ( T_STRING === $s->id( $i ) && 'false' === strtolower( $s->text( $i ) ) ) || ( T_LNUMBER === $s->id( $i ) && '0' === $s->text( $i ) ); } /** * Whether an upload call's overrides turn the type test off: [ 'test_type' => false ]. * * @param array $args The call's arguments. */ private static function type_test_off( Source $s, array $args ): bool { foreach ( $args as $range ) { for ( $k = $range[0]; $k < $range[1]; $k++ ) { if ( 'test_type' === $s->literal( $k ) && T_DOUBLE_ARROW === $s->id( $k + 1 ) && self::is_off( $s, $k + 2 ) ) { return true; } } } return false; } /** * @return array{kind: string, what: string, line: int} */ private static function change( string $kind, string $what, int $line ): array { return [ 'kind' => $kind, 'what' => $what, 'line' => $line, ]; } /** * @return array{check: string, kb: string, line: int, severity: string, what: string} */ private static function lead( string $check, string $kb, int $line, string $what, string $severity = 'medium' ): array { return [ 'check' => $check, 'kb' => $kb, 'line' => $line, 'severity' => $severity, 'what' => $what, ]; } /** * The innermost function around a token, or the file's own code. */ public static function unit_at( Source $s, int $i ): int { $best = count( $s->units ) - 1; foreach ( $s->units as $index => $unit ) { if ( 'file' === $unit['kind'] || $unit['decl'] > $i || $i >= $unit['end'] ) { continue; } if ( 'file' === $s->units[ $best ]['kind'] || $unit['decl'] > $s->units[ $best ]['decl'] ) { $best = $index; } } return $best; } /** * @return array|null */ private static function registration( Source $s, string $registrar, int $i ): ?array { $args = $s->args( $i + 1 ); $class = $s->class_name_at( $i ); switch ( $registrar ) { case 'add_action': case 'add_filter': if ( ! isset( $args[1] ) ) { return null; } $hook = self::hook_name( $s, $args[0] ); $kind = self::hook_kind( $hook ); if ( null === $kind ) { return null; } return [ 'type' => 'hook', 'hook' => $hook, 'kind' => $kind, 'callback' => self::callback( $s, $args[1], $class ), ]; case 'add_shortcode': return isset( $args[1] ) ? [ 'type' => 'shortcode', 'callback' => self::callback( $s, $args[1], $class ), ] : null; case 'register_block_type': case 'register_block_type_from_metadata': $open = isset( $args[1] ) ? self::array_at( $s, $args[1], $i ) : null; if ( null === $open ) { return null; } foreach ( $s->items( $open ) as $item ) { if ( 'render_callback' === $item['key'] ) { return [ 'type' => 'block', 'callback' => self::callback( $s, $item['value'], $class ), ]; } } return null; case 'register_rest_route': return isset( $args[2] ) ? self::rest_route( $s, $args, $i, $class ) : null; case 'wp_register_ability': return isset( $args[1] ) ? self::ability( $s, $args, $i, $class ) : null; } return null; } /** * A hook's name, or the fixed start of one built at run time ('wp_ajax_' . $action). * * @param array{0: int, 1: int} $range The name argument. */ private static function hook_name( Source $s, array $range ): string { $literal = $s->literal( $range[0] ); if ( null !== $literal ) { return $literal; } if ( $s->is( $range[0], '"' ) && T_ENCAPSED_AND_WHITESPACE === $s->id( $range[0] + 1 ) ) { return $s->text( $range[0] + 1 ); } return ''; } private static function hook_kind( string $hook ): ?string { if ( 0 === strpos( $hook, 'wp_ajax_nopriv_' ) || 0 === strpos( $hook, 'admin_post_nopriv_' ) ) { return 'nopriv'; } if ( 0 === strpos( $hook, 'wp_ajax_' ) || 0 === strpos( $hook, 'admin_post_' ) ) { return 'ajax'; } if ( 'admin_init' === $hook ) { return 'admin_init'; } if ( in_array( $hook, self::ABILITY_FILTERS, true ) ) { return 'ability_filter'; } return null; } /** * What a callback argument names: a function, a method, or a closure in this file. * * @param array{0: int, 1: int} $range The callback argument. * @return array|null */ public static function callback( Source $s, array $range, ?string $context ): ?array { $a = $range[0]; $literal = $s->only_literal( $range ); if ( null !== $literal ) { if ( '__return_true' === strtolower( $literal ) ) { return [ 'type' => 'true' ]; } if ( false !== strpos( $literal, '::' ) ) { list( $owner, $method ) = explode( '::', $literal, 2 ); return [ 'type' => 'method', 'class' => ltrim( $owner, '\\' ), 'name' => strtolower( $method ), ]; } return [ 'type' => 'fn', 'name' => strtolower( ltrim( $literal, '\\' ) ), ]; } $k = T_STATIC === $s->id( $a ) ? $a + 1 : $a; if ( in_array( $s->id( $k ), [ T_FUNCTION, T_FN ], true ) ) { foreach ( $s->units as $index => $unit ) { if ( $unit['decl'] === $k ) { return [ 'type' => 'unit', 'unit' => $index, ]; } } return null; } // First-class callable syntax: a method or function name followed by (...). if ( T_ELLIPSIS === $s->id( $range[1] - 2 ) && $s->is( $range[1] - 3, '(' ) ) { $name = strtolower( $s->text( $range[1] - 4 ) ); $sep = $s->id( $range[1] - 5 ); if ( T_OBJECT_OPERATOR === $sep ) { return [ 'type' => 'method', 'class' => '$this' === $s->text( $range[1] - 6 ) ? $context : null, 'name' => $name, ]; } if ( T_DOUBLE_COLON === $sep ) { return [ 'type' => 'method', 'class' => self::owner( $s->text( $range[1] - 6 ), $context ), 'name' => $name, ]; } return [ 'type' => 'fn', 'name' => $name, ]; } $open = $s->array_open( $a ); if ( null === $open || $s->close( $open ) + 1 !== $range[1] ) { return null; } $items = $s->items( $open ); if ( 2 !== count( $items ) ) { return null; } $method = $s->only_literal( $items[1]['value'] ); if ( null === $method ) { return null; } $first = $items[0]['value']; $text = $s->norm( $first[0], $first[1] ); $owner = null; if ( '$this' === $text || '__CLASS__' === $text || in_array( strtolower( $text ), [ 'self::class', 'static::class', 'get_class($this)' ], true ) ) { $owner = $context; } elseif ( null !== $s->only_literal( $first ) ) { $owner = ltrim( (string) $s->only_literal( $first ), '\\' ); } elseif ( 1 === preg_match( '/^\\\\?([A-Za-z0-9_\\\\]+)::class$/', $text, $m ) ) { $owner = $m[1]; } return [ 'type' => 'method', 'class' => $owner, 'name' => strtolower( $method ), ]; } private static function owner( string $text, ?string $context ): ?string { return in_array( strtolower( $text ), [ 'self', 'static' ], true ) ? $context : ltrim( $text, '\\' ); } /** * The array literal an argument is, or the one a variable was last set to in the same function. * * @param array{0: int, 1: int} $range The argument. */ private static function array_at( Source $s, array $range, int $at ): ?int { $open = $s->array_open( $range[0] ); if ( null !== $open ) { return $s->close( $open ) + 1 === $range[1] ? $open : null; } if ( 1 !== $range[1] - $range[0] || T_VARIABLE !== $s->id( $range[0] ) ) { return null; } $var = $s->text( $range[0] ); $unit = $s->units[ self::unit_at( $s, $at ) ]; $last = null; for ( $k = $unit['start']; $k < $at; $k++ ) { if ( T_VARIABLE === $s->id( $k ) && $var === $s->text( $k ) && $s->is( $k + 1, '=' ) ) { $last = $s->array_open( $k + 2 ); } } return $last; } /** * register_rest_route( $namespace, $route, $args ): each endpoint's methods, callback and * permission callback (CODE-002). * * @param array $args The call's arguments. * @return array|null */ private static function rest_route( Source $s, array $args, int $i, ?string $context ): ?array { $open = self::array_at( $s, $args[2], $i ); if ( null === $open ) { return null; } $items = $s->items( $open ); $endpoints = []; $keys = array_filter( array_column( $items, 'key' ) ); if ( array_intersect( $keys, [ 'methods', 'callback', 'permission_callback' ] ) ) { $endpoints[] = $items; } else { foreach ( $items as $item ) { $inner = null === $item['key'] ? $s->array_open( $item['value'][0] ) : null; if ( null !== $inner ) { $endpoints[] = $s->items( $inner ); } } } $route = [ 'type' => 'rest', 'route' => self::route_name( $s, $args[0], $args[1] ), 'endpoints' => [], ]; foreach ( $endpoints as $endpoint ) { $methods = false; $callback = null; $permission = [ 'type' => 'missing' ]; foreach ( $endpoint as $item ) { if ( 'methods' === $item['key'] ) { $methods = self::non_get( $s, $item['value'] ); } elseif ( 'callback' === $item['key'] ) { $callback = self::callback( $s, $item['value'], $context ); } elseif ( 'permission_callback' === $item['key'] ) { $permission = self::callback( $s, $item['value'], $context ) ?? [ 'type' => 'other' ]; } } $route['endpoints'][] = [ 'non_get' => $methods, 'callback' => $callback, 'permission' => $permission, ]; } return $route; } /** * @param array{0: int, 1: int} $ns The namespace argument. * @param array{0: int, 1: int} $route The route argument. */ private static function route_name( Source $s, array $ns, array $route ): string { $name = $s->only_literal( $ns ) ?? $s->norm( $ns[0], $ns[1] ); $path = $s->only_literal( $route ) ?? $s->norm( $route[0], $route[1] ); return trim( $name, '/' ) . '/' . ltrim( $path, '/' ); } /** * Whether a route's methods include one that changes something; null when they can't be read. * * @param array{0: int, 1: int} $range The methods value. */ private static function non_get( Source $s, array $range ): ?bool { $seen = false; $changes = false; for ( $k = $range[0]; $k < $range[1]; $k++ ) { $literal = $s->literal( $k ); if ( null !== $literal ) { foreach ( explode( ',', strtoupper( $literal ) ) as $method ) { $method = trim( $method ); $seen = $seen || '' !== $method; $changes = $changes || in_array( $method, [ 'POST', 'PUT', 'PATCH', 'DELETE' ], true ); } } elseif ( T_STRING === $s->id( $k ) && T_DOUBLE_COLON === $s->id( $k - 1 ) ) { $constant = strtoupper( $s->text( $k ) ); $seen = $seen || in_array( $constant, [ 'READABLE', 'CREATABLE', 'EDITABLE', 'DELETABLE', 'ALLMETHODS' ], true ); $changes = $changes || in_array( $constant, [ 'CREATABLE', 'EDITABLE', 'DELETABLE', 'ALLMETHODS' ], true ); } } return $seen ? $changes : null; } /** * wp_register_ability( $name, $args ) (WordPress 6.9): its permission callback, whether it is * read-only, and its ability_class (CODE-017). * * @param array $args The call's arguments. * @return array|null */ private static function ability( Source $s, array $args, int $i, ?string $context ): ?array { $open = self::array_at( $s, $args[1], $i ); if ( null === $open ) { return null; } $out = [ 'type' => 'ability', 'name' => $s->only_literal( $args[0] ) ?? $s->norm( $args[0][0], $args[0][1] ), 'permission' => null, 'readonly' => false, 'class' => null, ]; foreach ( $s->items( $open ) as $item ) { if ( 'permission_callback' === $item['key'] ) { $out['permission'] = self::callback( $s, $item['value'], $context ) ?? [ 'type' => 'other' ]; } elseif ( 'ability_class' === $item['key'] ) { $text = $s->only_literal( $item['value'] ) ?? $s->norm( $item['value'][0], $item['value'][1] ); $out['class'] = ltrim( (string) preg_replace( '/::class$/i', '', $text ), '\\' ); } elseif ( 'meta' === $item['key'] ) { $out['readonly'] = 1 === preg_match( "/['\"]readonly['\"]=>true/i", $s->norm( $item['value'][0], $item['value'][1] ) ); } } return $out; } }