Jak czytać raport CodeAuditAgent i działać na jego podstawie

Raport bezpieczeństwa jest użyteczny tylko wtedy, gdy zamienia się w scalone poprawki. Raporty CodeAuditAgent są wokół tego zaprojektowane: każde znalezisko jest na tyle konkretne, żeby szybko je zweryfikować, i zawiera poprawkę, którą można dostosować. Ten przewodnik wyjaśnia każdą część raportu, sposób triażu, gdy nie masz dedykowanego inżyniera bezpieczeństwa, i jak potwierdzić, że Twoje poprawki zadziałały.

Co podlega audytowi

Audyt działa na publicznym repozytorium GitHub albo na wklejonym fragmencie kodu. W przypadku repozytoriów CodeAuditAgent czyta domyślną gałąź. Repozytoriów prywatnych nie da się audytować przez adres URL i nie ma jeszcze komentarzy w pull requestach; wyniki żyją w panelu i w eksportach.

To, jak duża część repozytorium jest czytana, zależy od Twojego planu. Plan darmowy obejmuje 1 repozytorium, 3 audyty miesięcznie i do 20 plików na audyt. Starter, za 49 USD miesięcznie, obejmuje 5 repozytoriów, 50 audytów i 40 plików na audyt. Pro, za 199 USD miesięcznie, obejmuje nielimitowane repozytoria, 500 audytów i 80 plików na audyt. Pojedyncze pliki większe niż 60 KB są pomijane. Miesięczne liczniki audytów zerują się na początku każdego miesiąca kalendarzowego (UTC). Wklejony fragment kodu to też szybki sposób na sprawdzenie jednego pliku, o który się martwisz, zanim zaudytujesz całe repozytorium.

Gdy pliki zostaną pominięte z powodu tych limitów, raport jest oznaczony jako częściowa migawka. Potraktuj to oznaczenie poważnie. Czysty raport częściowy oznacza, że przeczytane pliki wyglądają czysto, a nie że czyste jest całe repozytorium. Jeśli pominięto kod, na którym zależy Ci najbardziej, zaudytuj go jako wklejony fragment albo na planie obejmującym więcej plików.

Ocena ryzyka

Na górze każdego raportu jest ocena ryzyka od 0 do 100; eksport Markdown podaje obok niej także ogólną wagę. Wyżej oznacza większe ryzyko. To podsumowanie znalezisk z danego audytu, przydatne do dwóch rzeczy: decyzji, jak pilnie zająć się repozytorium, i śledzenia, czy z czasem jest lepiej.

Nie wyciągaj zbyt daleko idących wniosków z drobnych różnic między niepowiązanymi repozytoriami. Ocena zawsze odnosi się do tego, co zostało zaudytowane, a częściowa migawka widzi mniej kodu. Najwięcej znaczy porównanie tego samego repozytorium przed poprawkami i po nich.

Waga i pewność

Każde znalezisko ma wagę i pewność. Odpowiadają na różne pytania: waga mówi, jak źle byłoby, gdyby znalezisko było prawdziwe, a pewność, jak bardzo recenzent jest przekonany, że jest prawdziwe.

• Krytyczny: bezpośrednio możliwy do wykorzystania, o poważnych skutkach, jak wstrzyknięcie na publicznym endpointcie, obejście uwierzytelniania czy ujawnione poświadczenia produkcyjne.
• Wysoki: prawdziwa podatność wymagająca pewnego warunku wstępnego albo o znaczących, ale ograniczonych skutkach.
• Średni: słabość, która ma znaczenie w połączeniu z innymi błędami, albo o umiarkowanych skutkach.
• Niski: kwestie utwardzania i luki w obronie w głąb.
• Info: obserwacje warte poznania, które same w sobie nie są podatnościami.

Pewność jest wysoka, średnia albo niska. Znalezisko o wysokiej pewności ma wyraźny dowód w przeczytanym kodzie. Znalezisko o niskiej pewności zwykle zależy od czegoś, czego audyt nie mógł zobaczyć, jak middleware w innym pliku, polityka bazy danych czy wartość konfiguracji ustawiana przy wdrożeniu. Niska pewność nie oznacza, żeby je zignorować; oznacza, że przed naprawą człowiek powinien sprawdzić brakujący kontekst.

Anatomia znaleziska

Każde znalezisko ma tę samą strukturę, więc możesz je weryfikować w stałej kolejności.

• Tytuł i CWE: klasa słabości, na przykład CWE-639 dla obejścia autoryzacji przez klucz kontrolowany przez użytkownika. CWE mówi, jakiego rodzaju poprawki się spodziewać.
• Lokalizacja: plik i linia, żebyś mógł otworzyć kod bezpośrednio.
• Dowód: odpowiedni kod zacytowany z pliku. Sprawdź, czy cytat pasuje do Twojego bieżącego kodu; jeśli linia już się zmieniła, znalezisko może być nieaktualne.
• Scenariusz ataku: jak atakujący rzeczywiście wykorzystałby tę słabość, krok po kroku. To najszybszy sposób, żeby ocenić, czy w Twoim kontekście jest prawdziwe.
• Poprawka naprawcza: proponowana zmiana w stylu otaczającego kodu.

