# Bezpieczeństwo

## Przegląd

Neotask jest zaprojektowany z architekturą bezpieczeństwo-jako-priorytet. Brama domyślnie jest powiązana z localhost, wszystkie wrażliwe dane są szyfrowane w spoczynku, a wykonanie agentów może być izolowane w kontenerach.

## Bezpieczeństwo sieci

### Pętla zwrotna domyślnie

Brama nasłuchuje tylko na `127.0.0.1` (localhost), chyba że wyraźnie zmienisz tryb powiązania. Domyślnie brak zewnętrznej ekspozycji sieciowej.

### Uwierzytelnianie

Wszystkie połączenia WebSocket wymagają uwierzytelniania:

- **Uwierzytelnianie tokenem** -- Token bearer (UUID lub niestandardowy ciąg)
- **Uwierzytelnianie hasłem** -- Haszowane hasło (bcrypt)
- **Zaufany proxy** -- Wstępnie uwierzytelnione nagłówki od odwrotnych proxy
- **Lokalne zaufanie** -- Połączenia z pętlą zwrotną są niejawnie zaufane

### Bezpieczeństwo zdalnego dostępu

Dla zdalnego dostępu zalecane podejście to **VPN Tailscale** lub **tunelowanie SSH** -- nigdy nie wystawiaj bramy bezpośrednio na internet.

## Parowanie urządzeń

### Jak działa parowanie

Każdy klient łączący się z bramą musi być sparowany:

1. Urządzenie prezentuje swoją tożsamość (odcisk + klucz publiczny)
2. Brama wydaje wyzwanie parowania (nonce)
3. Urządzenie podpisuje nonce swoim kluczem prywatnym
4. Zatwierdzasz urządzenie przez interfejs użytkownika
5. Brama wydaje token urządzenia dla przyszłych połączeń

### Model zaufania

- **Urządzenia lokalne** (pętla zwrotna) są automatycznie zatwierdzane dla wygody
- **Urządzenia nielokalne** wymagają wyraźnego zatwierdzenia
- Tokeny urządzeń są przechowywane lokalnie i ponownie używane przy ponownym połączeniu
- Urządzenia mogą być odwołane w dowolnym momencie

## Szyfrowanie

### Dane w spoczynku

- **AES-256-GCM** -- Wszystkie tokeny, sekrety i klucze API są szyfrowane w spoczynku
- **Klucze pochodne od maszyny** -- Klucze szyfrowania wyprowadzone przez scrypt z tożsamości urządzenia
- **Brak przechowywania w postaci jawnej** -- Tokeny nigdy nie są przechowywane w postaci jawnej

### Dane w tranzycie

- **TLS** -- HTTPS dla komunikacji API
- **WSS** -- WebSocket Secure dla połączeń bramy (przy użyciu Tailscale Serve lub odwrotnego proxy)
- **Podpisywanie HMAC** -- Integralność żądań z nonce i znacznikiem czasu

## Sandboxing

### Izolacja oparta na Docker

Wykonanie poleceń agenta może być izolowane w kontenerach Docker:

- **Profile per agent** -- Każdy agent może mieć własną konfigurację piaskownicy
- **Limity zasobów** -- Konfigurowalne limity procesora, pamięci i limitu czasu
- **Izolacja sieci** -- Kontenery mogą być izolowane sieciowo
- **Ograniczenie systemu plików** -- Agenci mają dostęp tylko do swojej przestrzeni roboczej
- **Niestandardowe obrazy** -- Używaj wstępnie zbudowanych obrazów z zainstalowanymi konkretnymi narzędziami

### Zakresy piaskownicy

| Zakres | Opis |
|--------|------|
| **Per sesja** | Nowy kontener dla każdej sesji |
| **Per agent** | Trwały kontener per agent |
| **Udostępniony** | Wspólny kontener między agentami |

### Dostęp do przestrzeni roboczej

Agenci z piaskownicą mogą uzyskać dostęp do swojego katalogu przestrzeni roboczej (zamontowanego do kontenera), ale nie mogą uzyskać dostępu do systemu plików hosta poza swoją przestrzenią roboczą.

## Zatwierdzenia Exec

Kontroluj, jakie polecenia agenci mogą wykonywać na węzłach i hoście bramy:

### Tryby

| Tryb | Opis |
|------|------|
| **Lista dozwolonych** | Wykonują się tylko wcześniej zatwierdzone polecenia |
| **Pytaj** | Nieznane polecenia wymagają zatwierdzenia użytkownika |
| **Pełny** | Brak ograniczeń (używaj ostrożnie) |

### Konfiguracja per węzeł

Każdy węzeł (macOS, host headless) ma własną konfigurację zatwierdzania exec, przechowywaną lokalnie. Możesz zezwolić na konkretne binaria (np. `/usr/bin/docker`, `/usr/local/bin/terraform`), blokując wszystko inne.

## Tryb podwyższony

Niektóre operacje wymagają bezpośredniego uruchamiania na hoście bramy (nie w piaskownicy). Tryb podwyższony to:

- Bramkowany przez wyraźne uprawnienie w konfiguracji agenta
- Dostępny tylko na hoście bramy
- Domyślnie wyłączony
- Audytowalny przez logowanie

## Audyt bezpieczeństwa

Wbudowany audyt bezpieczeństwa sprawdza:

- Uprawnienia pliku konfiguracyjnego (powinny wynosić 600)
- Uprawnienia pliku sesji
- Wersja Node.js (poprawki bezpieczeństwa)
- Wykrywanie sekretów w postaci jawnej
- Walidacja listy dozwolonych wtyczek
- Audyt otwartego interfejsu sieciowego
- Kompletność konfiguracji uwierzytelniania

Audyt może automatycznie naprawić wiele problemów po udzieleniu pozwolenia.

## Najlepsze praktyki

1. **Trzymaj bramę na pętli zwrotnej** -- Używaj Tailscale lub SSH dla zdalnego dostępu
2. **Włącz sandboxing** -- Uruchamiaj polecenia agentów w kontenerach Docker
3. **Używaj list dozwolonych exec** -- Ogranicz, które polecenia agenci mogą uruchamiać na węzłach
4. **Ustaw tokeny uwierzytelniające** -- Zawsze konfiguruj uwierzytelnianie tokenem, nawet dla pętli zwrotnej
5. **Przeglądaj uprawnienia agentów** -- Używaj minimalnych profili narzędzi tam, gdzie to możliwe
6. **Aktualizuj Neotask** -- Aktualizacje zawierają poprawki bezpieczeństwa
7. **Regularnie audytuj** -- Uruchamiaj audyty bezpieczeństwa, aby wykryć błędne konfiguracje
8. **Ogranicz ładowanie wtyczek** -- Instaluj tylko zaufane wtyczki