feat(032): Security Advisories Check – spec, plan, tasks, and config (#4263)

Co-authored-by: ildyria <627094+ildyria@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ildyria <beviguier@gmail.com>

Author: Copilot

app/Actions/Diagnostics/Errors.php

@@ -30,6 +30,7 @@
 use App\Actions\Diagnostics\Pipes\Checks\OpCacheCheck;
 use App\Actions\Diagnostics\Pipes\Checks\PHPVersionCheck;
 use App\Actions\Diagnostics\Pipes\Checks\PlaceholderExistsCheck;
+use App\Actions\Diagnostics\Pipes\Checks\SecurityAdvisoriesCheck;
 use App\Actions\Diagnostics\Pipes\Checks\SmallMediumExistsCheck;
 use App\Actions\Diagnostics\Pipes\Checks\StatisticsIntegrityCheck;
 use App\Actions\Diagnostics\Pipes\Checks\SupporterCheck;
@@ -77,6 +78,7 @@ class Errors
 		WatermarkerEnabledCheck::class,
 		StatisticsIntegrityCheck::class,
 		WebshopCheck::class,
+		SecurityAdvisoriesCheck::class,
 	];
 
 	/**

app/Actions/Diagnostics/Pipes/Checks/SecurityAdvisoriesCheck.php

@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Actions\Diagnostics\Pipes\Checks;
+
+use App\Assets\Features;
+use App\Contracts\DiagnosticPipe;
+use App\DTO\DiagnosticData;
+use App\Models\User;
+use App\Services\SecurityAdvisoriesService;
+use Illuminate\Support\Facades\Auth;
+
+/**
+ * Diagnostic pipe that reports known security vulnerabilities affecting the
+ * currently installed Lychee version.
+ *
+ * Only runs when:
+ *   - the `vulnerability-check` feature flag is enabled, and
+ *   - the currently authenticated user is an administrator.
+ *
+ * Vulnerability data is never disclosed to non-admin users.
+ */
+class SecurityAdvisoriesCheck implements DiagnosticPipe
+{
+	public function __construct(
+		private SecurityAdvisoriesService $service,
+	) {
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function handle(array &$data, \Closure $next): array
+	{
+		if (Features::inactive('vulnerability-check')) {
+			return $next($data);
+		}
+
+		/** @var User|null */
+		$user = Auth::user();
+
+		if ($user?->may_administrate !== true) {
+			return $next($data);
+		}
+
+		$advisories = $this->service->getMatchingAdvisories();
+
+		foreach ($advisories as $advisory) {
+			$identifier = $advisory->cve_id ?? $advisory->ghsa_id;
+			$score = $advisory->cvss_score !== null
+				? number_format($advisory->cvss_score, 1)
+				: '(no CVSS score)';
+
+			$data[] = DiagnosticData::error(
+				'Security vulnerability: ' . $identifier . ' (CVSS ' . $score . ')',
+				self::class,
+				[$advisory->summary],
+			);
+		}
+
+		return $next($data);
+	}
+}

app/DTO/SecurityAdvisory.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\DTO;
+
+/**
+ * Immutable DTO representing a single GitHub Security Advisory that
+ * affects the running Lychee version.
+ */
+class SecurityAdvisory
+{
+	public function __construct(
+		public readonly ?string $cve_id,
+		public readonly string $ghsa_id,
+		public readonly string $summary,
+		public readonly ?float $cvss_score,
+		public readonly ?string $cvss_vector,
+		public readonly string $affected_version_range,
+	) {
+	}
+}

app/Http/Controllers/Admin/SecurityAdvisoriesController.php

@@ -0,0 +1,50 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Controllers\Admin;
+
+use App\Assets\Features;
+use App\Http\Requests\Admin\SecurityAdvisories\IndexSecurityAdvisoriesRequest;
+use App\Http\Resources\Models\SecurityAdvisoryResource;
+use App\Services\SecurityAdvisoriesService;
+use Illuminate\Routing\Controller;
+
+/**
+ * Admin controller that exposes the list of security advisories matching
+ * the currently installed Lychee version.
+ *
+ * Only administrators may call this endpoint. Non-admins receive 403.
+ * When the vulnerability-check feature is disabled the endpoint returns an
+ * empty array.
+ */
+class SecurityAdvisoriesController extends Controller
+{
+	public function __construct(
+		private SecurityAdvisoriesService $service,
+	) {
+	}
+
+	/**
+	 * Return the list of advisories that affect the running Lychee version.
+	 *
+	 * @param IndexSecurityAdvisoriesRequest $_request
+	 *
+	 * @return SecurityAdvisoryResource[]
+	 */
+	public function index(IndexSecurityAdvisoriesRequest $_request): array
+	{
+		if (Features::inactive('vulnerability-check')) {
+			return [];
+		}
+
+		return array_map(
+			fn ($advisory) => SecurityAdvisoryResource::fromAdvisory($advisory),
+			$this->service->getMatchingAdvisories(),
+		);
+	}
+}

app/Http/Requests/Admin/SecurityAdvisories/IndexSecurityAdvisoriesRequest.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Requests\Admin\SecurityAdvisories;
+
+use App\Http\Requests\AbstractEmptyRequest;
+use App\Models\User;
+use Illuminate\Support\Facades\Auth;
+
+/**
+ * FormRequest for the Security Advisories index endpoint.
+ *
+ * Only administrators may retrieve advisory data.
+ * Unauthenticated requests receive 401 (Laravel default for failed authorize).
+ * Authenticated non-admin requests receive 403.
+ */
+class IndexSecurityAdvisoriesRequest extends AbstractEmptyRequest
+{
+	/**
+	 * Only allow administrators to call this endpoint.
+	 */
+	public function authorize(): bool
+	{
+		/** @var User|null */
+		$user = Auth::user();
+
+		return $user?->may_administrate === true;
+	}
+}

app/Http/Resources/Models/SecurityAdvisoryResource.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Http\Resources\Models;
+
+use App\DTO\SecurityAdvisory;
+use Spatie\LaravelData\Data;
+use Spatie\TypeScriptTransformer\Attributes\TypeScript;
+
+/**
+ * API resource for a single security advisory that affects the running
+ * Lychee version.
+ */
+#[TypeScript()]
+class SecurityAdvisoryResource extends Data
+{
+	public function __construct(
+		public readonly ?string $cve_id,
+		public readonly string $ghsa_id,
+		public readonly string $summary,
+		public readonly ?float $cvss_score,
+		public readonly ?string $cvss_vector,
+	) {
+	}
+
+	/**
+	 * Build a resource from a SecurityAdvisory DTO.
+	 *
+	 * @param SecurityAdvisory $advisory
+	 *
+	 * @return self
+	 */
+	public static function fromAdvisory(SecurityAdvisory $advisory): self
+	{
+		return new self(
+			cve_id: $advisory->cve_id,
+			ghsa_id: $advisory->ghsa_id,
+			summary: $advisory->summary,
+			cvss_score: $advisory->cvss_score,
+			cvss_vector: $advisory->cvss_vector,
+		);
+	}
+}

app/Metadata/Cache/RouteCacheManager.php

@@ -160,6 +160,9 @@ public function __construct()
 
 			'api/v2/Contact' => false,
 			'api/v2/Contact::Init' => new RouteCacheConfig(tag: CacheTag::SETTINGS, user_dependant: false),
+
+			// No need to cache this.
+			'api/v2/Security/Advisories' => false,
 		];
 	}
 

