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 nasłuchuje webhooków; numer portu dla danego wdrożenia podaje zespół wdrożeniowy Q247. Ruch pozostaje wewnątrz sieci Klienta i nie wymaga dostępu z internetu.
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 przeglądu, pierwszy i ostatni przegląd, scalenie, zamknięcie) oraz lista recenzentów z ich adresami e-mail i wynikiem przeglądu.
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, które Enterprise Plugin obsługuje przez webhooki, nie skanowanie:
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,
- wynik kaloryczny,
- lista identyfikatorów zmienionych pól.
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