AI Log Assistant

---

Co to robi

LogAssistant przyjmuje surowe logi sieciowe/dostępowe, przepuszcza je przez konfigurowalny silnik reguł (reguły detekcji sygnaturowej i wolumetrycznej) i — gdy reguła zostanie wywołana — przekazuje podejrzaną aktywność agentowi bezpieczeństwa LLM, który bada ją za pomocą realnych narzędzi (bazy wiedzy MITRE ATT&CK i historii aktywności IP), a następnie generuje ustrukturyzowany raport o zagrożeniu: typ, poziom istotności, plan działań naprawczych i rekomendacje. Raporty są zapisywane i transmitowane na żywo przez WebSocket do panelu Streamlit.

To niewielki, kompletny (end-to-end) system, który łączy kilka elementów pojedynczo powszechnych, ale rzadko spotykanych razem w projektach portfolio: detekcję opartą na regułach, agenta LLM z wywoływaniem narzędzi i wyszukiwaniem (retrieval), asynchroniczny zapis danych, autoryzację maszyna–maszyna oraz frontend czasu rzeczywistego — całość zabezpieczona zestawem testów (jednostkowych + integracyjnych, ok. 87% pokrycia), które mockują LLM i bazę wektorową, zamiast faktycznie się z nimi łączyć.

Architektura

flowchart LR
    A[Plik logu] -->|wgranie| B["POST /threat-reports/process-batch"]
    B --> C[LogService]
    C --> D["PolicyEngine\n(reguły sygnaturowe + wolumetryczne)"]
    D -->|reguła wywołana| E["SecurityAgentService\n(agent LangChain, wywoływanie narzędzi)"]
    E -->|wywołanie narzędzia| F[("Qdrant\nbaza wiedzy MITRE ATT&CK")]
    E -->|wywołanie narzędzia| G[Historia aktywności IP]
    E --> H[ThreatReport]
    H --> I[EventDispatcher]
    I --> J[Transmisja WebSocket]
    I --> K[(Baza danych)]
    J --> L[Panel Streamlit]

Analiza wsadowa (/process-batch) jest dostępna wyłącznie w komunikacji maszyna–maszyna, zabezpieczona tokenem JWT uzyskiwanym poprzez przepływ OAuth2 client_credentials (/auth/token) — nie standardowy grant login/hasło, ponieważ po tej stronie nie ma użytkownika-człowieka, a jedynie zaufany klient wysyłający logi.

Funkcje

• Konfigurowalny silnik reguł — reguły detekcji sygnaturowej i wolumetrycznej (opartej na częstotliwości), zdefiniowane w pliku polityki JSON, walidowane przez Pydantic podczas wczytywania.
• Agent bezpieczeństwa LLM — agent LangChain z wywoływaniem narzędzi (Claude), który bada wywołaną regułę, korzystając z bazy wiedzy MITRE ATT&CK (Qdrant + embeddingi HuggingFace) oraz historii aktywności IP, i zwraca ustrukturyzowany, zwalidowany schemą raport o zagrożeniu.
• Autoryzacja maszyna–maszyna — grant OAuth2 client_credentials z tokenem JWT, zaprojektowany specjalnie do wywołań między usługami, w przeciwieństwie do bardziej popularnego (i w tym przypadku niewłaściwego) grantu resource-owner z hasłem.
• Alerty w czasie rzeczywistym — nowe raporty o zagrożeniach są transmitowane przez WebSocket do panelu Streamlit w momencie ich powstania.
• Asynchroniczny zapis danych — asynchroniczny ORM SQLAlchemy 2.0.
• Strukturalne logowanie — structlog, JSON w produkcji / czytelny format konsolowy w środowisku deweloperskim.
• Zestaw testów — testy jednostkowe silnika reguł, schematów i serwisów; LLM oraz baza wektorowa są mockowane, nie wywoływane naprawdę, dzięki czemu zestaw testów jest szybki i deterministyczny.

Stos technologiczny

Backend: FastAPI, LangChain (Anthropic Claude), Qdrant, embeddingi HuggingFace, SQLAlchemy (async), Pydantic v2, structlog, PyJWT Frontend: Streamlit, klient WebSocket Testy: pytest, pytest-cov, anyio Infrastruktura: Docker Compose (backend + frontend + Qdrant)

Szybki start

git clone https://github.com/dozoq/AILogAssistant.git
cd AILogAssistant
cp .env.example .env   # wypełnij wartości, patrz sekcja Konfiguracja poniżej
docker compose up --build

• API backendu: http://localhost:8000
• Panel frontendu: http://localhost:8080
• Qdrant: http://localhost:6333

Konfiguracja

Zmienna	Używana przez	Opis
ANTHROPIC_API_KEY	backend	Klucz API Claude dla agenta bezpieczeństwa
JWT_SECRET_KEY	backend	Podpisuje/weryfikuje tokeny dostępu M2M
INTERNAL_CLIENT_SECRET	backend	Wspólny sekret, którym autoryzują się zaufani klienci
QDRANT_URL	backend	Adres Qdrant (http://qdrant:6333 w Dockerze)
DATABASE_URL	backend	Opcjonalne — domyślnie lokalny plik SQLite

Testowanie

cd LogAssistant
uv run pytest --cov=src/logassistant --cov-report=term-missing

Zestaw testów obejmuje silnik reguł (włącznie z przypadkami granicznymi, takimi jak arytmetyka progów i wyszukiwanie po wyrażeniach regularnych), walidację schematów Pydantic, przepływ autoryzacji oraz pętlę orkiestracji agenta LLM — wywołania ainvoke agenta są mockowane za pomocą przygotowanych odpowiedzi AIMessage, dzięki czemu testy działają bez rzeczywistych wywołań API czy działającej instancji Qdrant.

Testowanie API

W katalogu bruno/ znajduje się kolekcja Bruno z przykładowymi żądaniami dla każdego endpointu.

Struktura projektu

LogAssistant/          Backend FastAPI
LogAssistantFrontend/  Panel Streamlit
bruno/                 Kolekcja żądań API
docker-compose.yaml    Backend + frontend + Qdrant