$finding Finding candidate. */ public function validate( array $finding ): void { $keys = array_keys( $finding ); $required = self::REQUIRED; sort( $keys ); sort( $required ); if ( $keys !== $required ) { throw new InvalidArgumentException( 'invalid_finding_fields' ); } $this->identifier( $finding['check_id'] ); $this->identifier( $finding['category'] ); $this->identifier( $finding['subcategory'] ); $this->semver( $finding['check_version'] ); $this->semver( $finding['rule_pack_version'] ); foreach ( array( 'title_key', 'summary_key', 'why_it_matters_key', 'evidence_summary_key', 'next_step_key', 'owner_key', 'limitation_key', 'method' ) as $key ) { $this->identifier( $finding[ $key ] ); } if ( ! in_array( $finding['status'], array( 'pass', 'warning', 'fail', 'info', 'not_tested', 'error' ), true ) ) { throw new InvalidArgumentException( 'invalid_finding_status' ); } if ( ! in_array( $finding['severity'], array( 'critical', 'high', 'medium', 'low', 'info', 'none' ), true ) ) { throw new InvalidArgumentException( 'invalid_finding_severity' ); } if ( ! in_array( $finding['confidence'], array( 'confirmed', 'high', 'medium', 'low' ), true ) ) { throw new InvalidArgumentException( 'invalid_finding_confidence' ); } if ( ! is_array( $finding['coverage'] ) || array( 'observed', 'state', 'total', 'unit' ) !== $this->sorted_keys( $finding['coverage'] ) ) { throw new InvalidArgumentException( 'invalid_finding_coverage' ); } $coverage = $finding['coverage']; $this->identifier( $coverage['unit'] ); if ( ! is_int( $coverage['observed'] ) || ! is_int( $coverage['total'] ) || $coverage['observed'] < 0 || $coverage['observed'] > $coverage['total'] || ! in_array( $coverage['state'], array( 'complete', 'partial', 'none', 'error' ), true ) ) { throw new InvalidArgumentException( 'invalid_finding_coverage' ); } if ( ! is_array( $finding['evidence'] ) || $this->contains_forbidden_key( $finding['evidence'] ) ) { throw new InvalidArgumentException( 'unsafe_finding_evidence' ); } if ( ! is_array( $finding['affected_objects'] ) || ! is_array( $finding['prerequisites'] ) || ! is_array( $finding['source_refs'] ) ) { throw new InvalidArgumentException( 'invalid_finding_collections' ); } foreach ( $finding['affected_objects'] as $object ) { if ( ! is_array( $object ) || array( 'reference', 'type' ) !== $this->sorted_keys( $object ) || ! is_string( $object['reference'] ) || strlen( $object['reference'] ) > 1536 ) { throw new InvalidArgumentException( 'invalid_affected_object' ); } $this->identifier( $object['type'] ); } foreach ( array_merge( $finding['prerequisites'], $finding['source_refs'] ) as $identifier ) { $this->identifier( $identifier ); } if ( ! in_array( $finding['effort_band'], array( 'unknown', 'small', 'medium', 'large' ), true ) || ! in_array( $finding['comparison_state'], array( 'new', 'unchanged', 'resolved', 'regressed' ), true ) ) { throw new InvalidArgumentException( 'invalid_finding_classification' ); } $this->acknowledgement( $finding['acknowledgement'] ); try { new DateTimeImmutable( (string) $finding['first_seen'] ); new DateTimeImmutable( (string) $finding['last_seen'] ); } catch ( \Exception $exception ) { // The previous exception is retained for local debugging, never rendered. // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped throw new InvalidArgumentException( 'invalid_finding_timestamp' ); } } /** * @param mixed $value Identifier candidate. */ private function identifier( $value ): void { if ( ! is_string( $value ) || 1 !== preg_match( '/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/', $value ) ) { throw new InvalidArgumentException( 'invalid_finding_identifier' ); } } /** * @param mixed $value Semantic version candidate. */ private function semver( $value ): void { if ( ! is_string( $value ) || 1 !== preg_match( '/^[0-9]+\.[0-9]+\.[0-9]+$/', $value ) ) { throw new InvalidArgumentException( 'invalid_finding_version' ); } } /** * @param array $value Array value. * @return list */ private function sorted_keys( array $value ): array { $keys = array_keys( $value ); sort( $keys ); return $keys; } /** * @param array $value Evidence subtree. */ private function contains_forbidden_key( array $value ): bool { foreach ( $value as $key => $child ) { if ( is_string( $key ) && in_array( strtolower( $key ), self::FORBIDDEN_EVIDENCE_KEYS, true ) ) { return true; } if ( is_array( $child ) && $this->contains_forbidden_key( $child ) ) { return true; } } return false; } /** * @param mixed $value Local report decision projection. */ private function acknowledgement( $value ): void { if ( null === $value ) { return; } if ( ! is_array( $value ) || array( 'actor_role', 'decided_at', 'decision', 'reason_masked' ) !== $this->sorted_keys( $value ) ) { throw new InvalidArgumentException( 'invalid_finding_acknowledgement' ); } if ( ! in_array( $value['decision'], array( 'acknowledged', 'suppressed' ), true ) || 'administrator' !== $value['actor_role'] || ! is_string( $value['reason_masked'] ) || '' === trim( $value['reason_masked'] ) || strlen( $value['reason_masked'] ) > 500 || 1 === preg_match( '/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/', $value['reason_masked'] ) ) { throw new InvalidArgumentException( 'invalid_finding_acknowledgement' ); } try { new DateTimeImmutable( (string) $value['decided_at'] ); } catch ( \Exception $exception ) { // The exception is retained only for local diagnostics and is never rendered. // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped throw new InvalidArgumentException( 'invalid_finding_acknowledgement', 0, $exception ); } } }