Bezpieczeństwo Enterprise Plugin
Specyfikacja bezpieczeństwa Enterprise Plugin: jakie uprawnienia potrzebuje proces, jakie reguły firewalla obowiązują i jakie dane faktycznie wymienia z Q247. Skrócony opis tego podziału jest też na stronie Konektory, tu jest pełna, techniczna specyfikacja.
Uprawnienia procesu
Wtyczka działa w lokalnym katalogu i nie wymaga uprawnień administratora. Podczas pracy tworzy w bieżącym katalogu tymczasowe podkatalogi, do których pobiera historię kodu i przyrosty; po zakończeniu analizy efektu i kalorii są usuwane automatycznie.
Uruchamia też lokalną bazę danych, w której przechowuje konfigurację, parametry połączenia oraz informacje o repozytoriach potrzebne do komunikacji.
Wtyczka nie ma dostępu do żadnych katalogów poza swoim katalogiem domowym.
Reguły firewalla
Ruch wychodzący
| Źródło | Port źródłowy | Cel | Port docelowy | Zastosowanie |
|---|---|---|---|---|
| host wtyczki | dowolny | adres repozytorium Git Klienta | 443 | Wtyczka łączy się przez HTTPS, żeby pobrać dane z repozytorium Git. |
| host wtyczki | dowolny | backend Q247 | 443 | Wtyczka wysyła "odciski" przyrostów przez HTTPS do panelu centralnego oraz pobiera konfigurację konektorów i listę repozytoriów do zeskanowania. Adresy docelowe podaje zespół wdrożeniowy Q247. |
| host wtyczki | dowolny | instancja Jiry albo Confluence Klienta | 443 | Wtyczka odczytuje tickety, statusy i strony przy włączonych integracjach z Jirą i Confluence. |
Ruch przychodzący
Domyślnie cały ruch przychodzący do hosta wtyczki musi być zablokowany.
Jedyny wyjątek dotyczy wdrożeń, w których wtyczka odbiera webhooki z instancji Jiry albo Confluence w wersji Data Center. Wtedy trzeba dopuścić ruch z tych instancji na port, na którym wtyczka faktycznie działa. Port ten wybiera administrator infrastruktury podczas konfiguracji wtyczki. Ruch pozostaje wewnątrz sieci i nie wymaga dostępu z internetu. Sposób uruchamiania HTTPS i HTTP opisuje sekcja Dostęp sieciowy.
Wersje chmurowe Jiry i Confluence nie potrzebują żadnej reguły przychodzącej, bo ich zdarzenia trafiają do odbiornika po stronie Q247.
Inspekcja TLS na firewallu
Jeśli firewall Klienta terminuje połączenia TLS i podpisuje je ponownie własnym certyfikatem, wtyczka nie rozpozna certyfikatu backendu Q247 i połączenie się nie uda. Rozwiązaniem jest przekazanie zespołowi wdrożeniowemu pliku PEM z certyfikatem firmowego CA, opisane w Instalacji. Weryfikację certyfikatów wyłącza się wyłącznie awaryjnie.
Wymiana danych
Cała komunikacja między Enterprise Plugin a Q247 Management Portal jest zabezpieczona HTTPS:
- Minimalna wersja TLS: 1.2
- Wyłącznie HTTPS: tak
Treść zmian w kodzie oraz treść ticketów i stron zostaje na hoście wtyczki. Analiza odbywa się lokalnie, a do Q247 idzie jej wynik wraz z metadanymi potrzebnymi do metryk. Poniższe tabele wymieniają te metadane wyczerpująco.
Zdarzenia z repozytoriów kodu
| Kategoria | Co konkretnie |
|---|---|
| Identyfikacja zmiany | identyfikator commita, adres repozytorium zdalnego, typ repozytorium, znacznik czasu autorstwa |
| Autor | imię i nazwisko oraz adres e-mail commitera, w postaci zapisanej w Git |
| Wiadomość commita | pełna treść wiadomości, bez obcinania. Jest potrzebna do rozpoznania klucza ticketu i adnotacji narzędzi AI, więc trafia do Q247 w całości |
| Lista zmienionych plików | ścieżki i nazwy plików wraz z liczbą wstawionych i usuniętych linii oraz wynikiem kalorycznym każdego z nich |
| Podsumowanie zmiany | liczba plików, liczba wstawionych i usuniętych linii |
| Gałęzie | nazwy gałęzi, na których commit znajdował się w momencie skanowania |
| Wynik analizy | wynik kaloryczny, wektor wysiłku, nazwa i wersja modelu wyliczającego |
| Kontekst Q247 | identyfikator organizacji i projektu |
| Klucz ticketu | identyfikator rozpoznany w wiadomości commita, wraz z jego prefiksem |
| Dane diagnostyczne | informacja o tym, że lista plików albo treść zmiany została przycięta z powodu rozmiaru, wraz z liczbami opisującymi skalę przycięcia |
Ścieżki plików są niezbędne do działania Wykluczeń wzorców plików i do rozpoznawania duplikatów commitów, dlatego przekazywane są razem z każdym zdarzeniem i przechowywane. Wiadomość commita przekazywana jest w całości, bo z niej odczytywany jest klucz ticketu i adnotacja narzędzia AI; jest przy tym tekstem pisanym swobodnie przez człowieka, więc jego zawartość zależy wyłącznie od praktyki zespołu.
Sama treść plików, czyli różnica między wersjami kodu, jest usuwana przed wysyłką i nie opuszcza hosta wtyczki.
Zdarzenia z pull requestów
Wtyczka rozpoznaje pull i merge requesty jako osobny rodzaj zdarzenia. Przekazywane są: tytuł, pełny opis, adres URL, identyfikator i numer, gałąź docelowa wraz z informacją o jej ochronie, status, znacznik wersji roboczej, lista identyfikatorów commitów wchodzących do żądania, identyfikator commita scalającego, znaczniki czasu (otwarcie, gotowość do review, pierwszy i ostatni review, scalenie, zamknięcie) oraz lista recenzentów z ich adresami e-mail i wynikiem review.
Poza tym zakresem do Q247 nie trafia kod źródłowy, różnice między wersjami plików ani treść komentarzy z code review. Zapisywany jest wynik review, bez jego przebiegu.
Dane pochodzą z GitLaba, GitHuba, Bitbucketa, Gerrita i Azure DevOps, w wariantach chmurowym i instalowanym lokalnie. Pobieranie uruchamia się automatycznie wraz z dodaniem połączenia do repozytorium i nie wymaga osobnej konfiguracji.
Informacje o repozytoriach
| Kierunek | Co jest przekazywane |
|---|---|
| Q247 → wtyczka | adres serwera Git, dane dostępowe konektora oraz lista repozytoriów do skanowania |
| Wtyczka → Q247 | nazwa repozytorium, adres URL, nazwa grupy, status synchronizacji i skanowania wraz z datą |
Token dostępu do repozytoriów wędruje wyłącznie w pierwszym kierunku, razem z konfiguracją konektora. Wtyczka nie wysyła tokenu do Q247. Wyjątkiem jest konektor Generic GIT, w którym poświadczenia stanowią część adresu repozytorium i trafiają do Q247 razem z tym adresem. Jeśli konektor korzysta ze zmiennej środowiskowej, token nie przechodzi nawet w tę stronę: w Q247 zapisana jest sama nazwa zmiennej.
Telemetria narzędzi AI
Jeśli organizacja korzysta z Logów narzędzi AI, wtyczka przekazuje dobowe podsumowania per użytkownik: adres e-mail identyfikujący osobę w narzędziu AI, dzień, nazwę narzędzia, liczbę tokenów w podziale na wejściowe, wyjściowe i cache, koszt, liczbę wygenerowanych i usuniętych linii, liczbę commitów i pull requestów, liczbę sesji oraz czas aktywnej pracy.
Prompty i odpowiedzi modelu nie są przekazywane. Przekazywane są wyłącznie liczniki.
Wyniki retencji
Trwałość kodu wyliczana jest lokalnie, przez porównanie stanu repozytorium po 1, 7, 30 i 90 dniach. Do Q247 trafiają: identyfikator commita, udział linii, które przetrwały w każdym z czterech punktów, liczba dodanych linii, informacja o tym, czy commit znalazł się na gałęzi głównej, nazwy gałęzi użytych jako punkt odniesienia oraz znacznik czasu wyliczenia.
Zdarzenia z Jiry i Confluence
Ten sam mechanizm, lokalna analiza treści i wysyłka tylko wyniku, obowiązuje dla Jiry i Confluence. Enterprise Plugin otrzymuje z nich zdarzenia webhookami albo sam odpytuje ich API według harmonogramu, zależnie od sposobu pobierania danych wybranego w konektorze (→ Jira, Confluence). Do Q247 trafiają:
Informacje o ticketach (Jira):
- klucz i typ ticketu, adres URL,
- osoba przypisana, wraz z jej imieniem, nazwiskiem i adresem e-mail, oraz osoba przypisana przed zmianą,
- historia zmian statusu: nazwa statusu przed i po zmianie, kategoria każdego z nich oraz moment zmiany, potrzebne do Czasu realizacji i Czasu cyklu,
- wynik kaloryczny,
- liczba wstawionych i usuniętych znaków oraz liczba plików w zmianie, bez ich treści,
- lista identyfikatorów zmienionych pól.
Z historii statusów powstaje po stronie Q247 zestawienie cyklu życia ticketu, obejmujące moment pierwszego wejścia w pracę, moment zakończenia, liczbę powrotów oraz przedziały czasu przypisane do poszczególnych osób.
Informacje o stronach (Confluence):
- identyfikator strony oraz klucz przestrzeni, adres URL, a przy wiki także ścieżka strony,
- autor, wraz z adresem e-mail,
- rodzaj zdarzenia (nowa wersja strony albo komentarz) oraz moment publikacji wersji albo dodania komentarza,
- wynik kaloryczny,
- liczba wstawionych i usuniętych znaków oraz liczba plików w zmianie, bez ich treści,
- identyfikator zdarzenia zawierający adres instancji Confluence z formularza konektora, w Enterprise Plugin od wersji
q247-enterprise-plugin-linux-v2.6.0, - lista identyfikatorów zmienionych pól.
Każde zdarzenie z Confluence ma powyższy zestaw pól, niezależnie od tego, czy pochodzi z webhooka, z odpytywania API czy z uzupełniania danych historycznych. Zdarzenia nie zawierają treści stron, komentarzy ani opisów wersji.
Lista do uzgodnienia (Confluence, odpytywanie API i uzupełnianie danych historycznych):
Oprócz zdarzeń wtyczka wysyła do Q247 osobną listę elementów, którą Q247 porównuje z danymi już zapisanymi. Dzieje się to w dwóch sytuacjach: przy uzgadnianiu ostatnich 24 godzin po przejściu na tryb odpytywania API oraz przy uzupełnianiu danych historycznych. Lista nie zawiera treści stron ani komentarzy, a składa się z:
- danych każdej strony: identyfikator strony, klucz przestrzeni, moment utworzenia oraz znaczniki techniczne (rodzaj kontenera i informacja, czy historia strony jest kompletna),
- danych każdej wersji i każdego komentarza: rodzaj elementu, identyfikator zdarzenia, identyfikator wersji albo komentarza (dla wersji także jej numer), moment utworzenia, wynik kaloryczny, liczba wstawionych znaków oraz informacja, czy element podlega ocenie,
- danych autora każdego elementu: imię i nazwisko, adres e-mail, identyfikator konta w Confluence i jego aliasy, w wersji Data Center łącznie z adresem zastępczym,
- danych całego przebiegu: identyfikator przebiegu, tryb i opcje przebiegu, adres instancji Confluence z formularza konektora oraz numer wersji wtyczki.
Dane diagnostyczne i wersja wtyczki
Poza danymi o pracy wtyczka przekazuje informacje potrzebne do utrzymania integracji: numer swojej wersji przy każdym połączeniu oraz zgłoszenia błędów, zawierające treść komunikatu błędu, adres repozytorium i identyfikator projektu, przy którym błąd wystąpił. Służą one diagnostyce po stronie Q247 i nie zawierają treści analizowanych danych.
Lista zmienionych pól
Zdarzenie niesie informację o tym, które pola zostały zmienione, bez ich nowych wartości. Słownik jest zamknięty i wspólny dla Jiry, Confluence oraz Azure DevOps:
| Identyfikator | Czego dotyczy |
|---|---|
title | tytuł, w Jirze odpowiada polu podsumowania |
description | opis |
body | treść strony albo dokumentu wiki |
message | opis wersji, czyli komentarz do zapisu zmiany |
status | zmiana statusu |
assignee | zmiana osoby przypisanej |
comment | dodanie albo zmiana komentarza |
acceptanceCriteria | kryteria akceptacji |
reproSteps | kroki odtworzenia błędu |
deleted | usunięcie |
Słownik jest zamknięty: zmiana pola spoza tej listy nie jest raportowana. Treść zmian, przechowywana lokalnie na potrzeby analizy, jest usuwana przed wysyłką, więc przekazywana jest sama informacja o tym, że dane pole zostało zmienione.
Doprecyzowanie zakresu treści
Treść ticketów, stron i komentarzy nie jest przekazywana do Q247. Istnieje jednak jeden wyjątek.
Q247 rozpoznaje powiązanie strony Confluence z ticketem, wyszukując jego identyfikator w treści strony, jej tytule oraz opisie wersji. Rozpoznany identyfikator jest przekazywany jako metadana, więc fragment treści strony trafia do backendu wtedy, gdy zawiera odwołanie do ticketu.
Wartość dłuższa niż 64 znaki jest pomijana w całości, a nie obcinana. Ograniczenie działa po stronie Q247, przy przenoszeniu zdarzenia do warstwy analitycznej, więc w samym zdarzeniu wartość zostaje zapisana w postaci, w jakiej ją rozpoznano.
Uwierzytelnienie odbiornika webhooków
Odbiornik webhooków jest uwierzytelniony osobnym, losowym kluczem API generowanym dla każdej organizacji i wbudowanym w adres URL webhooka. Żądanie z nieznanym albo niepoprawnym kluczem jest odrzucane odpowiedzią o braku autoryzacji.
Ponieważ sekret jest częścią adresu, sam adres webhooka należy traktować jak hasło: nie umieszczać go w zgłoszeniach, dokumentacji wewnętrznej ani na kanałach czatu.
Dostęp do repozytoriów kodu
Dostęp do repozytoriów źródłowych obsługują odpowiednie tokeny dostępu, którymi wtyczka łączy się z repozytorium. Wymagany jest wyłącznie dostęp do odczytu, token musi być tak skonfigurowany po stronie SCM.
Wtyczka odczytuje wszystkie repozytoria, do których ma dostęp (ewentualne ograniczenia ustawia się w samym systemie SCM albo przez zakres uprawnień tokenu), a lokalnie odczytuje też historię przyrostów z tych repozytoriów.
Zobacz też
- Konektory: co zostaje lokalnie u Klienta, a co trafia do Q247, opisane od strony administratora
- Instalacja: Cloud Plugin kontra Private Plugin