Traktuj poprawkę jako mocny punkt wyjścia, a nie gotowy do scalenia commit. Jest napisana na podstawie kodu, który przeczytał audyt, więc może nie wiedzieć o Twoich funkcjach pomocniczych, konwencjach Twojego ORM-a ani o wywołaniu w innym miejscu bazy kodu. Typowa poprawka jest mała i celowana:

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Pozytywne obserwacje i kolejne kroki

Raporty wymieniają też to, co jest zrobione dobrze: konsekwentnie stosowane zapytania parametryzowane, sekrety wczytywane ze środowiska, ścisła konfiguracja ciasteczek. Warto to przeczytać. Mówi, które wzorce zachować i kopiować do nowego kodu, i przydaje się, gdy tłumaczysz komuś stan bazy kodu.

Sekcja zalecanych kolejnych kroków zamienia znaleziska w uporządkowany plan. Często grupuje powiązane znaleziska, na przykład kilka brakujących sprawdzeń własności, które najlepiej naprawić jedną wspólną funkcją pomocniczą zamiast pięcioma osobnymi poprawkami.

Proces triażu dla małych zespołów

Bez inżyniera bezpieczeństwa ryzykiem nie jest zignorowanie raportu; jest nim spędzenie dnia na niskich znaleziskach, podczas gdy czeka krytyczne. Prosta kolejność działa dobrze:

• Najpierw przeczytaj wszystkie znaleziska krytyczne i wysokie. Przy każdym przeczytaj scenariusz ataku i zdecyduj: prawdziwe, nieprawdziwe albo wymaga kontekstu.
• Prawdziwe znaleziska krytyczne napraw tego samego dnia. Jeśli poprawka wymaga czasu, dodaj tymczasowe ograniczenie, na przykład wyłączenie endpointu albo zaostrzenie sprawdzenia.
• Przy znaleziskach wymagających kontekstu sprawdź brakujący element: czy jest middleware, polityka na poziomie wierszy albo konfiguracja, która już temu zapobiega? Zapisz odpowiedź.
• Zaplanuj znaleziska wysokie w bieżącym sprincie, średnie w backlogu, a niskie i informacyjne zbierz w jedną rundę utwardzania.
• Gdy znalezisko nie jest prawdziwe, zapisz dlaczego. Ta notatka oszczędzi kolejnej osobie powtórnego badania sprawy.

Przypisz każde znalezisko jednemu właścicielowi. Znaleziska wspólne dla całego zespołu zwykle nie należą do nikogo.

Przeglądarka znalezisk i eksporty

Gdy masz już kilka audytów, łatwiej pracuje się z przeglądarki znalezisk niż z pojedynczych raportów. Wymienia ona znaleziska z wielu audytów i filtruje je według wagi, CWE i repozytorium. Filtrowanie według CWE jest szczególnie przydatne: jeśli ta sama słabość pojawia się w trzech repozytoriach, zwykle wskazuje na wspólny wzorzec lub brakującą funkcję pomocniczą, a naprawa wzorca jest tańsza niż naprawa każdego przypadku z osobna.

Znaleziska można wyeksportować z przeglądarki do CSV, co przydaje się przy imporcie do systemu zgłoszeń albo arkusza. Pojedyncze raporty można wyeksportować jako Markdown, który dobrze się czyta w opisie pull requesta, na wewnętrznej wiki albo w wiadomości do kontraktora wykonującego naprawę.

Ponowny audyt, żeby potwierdzić poprawkę

Poprawka nie jest gotowa, dopóki jej nie sprawdzisz. Po scaleniu uruchom nowy audyt na tym samym repozytorium. Każdy raport można porównać z poprzednim audytem, więc widzisz, które znaleziska zniknęły, które zostały i czy pojawiło się coś nowego. Ocena ryzyka powinna spaść, gdy naprawisz prawdziwe problemy; jeśli tak się nie dzieje, zajrzyj do porównania, żeby zobaczyć dlaczego.

Zadbaj o uczciwe porównanie. Jeśli pierwszy audyt był częściową migawką, a drugi przeczytał inne pliki, różnica odzwierciedla zarówno zakres, jak i poprawki. Audyty zużywają Twój miesięczny limit, więc zwykle warto zebrać kilka poprawek przed ponownym audytem, zamiast uruchamiać go po każdym commicie.

Czego raport nie obejmuje

Znajomość ograniczeń pomaga wypełnić luki. Audyty czytają Twój kod źródłowy; nie skanują zależności pod kątem znanych podatnych wersji, więc utrzymuj też działający skaner zależności, taki jak ten wbudowany w Twojego menedżera pakietów albo w GitHub. Audyty nie widzą konfiguracji ustawianej przy wdrożeniu, infrastruktury poza repozytorium ani pominiętych plików. I jak każdy recenzent, człowiek czy AI, audyt może się mylić: dowody i poziomy pewności są po to, żebyś mógł go szybko sprawdzić, a nie przyjmować na wiarę.

Używany w ten sposób raport staje się krótką, uporządkowaną według priorytetu listą zmian z dołączonymi dowodami. Napraw te krytyczne, sprawdź te niepewne, zaudytuj ponownie i obserwuj, jak ocena się zmienia.