Formularz z polem „Dodaj załącznik” wygląda niewinnie. Użytkownik wybiera plik, klika „Wyślij”, aplikacja zapisuje go na dysku. Kilka linijek kodu, często napisanych w pół godziny.

Tymczasem to jedno z niewielu miejsc w aplikacji, w którym obca osoba może umieścić na Twoim serwerze dowolną zawartość. Nie tekst w polu formularza, który trafi do bazy, tylko cały plik, który leży potem na dysku obok Twojego kodu. Jeżeli ten plik okaże się skryptem PHP, a serwer da się namówić do jego uruchomienia, atakujący przestaje być użytkownikiem aplikacji. Staje się kimś, kto wykonuje na serwerze własny kod.

W tym artykule pokażę, jak zbudować upload, który nie polega na jednym zabezpieczeniu, tylko na kilku niezależnych warstwach. Każda z nich łapie inny rodzaj problemu, a razem sprawiają, że pojedynczy błąd nie kończy się przejęciem serwera. Przykłady dotyczą Laravela, nginx i PHP-FPM na AlmaLinux 10, ale zasady przeniesiesz do dowolnego frameworka.

Jak wygląda atak przez upload?

Najprostszy scenariusz

Wyobraź sobie aplikację, która zapisuje zdjęcia profilowe w katalogu public/avatars, czyli tam, skąd serwer WWW serwuje pliki bezpośrednio. Ktoś zamiast zdjęcia wysyła plik avatar.php z jedną linijką:

<?php system($_GET['cmd']);

Jeżeli aplikacja zachowa oryginalną nazwę, a nginx przekazuje do PHP każdy plik kończący się na .php, wystarczy teraz otworzyć adres https://twoja-aplikacja.pl/avatars/avatar.php?cmd=id. Serwer wykona polecenie i odeśle wynik. Taki plik nazywa się webshellem i jest jednym z najczęstszych sposobów, w jaki atakujący zdobywają przyczółek na serwerze.

„Ale ja sprawdzam rozszerzenie”

Pierwszy odruch to sprawdzenie, czy plik kończy się na .jpg. Problem w tym, że nazwa pliku i deklarowany typ MIME pochodzą od klienta. Atakujący ustawia je, jak chce. Sprawdzanie ich przypomina pytanie gościa w drzwiach, czy jest listonoszem.

Trochę lepiej jest sprawdzić zawartość pliku. Większość formatów zaczyna się od charakterystycznych bajtów, tak zwanych magic bytes. JPEG zaczyna się od FF D8 FF, PNG od 89 50 4E 47, GIF od tekstu GIF89a. PHP potrafi je rozpoznać przez rozszerzenie fileinfo i Laravel z tego korzysta.

Tyle że to też da się obejść. Plik zaczynający się od GIF89a, a dalej zawierający kod PHP, zostanie rozpoznany jako obraz GIF. Taki plik, poprawny jednocześnie w dwóch formatach, nazywa się poliglotą. Sprawdzenie zawartości odsiewa przypadkowe śmieci i proste ataki, ale nie daje gwarancji.

Wniosek: jedna warstwa to za mało

Każde z tych zabezpieczeń ma lukę. Dlatego zamiast szukać jednego idealnego sprawdzenia, ułożymy kilka warstw, z których każda zakłada, że poprzednia mogła zawieść:

  1. Pliki trafiają poza katalog publiczny i dostają nazwy nadane przez aplikację.

  2. nginx przekazuje do PHP wyłącznie jeden plik: index.php.

  3. Katalog z plikami leży na osobnej partycji z opcjami noexec, nosuid i nodev.

  4. Aplikacja sprawdza typ pliku po zawartości i przetwarza obrazy od nowa.

  5. Każdy plik przechodzi przez skaner antywirusowy ClamAV.

  6. Pliki wracają do użytkownika przez kontroler, który sprawdza uprawnienia i wymusza pobieranie.

Przejdźmy przez nie po kolei.

Warstwa pierwsza: pliki poza webrootem

Dlaczego katalog public to złe miejsce