app/Metadata/Json/AdvisoriesRequest.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Metadata\Json;
+
+use Illuminate\Support\Facades\Config;
+
+/**
+ * HTTP request class for the GitHub Security Advisories API.
+ *
+ * Extends JsonRequestFunctions to send the required
+ * "Accept: application/vnd.github+json" header.
+ */
+class AdvisoriesRequest extends JsonRequestFunctions
+{
+	/**
+	 * We just override the constructor.
+	 * The rest is handled directly by the parent class.
+	 */
+	public function __construct()
+	{
+		parent::__construct(
+			Config::get('urls.advisories.api_url'),
+			Config::get('urls.advisories.cache_ttl'),
+			['Accept: application/vnd.github+json'],
+		);
+	}
+}

app/Metadata/Json/ExternalRequestFunctions.php

@@ -19,9 +19,15 @@ class ExternalRequestFunctions implements ExternalRequest
 {
 	protected ?string $data = null;
 
+	/**
+	 * @param string   $url           URL to fetch
+	 * @param int      $ttl_in_days   cache TTL in days
+	 * @param string[] $extra_headers additional HTTP headers to send (e.g. ['Accept: application/json'])
+	 */
 	public function __construct(
 		private string $url,
 		private int $ttl_in_days,
+		private array $extra_headers = [],
 	) {
 	}
 
@@ -114,9 +120,10 @@ private function fetchFromServer(): string
 			'http' => [
 				'method' => 'GET',
 				'timeout' => 1,
-				'header' => [
-					'User-Agent: ' . ini_get('user_agent'),
-				],
+				'header' => array_merge(
+					['User-Agent: ' . ini_get('user_agent')],
+					$this->extra_headers,
+				),
 			],
 		];
 		$context = stream_context_create($opts);