Netpulse_SasS/server/internal/httpapi/traps.go

package httpapi

import (
	"net/http"
	"strconv"
	"strings"
	"time"

	"github.com/netpulse/netpulse/server/internal/store"
)

// SNMP-трапи: журнал, словник назв і перелік невідомих відправників.
//
// ПРО ПРАВА
//
// Дивитись — devices:read. Те саме рішення, що для сховища й дзеркала:
// трап — це подія з мережі, і бачити її має той, хто щодня дивиться на
// мережу, а не лише власник кабінету.
//
// Правити словник і прибирати рядки з переліку невідомих —
// settings:write. Словник міняє те, ЯК підписані події для всіх у
// кабінеті, а видалення з переліку невідомих означає «я з цим
// розібрався». І перше, і друге — рішення про кабінет, а не про свій
// екран.

const (
	trapsReadPerm  = "devices:read"
	trapsWritePerm = "settings:write"
)

// trapsMaxRange — стеля глибини вибірки.
//
// Та сама, що в аудиті, і з тих самих міркувань: журнал росте вічно, а
// «покажи все» — це не глибина, а відсутність питання. Строк зберігання
// трапів усе одно 90 діб (0005), тож рік тут — із запасом на кабінети,
// де його подовжили.
const trapsMaxRange = 366 * 24 * time.Hour

func (s *Server) handleListTraps(w http.ResponseWriter, r *http.Request, p *Principal) {
	if !requirePerm(w, p, trapsReadPerm) {
		return
	}

	q := r.URL.Query()
	f := store.TrapFilter{
		DeviceIDs: splitParam(q, "device"),
		OIDs:      splitParam(q, "oid"),
		SourceIP:  strings.TrimSpace(q.Get("source_ip")),
		Query:     strings.TrimSpace(q.Get("q")),
		Cursor:    q.Get("cursor"),
		// «Тільки невідомі» — окремий фільтр, а не порожній device.
		// Порожнє значення в адресному рядку губиться, а це питання
		// ставлять достатньо часто, щоб на нього давали посилання.
		OnlyUnknown: q.Get("unknown") == "1",
	}

	var err error
	if f.From, err = parseTimeParam(q.Get("from")); err != nil {
		writeError(w, http.StatusBadRequest, "invalid", "некоректна дата «від»")
		return
	}
	if f.To, err = parseTimeParam(q.Get("to")); err != nil {
		writeError(w, http.StatusBadRequest, "invalid", "некоректна дата «до»")
		return
	}
	if f.To.IsZero() {
		f.To = time.Now().UTC()
	}
	if f.From.IsZero() {
		f.From = f.To.Add(-24 * time.Hour)
	}
	if !f.From.Before(f.To) {
		writeError(w, http.StatusBadRequest, "invalid", "початок періоду має бути раніше за кінець")
		return
	}
	if f.To.Sub(f.From) > trapsMaxRange {
		writeError(w, http.StatusBadRequest, "invalid",
			"період не більший за рік — звузьте діапазон або скористайтесь фільтрами")
		return
	}
	if n, err := strconv.Atoi(q.Get("limit")); err == nil {
		f.Limit = n
	}

	page, err := s.store.ListTraps(r.Context(), p.TenantID, f)
	if err != nil {
		s.writeStoreError(w, "журнал трапів", err)
		return
	}
	writeJSON(w, http.StatusOK, page)
}

// handleTrapsMeta — усе, що сторінці треба знати на момент відкриття.
//
// Одним викликом, а не трьома: словник, перелік невідомих відправників
// і перелік сліпих зон — це стан сторінки, і зібраний із трьох
// відповідей у різні секунди він нічого не виграє, зате додає два
// стани завантаження на екран.
func (s *Server) handleTrapsMeta(w http.ResponseWriter, r *http.Request, p *Principal) {
	if !requirePerm(w, p, trapsReadPerm) {
		return
	}

	custom, err := s.store.TrapNames(r.Context(), p.TenantID)
	if err != nil {
		s.writeStoreError(w, "словник трапів", err)
		return
	}
	unknown, err := s.store.ListUnknownTrapSources(r.Context(), p.TenantID)
	if err != nil {
		s.writeStoreError(w, "невідомі джерела трапів", err)
		return
	}

	type namedOID struct {
		OID string `json:"oid"`
		store.TrapMeaning
	}
	names := []namedOID{}
	for oid, m := range store.BuiltinTrapNames() {
		names = append(names, namedOID{OID: oid, TrapMeaning: m})
	}
	for oid, m := range custom {
		names = append(names, namedOID{OID: oid, TrapMeaning: m})
	}

	writeJSON(w, http.StatusOK, map[string]any{
		"names":   names,
		"unknown": unknown,
		// Сліпі зони переліком, а не текстом на сторінці: порожній
		// журнал без цього блоку читається як «трапів не було», хоча
		// частіше означає «їх нікому приймати». Саме це й було станом
		// продукту до 0065 — порт слухав ніхто, а екран мовчав.
		"blind_spots": trapBlindSpots,
	})
}