Webroot to katalog, którego zawartość serwer WWW udostępnia bezpośrednio pod adresem URL. W Laravelu jest nim public/. Wszystko, co tam trafi, jest dostępne dla każdego, kto zna albo zgadnie ścieżkę, a nginx decyduje o tym, co z danym plikiem zrobić, wyłącznie na podstawie swojej konfiguracji.

Jeżeli pliki użytkowników leżą poza webrootem, nie da się ich otworzyć bezpośrednio z przeglądarki. Nie ma adresu URL, który by do nich prowadził. Jedyną drogą jest kod aplikacji, który świadomie zdecyduje, komu i w jakiej formie plik oddać.

W Laravelu łatwo tu o pomyłkę. Dysk public z pliku config/filesystems.php zapisuje pliki w storage/app/public, a polecenie php artisan storage:link tworzy do niego dowiązanie z public/storage. Czyli pliki „w storage” są w praktyce publiczne. Do plików od użytkowników ten dysk się nie nadaje.

Osobny dysk dla uploadów

Dodaj w config/filesystems.php własny dysk, wskazujący katalog poza projektem:

'disks' => [
    // ...

    'uploads' => [
        'driver' => 'local',
        'root' => env('UPLOADS_ROOT', '/srv/uploads'),
        'visibility' => 'private',
        'throw' => true,
    ],
],

Katalog /srv/uploads przygotujemy za chwilę jako osobną partycję. Opcja throw sprawia, że błąd zapisu rzuci wyjątek, zamiast po cichu zwrócić false, co przy uploadzie łatwo przeoczyć.

Nazwa pliku należy do aplikacji

Druga zasada tej warstwy: nigdy nie używaj nazwy pliku podanej przez użytkownika jako nazwy na dysku. Może zawierać ../, znaki specjalne, rozszerzenie .php albo po prostu nadpisać plik innego użytkownika.

Metoda store() w Laravelu robi to dobrze: generuje losową nazwę, a rozszerzenie dobiera na podstawie rozpoznanej zawartości, a nie nazwy od klienta. Oryginalną nazwę warto zapisać w bazie danych, żeby pokazać ją użytkownikowi i użyć przy pobieraniu, ale to tylko etykieta, nie ścieżka.

Warstwa druga: nginx uruchamia tylko index.php

Problem z regułą „każdy plik .php”

Wiele konfiguracji nginx, które krążą w internecie, zawiera regułę w stylu:

location ~ \.php$ {
    fastcgi_pass unix:/run/php-fpm/www.sock;
    # ...
}

Oznacza ona: każdy plik kończący się na .php, gdziekolwiek leży w webroocie, przekaż do PHP-FPM, czyli procesu wykonującego kod PHP. Jeżeli jakimkolwiek sposobem plik .php trafi do katalogu publicznego, na przykład przez błąd w innym miejscu aplikacji albo źle ustawiony dysk, zostanie wykonany.

Laravel takiej elastyczności nie potrzebuje. Cały ruch przechodzi przez jeden plik, public/index.php. Możemy więc powiedzieć nginx wprost: wykonuj ten jeden plik, a wszystkie inne pliki PHP traktuj jak nieistniejące.

Konfiguracja

Fragment konfiguracji serwera (ścieżki zastąp własnymi):

server {
    listen 443 ssl;
    server_name twoja-aplikacja.pl;
    root /var/www/app/public;
    index index.php;

    # Limit rozmiaru żądania, spójny z limitem w aplikacji
    client_max_body_size 12m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # Jedyny plik PHP, który wolno wykonać
    location = /index.php {
        fastcgi_pass unix:/run/php-fpm/www.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Każdy inny plik .php nie istnieje
    location ~ \.php$ {
        return 404;
    }

    # Ukryte pliki, np. .env albo .git
    location ~ /\.(?!well-known) {
        deny all;
    }
}

Lokalizacja ze znakiem = oznacza dokładne dopasowanie i nginx sprawdza ją przed wyrażeniami regularnymi. Żądanie /index.php trafia więc do PHP, a /avatars/avatar.php dostaje odpowiedź 404, nawet jeśli taki plik fizycznie istnieje.

Po zmianie sprawdź składnię i przeładuj konfigurację:

sudo nginx -t && sudo systemctl reload nginx

Druga linia obrony w PHP-FPM

PHP-FPM ma własne zabezpieczenie: dyrektywę security.limit_extensions, która określa, jakie pliki proces zgodzi się wykonać. Domyślnie jest to .php (w starszych wersjach także .phar, .php3 i podobne). Upewnij się, że w pliku puli, zwykle /etc/php-fpm.d/www.conf, jest ustawione:

security.limit_extensions = .php

Dzięki temu nawet źle skonfigurowany serwer WWW nie namówi PHP-FPM do wykonania pliku zdjecie.jpg jako skryptu.

Warstwa trzecia: osobna partycja z noexec

Co naprawdę robi noexec

Opcje montowania to instrukcje dla jądra systemu, jak ma traktować pliki na danej partycji:

  • noexec zabrania uruchamiania plików jako programów;

  • nosuid sprawia, że bit setuid jest ignorowany, więc plik nie może uruchomić się z uprawnieniami innego użytkownika, na przykład roota;

  • nodev zabrania traktowania plików jako urządzeń systemowych.

Dla katalogu, do którego obcy ludzie wgrywają pliki, wszystkie trzy mają sens. Nie ma żadnego uprawnionego powodu, żeby ktokolwiek uruchamiał stamtąd programy.

Czego noexec nie robi

Tu jest pułapka, o której warto wiedzieć, bo wiele osób przecenia tę opcję. noexec blokuje uruchomienie pliku bezpośrednio, czyli tak, jak uruchamia się program: ./plik. Nie blokuje natomiast sytuacji, w której inny program, leżący na zwykłej partycji, otwiera plik i interpretuje jego treść.

Tak właśnie działa PHP. Interpreter php albo PHP-FPM nie uruchamia skryptu jako programu, tylko go czyta. Dla jądra to zwykły odczyt pliku, więc noexec w niczym tu nie przeszkadza. Za chwilę pokażę to na żywo.

Dlaczego więc w ogóle ta warstwa? Bo chroni przed inną klasą ataku. Jeżeli atakujący znajdzie w aplikacji lukę pozwalającą wykonać polecenie systemowe, typowym następnym krokiem jest wgranie skompilowanego narzędzia, na przykład koparki kryptowalut albo programu do dalszego ataku, i uruchomienie go. Katalog uploadów to wymarzone miejsce, bo jest zapisywalny. Na partycji z noexec ten krok się nie uda. Przed wykonaniem skryptów PHP chroni natomiast konfiguracja nginx z poprzedniej warstwy. Każda warstwa ma swoje zadanie.

Przygotowanie woluminu

Przykład zakłada, że korzystasz z LVM i masz wolne miejsce w grupie woluminów. Nazwę grupy vg_data i rozmiar zastąp własnymi. Wszystkie polecenia wykonujesz jako root.

lvcreate -n uploads -L 50G vg_data
mkfs.xfs /dev/vg_data/uploads
mkdir -p /srv/uploads
blkid /dev/vg_data/uploads

Jeżeli katalog /srv/uploads już istnieje i zawiera pliki, najpierw przenieś je w inne miejsce. Zamontowanie partycji przykryje dotychczasową zawartość katalogu, a pliki wrócą do widoku dopiero po odmontowaniu.

Do /etc/fstab dopisz wpis z UUID, który zwróciło blkid:

UUID=TWOJ-UUID  /srv/uploads  xfs  defaults,nodev,nosuid,noexec  0 0

Zamontuj i sprawdź opcje:

systemctl daemon-reload
mount /srv/uploads
findmnt /srv/uploads

W kolumnie OPTIONS powinny być widoczne nosuid, nodev i noexec. Jeżeli findmnt nic nie zwraca, partycja się nie zamontowała i nie warto iść dalej.

Uprawnienia i SELinux

PHP-FPM na AlmaLinux domyślnie działa jako użytkownik apache (sprawdzisz to w dyrektywie user w pliku puli). To on musi móc zapisywać w katalogu:

chown apache:apache /srv/uploads
chmod 750 /srv/uploads

Samo uprawnienie to jednak nie wszystko. SELinux pozwala procesom serwera WWW zapisywać tylko w plikach z odpowiednią etykietą, a nowa partycja jej nie ma. Nadaj ją regułą, która przetrwa ponowne etykietowanie systemu (polecenie semanage pochodzi z pakietu policycoreutils-python-utils):

semanage fcontext -a -t httpd_sys_rw_content_t "/srv/uploads(/.*)?"
restorecon -Rv /srv/uploads
ls -Zd /srv/uploads

Wynik ls -Zd powinien zawierać httpd_sys_rw_content_t. Bez tego kroku zapis z aplikacji skończy się błędem „Permission denied”, mimo poprawnych uprawnień. Nie wyłączaj w takiej sytuacji SELinuksa. To on pilnuje, żeby przejęty proces PHP nie mógł pisać w dowolnym miejscu systemu.

Gdy partycja się nie zamontuje

Jest jeszcze jeden scenariusz, który łatwo przeoczyć. Jeżeli po restarcie partycja się nie zamontuje, katalog /srv/uploads nadal istnieje, tyle że jako zwykły katalog na partycji systemowej. Bez noexec, bez osobnego limitu miejsca. Aplikacja działa dalej i nikt niczego nie zauważa.

Zabezpieczysz się przed tym, uzależniając start PHP-FPM od zamontowania partycji:

systemctl edit php-fpm.service
[Unit]
RequiresMountsFor=/srv/uploads

Teraz PHP-FPM nie wystartuje bez partycji. Aplikacja, która nie działa, jest lepsza niż aplikacja, która działa bez zabezpieczeń i nikt o tym nie wie.

Sprawdźmy to w praktyce

Najpierw spróbuj uruchomić program z nowej partycji:

cp /usr/bin/true /srv/uploads/test-bin
/srv/uploads/test-bin

Zobaczysz komunikat „Permission denied”, mimo że jesteś rootem, a plik ma prawo wykonywania. To działa noexec.

Teraz skrypt PHP:

echo '<?php echo "PHP dziala\n";' > /srv/uploads/test.php
php /srv/uploads/test.php

Skrypt się wykona i wypisze tekst. To dokładnie to ograniczenie, o którym pisałem wyżej: interpreter czyta plik, więc noexec go nie zatrzymuje. Dlatego reguła nginx z poprzedniej warstwy jest tak ważna. Posprzątaj po teście:

rm /srv/uploads/test-bin /srv/uploads/test.php

Warstwa czwarta: walidacja i ponowne przetworzenie

Sprawdzanie typu po zawartości

W Laravelu walidację typu pliku najwygodniej zapisać regułą File:

use Illuminate\Validation\Rules\File;

$request->validate([
    'attachment' => [
        'required',
        File::types(['pdf', 'jpg', 'png'])->max(10 * 1024), // w kilobajtach
    ],
]);

File::types() rozpoznaje typ po zawartości pliku przez fileinfo, a nie po nazwie podanej przez klienta. Lista dozwolonych typów powinna być krótka i wynikać z potrzeb aplikacji. Jeżeli użytkownik ma wysyłać faktury, wystarczy PDF. Nie dodawaj formatów „na zapas”.

Szczególnie uważaj na SVG i HTML. SVG to obraz, ale zapisany jako XML, który może zawierać JavaScript. Otwarty w przeglądarce w kontekście Twojej domeny pozwala na atak XSS, czyli wykonanie obcego skryptu w sesji zalogowanego użytkownika. Jeżeli nie musisz przyjmować SVG, nie przyjmuj.

Limit rozmiaru ustaw spójnie w trzech miejscach: w nginx (client_max_body_size), w PHP (upload_max_filesize i post_max_size) i w walidacji. Każde z nich odrzuca za duże pliki na innym etapie, a ich rozjechanie się daje mylące błędy.

Obraz zapisany od nowa

Pamiętasz poliglotę, czyli plik, który jest jednocześnie obrazem GIF i skryptem PHP? Walidacja po zawartości go przepuści, bo nagłówek jest poprawny. Jest jednak prosty sposób, żeby taki ładunek zniszczyć: wczytać obraz i zapisać go od nowa.

Biblioteka graficzna odczytuje z pliku wyłącznie dane obrazu, czyli piksele, a potem zapisuje je jako nowy plik. Wszystko, co było doklejone obok, w tym kod PHP, po drodze znika. Przy okazji znikają też metadane EXIF, w których zdjęcia z telefonu często zawierają współrzędne GPS miejsca wykonania. Dla prywatności użytkowników to dodatkowa korzyść.

Przykład z biblioteką GD, wbudowaną w PHP (na AlmaLinux pakiet php-gd):

use Illuminate\Validation\ValidationException;

private function reencodeImage(string $path, string $mime): void
{
    // Ochrona przed "bombą dekompresyjną": mały plik, gigantyczne wymiary
    $size = @getimagesize($path);
    if ($size === false || $size[0] > 8000 || $size[1] > 8000) {
        throw ValidationException::withMessages([
            'attachment' => 'Nieprawidłowy lub zbyt duży obraz.',
        ]);
    }

    $image = @imagecreatefromstring(file_get_contents($path));
    if ($image === false) {
        throw ValidationException::withMessages([
            'attachment' => 'Nie udało się odczytać obrazu.',
        ]);
    }

    $saved = match ($mime) {
        'image/jpeg' => imagejpeg($image, $path, 90),
        'image/png' => imagesavealpha($image, true) && imagepng($image, $path),
        default => false,
    };

    if (! $saved) {
        throw ValidationException::withMessages([
            'attachment' => 'Nie udało się przetworzyć obrazu.',
        ]);
    }
}

Sprawdzenie wymiarów przed wczytaniem nie jest przypadkowe. Plik PNG ważący kilkadziesiąt kilobajtów może deklarować wymiary 50 000 na 50 000 pikseli. Po rozpakowaniu w pamięci zająłby gigabajty i położył proces PHP.

Z PDF-ami nie da się postąpić tak prosto. Ich ponowne generowanie jest skomplikowane i często psuje dokument. Tu ciężar przejmują pozostałe warstwy: skaner antywirusowy i sposób, w jaki plik oddajemy użytkownikowi.

Warstwa piąta: skanowanie ClamAV

Czego się spodziewać po antywirusie

ClamAV to otwartoźródłowy skaner antywirusowy, który porównuje pliki z bazą sygnatur znanego złośliwego oprogramowania. Dobrze wyłapuje znane zagrożenia: zainfekowane dokumenty Office, złośliwe PDF-y, popularne webshelle, pliki wykonywalne z malware.

Nie zatrzyma za to webshella napisanego specjalnie pod Twoją aplikację, którego nikt wcześniej nie widział. Dlatego jest jedną z warstw, a nie głównym zabezpieczeniem. Jego największą wartość widać wtedy, gdy pliki od użytkowników trafiają dalej, do innych ludzi: księgowej, która otworzy przesłaną fakturę, albo klienta, który pobierze załącznik. Wtedy serwer nie jest jedynym celem.

Instalacja na AlmaLinux

ClamAV jest dostępny w repozytorium EPEL. Wszystkie polecenia jako root:

dnf install epel-release
dnf install clamav clamd clamav-update

Najpierw pobierz bazę sygnatur. Bez niej skaner nie wystartuje:

freshclam
systemctl enable --now clamav-freshclam

Usługa clamav-freshclam będzie odtąd regularnie aktualizować bazę. Nieaktualny antywirus daje tylko złudne poczucie bezpieczeństwa.

Konfiguracja demona

Skanowanie wykonuje demon clamd, który trzyma bazę sygnatur w pamięci i odpowiada na zapytania przez gniazdo uniksowe. W pliku /etc/clamd.d/scan.conf odkomentuj lub ustaw:

LocalSocket /run/clamd.scan/clamd.sock
LocalSocketGroup virusgroup
LocalSocketMode 660
StreamMaxLength 12M

Jeżeli w pliku jest aktywna linia Example, zakomentuj ją, bo inaczej demon odmówi startu. StreamMaxLength to największy plik, jaki clamd przyjmie do przeskanowania. Ustaw go nie mniejszy niż limit uploadu, bo inaczej większe pliki zostaną odrzucone.

Użytkownik, na którym działa PHP-FPM, musi należeć do grupy virusgroup, żeby mógł połączyć się z gniazdem:

usermod -aG virusgroup apache
systemctl enable --now clamd@scan
systemctl restart php-fpm

Jedna uwaga praktyczna: clamd z załadowaną bazą sygnatur zajmuje w pamięci ponad gigabajt. Na małym serwerze warto to uwzględnić.

Test na pliku EICAR

EICAR to standardowy plik testowy, który każdy antywirus rozpoznaje jako zagrożenie, choć jest całkowicie nieszkodliwy. Służy właśnie do sprawdzania, czy skanowanie działa:

echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!H+H*' > /tmp/eicar.txt
clamdscan --stream /tmp/eicar.txt
rm /tmp/eicar.txt

W wyniku powinno pojawić się Eicar-Signature FOUND. Jeżeli tak jest, demon działa i ma aktualną bazę.

Rozmowa z clamd z poziomu PHP

Aplikacja nie musi uruchamiać zewnętrznych poleceń. clamd obsługuje komendę INSTREAM: wysyłamy mu zawartość pliku przez gniazdo, a on odpowiada, czy znalazł zagrożenie. Ma to dodatkową zaletę: demon nie potrzebuje dostępu do plików aplikacji, bo dostaje same bajty.

Protokół jest prosty. Wysyłamy komendę zINSTREAM zakończoną bajtem zerowym, potem kolejne kawałki pliku, każdy poprzedzony czterobajtową długością, a na końcu kawałek o długości zero. Odpowiedź to stream: OK albo stream: NazwaZagrozenia FOUND.

<?php

namespace App\Security;

use RuntimeException;

final class ClamAvScanner
{
    public function __construct(
        private string $socket = '/run/clamd.scan/clamd.sock',
        private int $chunkSize = 8192,
    ) {}

    /**
     * Zwraca null, gdy plik jest czysty, albo nazwę wykrytego zagrożenia.
     * Każda inna sytuacja kończy się wyjątkiem.
     */
    public function scan(string $path): ?string
    {
        $clamd = @stream_socket_client('unix://' . $this->socket, $errno, $errstr, 5);
        if ($clamd === false) {
            throw new RuntimeException("Brak połączenia z clamd: {$errstr}");
        }
        stream_set_timeout($clamd, 30);

        $file = fopen($path, 'rb');
        if ($file === false) {
            fclose($clamd);
            throw new RuntimeException('Nie można otworzyć pliku do skanowania.');
        }

        try {
            $this->write($clamd, "zINSTREAM\0");

            while (($chunk = fread($file, $this->chunkSize)) !== false && $chunk !== '') {
                $this->write($clamd, pack('N', strlen($chunk)) . $chunk);
            }

            $this->write($clamd, pack('N', 0));
            $response = trim((string) stream_get_contents($clamd), "\0\n ");
        } finally {
            fclose($file);
            fclose($clamd);
        }

        if ($response === 'stream: OK') {
            return null;
        }

        if (str_starts_with($response, 'stream: ') && str_ends_with($response, ' FOUND')) {
            return substr($response, 8, -6);
        }

        throw new RuntimeException("Nieoczekiwana odpowiedź clamd: {$response}");
    }

    private function write($stream, string $data): void
    {
        while ($data !== '') {
            $written = fwrite($stream, $data);
            if ($written === false || $written === 0) {
                throw new RuntimeException('Błąd zapisu do gniazda clamd.');
            }
            $data = substr($data, $written);
        }
    }
}

Zwróć uwagę na jedną decyzję zapisaną w tym kodzie. Jeżeli clamd nie działa, nie odpowiada albo zwraca coś nieoczekiwanego, na przykład błąd przekroczenia rozmiaru, klasa rzuca wyjątek. Plik nie zostanie uznany za czysty. To zasada „fail closed”: gdy zabezpieczenie nie może się wypowiedzieć, odmawiamy. Alternatywa, czyli przepuszczanie plików, gdy skaner nie działa, sprawia, że wystarczy przeciążyć clamd, żeby wyłączyć całą warstwę.

Gdy SELinux zablokuje połączenie

Na systemach z SELinux może się zdarzyć, że proces PHP-FPM nie dostanie zgody na połączenie z gniazdem clamd. Objawem jest błąd połączenia, mimo poprawnych uprawnień do pliku gniazda. Sprawdź, czy w logach są odmowy:

ausearch -m avc -ts recent

Jeżeli widzisz odmowy dotyczące clamd.sock, nie wyłączaj SELinuksa. Możesz przygotować lokalny moduł polityki na podstawie tych odmów, ale zanim go załadujesz, przeczytaj wygenerowany plik .te i upewnij się, że zezwala wyłącznie na połączenie z gniazdem clamd:

ausearch -m avc -ts recent | audit2allow -M php_clamd
cat php_clamd.te
semodule -i php_clamd.pp

Składamy całość w kontrolerze

Kolejność ma znaczenie

Mamy wszystkie elementy. Teraz trzeba je ułożyć w odpowiedniej kolejności. Plik od użytkownika najpierw trafia do katalogu tymczasowego PHP. Tam go walidujemy, skanujemy i przetwarzamy. Dopiero gdy przejdzie wszystkie kontrole, przenosimy go do docelowego katalogu /srv/uploads. Plik, który nie przeszedł weryfikacji, nigdy nie trafia do miejsca, w którym aplikacja trzyma prawdziwe dane.

<?php

namespace App\Http\Controllers;

use App\Models\Document;
use App\Security\ClamAvScanner;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Storage;
use Illuminate\Validation\Rules\File;
use Illuminate\Validation\ValidationException;

class DocumentController extends Controller
{
    public function store(Request $request, ClamAvScanner $scanner)
    {
        $request->validate([
            'attachment' => ['required', File::types(['pdf', 'jpg', 'png'])->max(10 * 1024)],
        ]);

        $file = $request->file('attachment');
        $mime = $file->getMimeType(); // rozpoznany po zawartości

        $threat = $scanner->scan($file->getRealPath());
        if ($threat !== null) {
            Log::warning('Odrzucono plik zawierający zagrożenie', [
                'threat' => $threat,
                'user_id' => $request->user()->id,
                'ip' => $request->ip(),
            ]);

            throw ValidationException::withMessages([
                'attachment' => 'Plik nie przeszedł kontroli bezpieczeństwa.',
            ]);
        }

        if (str_starts_with($mime, 'image/')) {
            $this->reencodeImage($file->getRealPath(), $mime);
        }

        $path = $file->store(date('Y/m'), 'uploads');

        $document = $request->user()->documents()->create([
            'path' => $path,
            'original_name' => mb_substr($file->getClientOriginalName(), 0, 200),
            'mime' => $mime,
            'size' => Storage::disk('uploads')->size($path),
        ]);

        return redirect()->route('documents.show', $document);
    }

    // reencodeImage() jak w rozdziale o ponownym przetwarzaniu
}

Użytkownik, którego plik odrzucono, dostaje ogólny komunikat bez nazwy wykrytego zagrożenia. Szczegóły trafiają do logu, gdzie zobaczy je administrator. Atakujący nie powinien dostawać od aplikacji podpowiedzi, które sygnatury działają.

Duże pliki i kolejka

Skanowanie kilkunastu megabajtów trwa zwykle ułamek sekundy, więc przy typowych załącznikach można to robić od razu, w trakcie żądania. Jeżeli aplikacja przyjmuje duże pliki, lepiej zapisać je najpierw w osobnym katalogu kwarantanny ze statusem „oczekuje na weryfikację”, a skanowanie przenieść do zadania w kolejce. Plik staje się dostępny dopiero po pozytywnym wyniku. Zasada jest ta sama, zmienia się tylko moment wykonania.

Warstwa szósta: bezpieczne oddawanie plików

Kontroler zamiast bezpośredniego linku

Skoro pliki leżą poza webrootem, użytkownik pobiera je przez kontroler. To nie jest wada, tylko zaleta. W tym miejscu aplikacja sprawdza, czy osoba pytająca o plik ma do niego prawo:

public function download(Document $document)
{
    $this->authorize('view', $document);

    return Storage::disk('uploads')->download(
        $document->path,
        $document->original_name,
        ['X-Content-Type-Options' => 'nosniff'],
    );
}

Metoda download() ustawia nagłówek Content-Disposition: attachment, który każe przeglądarce zapisać plik na dysku, zamiast otwierać go w karcie. Nagłówek X-Content-Type-Options: nosniff zabrania przeglądarce zgadywania typu pliku na podstawie zawartości. Razem sprawiają, że nawet jeśli jakiś plik HTML czy SVG przemknie się przez walidację, nie zostanie wyrenderowany w kontekście Twojej domeny.

Jeżeli chcesz wyświetlać obrazy bezpośrednio na stronie, na przykład zdjęcia profilowe, możesz w ich przypadku zrezygnować z attachment. Rób to jednak tylko dla typów, które zostały przetworzone od nowa w warstwie czwartej.

Gdy plików jest dużo: X-Accel-Redirect

Przy dużym ruchu przesyłanie plików przez PHP obciąża procesy PHP-FPM, które w tym czasie nie obsługują innych żądań. nginx ma na to sprytne rozwiązanie. Aplikacja sprawdza uprawnienia, ale zamiast wysyłać plik, odpowiada nagłówkiem X-Accel-Redirect, a samym przesłaniem zajmuje się nginx.

W konfiguracji nginx dodajesz lokalizację oznaczoną jako internal, czyli niedostępną bezpośrednio z zewnątrz:

location /protected-uploads/ {
    internal;
    alias /srv/uploads/;
    add_header X-Content-Type-Options nosniff;
}

A w kontrolerze, po sprawdzeniu uprawnień:

return response('', 200, [
    'X-Accel-Redirect' => '/protected-uploads/' . $document->path,
    'Content-Type' => $document->mime,
    'Content-Disposition' => 'attachment; filename="' . basename($document->path) . '"',
]);

Ścieżka pochodzi z bazy danych i została wygenerowana przez aplikację, więc nie da się nią manipulować. Gdyby była budowana z danych od użytkownika, ten mechanizm otworzyłby drogę do odczytu dowolnych plików z partycji.

Czego ten układ nie załatwia

Logika aplikacji nadal ma znaczenie

Żadna z tych warstw nie ochroni przed błędem w autoryzacji. Jeżeli polityka view przepuszcza każdego zalogowanego użytkownika, każdy zobaczy pliki wszystkich. Bezpieczny upload to nie tylko obrona serwera przed plikami, ale też obrona plików jednych użytkowników przed innymi.

Antywirus nie jest wyrocznią

ClamAV zna to, co już ktoś widział i opisał. Nowe, celowane zagrożenia przejdą. Dlatego w tym układzie skaner jest jedną z sześciu warstw, a nie fundamentem. Gdyby był jedynym zabezpieczeniem, pierwszy nieznany webshell kończyłby sprawę.

Kopia zapasowa i miejsce na dysku

Pliki od użytkowników to dane unikalne, których nie odtworzysz z żadnego repozytorium. Partycja /srv/uploads musi być objęta kopią zapasową. Osobny wolumin ma tu też praktyczną zaletę: gdy ktoś zacznie masowo wysyłać pliki, zapełni się tylko on, a system i baza danych pracują dalej.

Podsumowanie

Upload pliku to moment, w którym aplikacja przyjmuje od obcej osoby coś więcej niż dane. Dlatego zamiast jednego zabezpieczenia budujemy kilka, z których każde odpowiada na inne pytanie.

Pliki poza webrootem i z nazwami nadanymi przez aplikację sprawiają, że nie da się ich otworzyć bezpośrednio. nginx, który wykonuje wyłącznie index.php, odbiera atakującemu możliwość uruchomienia skryptu, nawet jeśli ten trafi tam, gdzie nie powinien. Partycja z noexec blokuje uruchamianie programów, choć, jak sprawdziliśmy, nie zatrzymuje interpretera PHP. Walidacja po zawartości i ponowne zapisanie obrazów niszczą ładunki ukryte w poliglotach. ClamAV wyłapuje znane zagrożenia, zanim trafią do innych ludzi. A kontroler oddający pliki pilnuje uprawnień i nie pozwala przeglądarce wyrenderować czegoś, co powinno zostać pobrane.

Żadna z tych warstw nie jest skomplikowana. Każdą da się wdrożyć w kilkanaście minut. Ich siła bierze się z tego, że błąd w jednej nie otwiera drzwi, bo za nią stoją kolejne.