// trapBlindSpots — те, чого приймач трапів НЕ бачить.
//
// Перелік тут, а не в тексті сторінки, з тієї ж причини, що й у
// журналі аудиту: він мусить жити поруч із кодом, який його спростовує.
// Рядок, який перестав бути правдою, прибирає той, хто це полагодив.
var trapBlindSpots = []map[string]string{
	{
		"title": "Трапи приймає лише зонд із увімкненим модулем «traps»",
		"note": "Модуль вмикається переліком -modules на самому зонді, і йому потрібен " +
			"порт 162/udp. Порт нижче 1024, тож у Linux зонду треба CAP_NET_BIND_SERVICE " +
			"або перенаправлення 162 → 1162 правилом фаєрвола. Поки цього немає, " +
			"пристрої шлють трапи в нікуди, і виглядає це як спокійна мережа.",
	},
	{
		"title": "SNMPv3 приймається, але не перевіряється",
		"note": "Трап v3 розбирається й зберігається, проте підпис і шифрування зонд не " +
			"звіряє: для цього потрібні облікові записи USM на кожен пристрій, і " +
			"поки їх немає, «перевірено» було б неправдою. Ім'я користувача " +
			"зберігається як контекст, а не як доказ.",
	},
	{
		"title": "Словник MIB — лише шість стандартних трапів плюс ваші записи",
		"note": "Вбудовані назви є для coldStart, warmStart, linkDown, linkUp, " +
			"authenticationFailure та egpNeighborLoss — їх визначає сам протокол. " +
			"Усе інше показується сирим OID, доки ви не додасте назву самі. " +
			"Ми навмисно не вгадуємо назви за схожістю OID.",
	},
	{
		"title": "Зонд обмежує потік",
		"note": "Не більше 20 трапів за секунду з однієї адреси й 10 000 у черзі; " +
			"надлишок відкидається, а його кількість видно в журналі зонда. " +
			"Без цього порт, що фліпає, поклав би і зонд, і базу.",
	},
}

// handleSaveTrapName додає або міняє власну назву трапа.
func (s *Server) handleSaveTrapName(w http.ResponseWriter, r *http.Request, p *Principal) {
	if !requirePerm(w, p, trapsWritePerm) {
		return
	}
	var in struct {
		OID         string `json:"oid"`
		Name        string `json:"name"`
		Description string `json:"description"`
	}
	if !decodeBody(w, r, &in) {
		return
	}
	if err := s.store.SaveTrapName(r.Context(), p.TenantID, in.OID, in.Name, in.Description); err != nil {
		s.writeStoreError(w, "запис словника трапів", err)
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

func (s *Server) handleDeleteTrapName(w http.ResponseWriter, r *http.Request, p *Principal) {
	if !requirePerm(w, p, trapsWritePerm) {
		return
	}
	if err := s.store.DeleteTrapName(r.Context(), p.TenantID, r.PathValue("oid")); err != nil {
		s.writeStoreError(w, "видалення зі словника трапів", err)
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}

// handleForgetUnknownTrapSource прибирає адресу з переліку невідомих.
//
// Це не видалення даних: самі трапи лишаються в журналі, і якщо з цієї
// адреси прийде наступний, вона в переліку з'явиться знову. Прибирається
// саме ПИТАННЯ — «а що це таке», — на яке людина вже відповіла.
func (s *Server) handleForgetUnknownTrapSource(w http.ResponseWriter, r *http.Request, p *Principal) {
	if !requirePerm(w, p, trapsWritePerm) {
		return
	}
	ip := strings.TrimSpace(r.PathValue("ip"))
	if ip == "" {
		writeError(w, http.StatusBadRequest, "invalid", "потрібна адреса")
		return
	}
	if err := s.store.ForgetUnknownTrapSource(r.Context(), p.TenantID, ip); err != nil {
		s.writeStoreError(w, "видалення невідомого джерела", err)
		return
	}
	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
}