Documentation
¶
Overview ¶
Package alerts is the producer-facing seam for security alerting. It owns the alert Payload DTO and a publish-once dispatch indirection, so alert producers (the scan engines, policy, …) can fire alerts without depending on the webhook-delivery implementation, which stays in package main and is installed once at startup via SetSink. ADR-0002/0003 (sibling to the obs sink seam).
Index ¶
- func Fire(event string, p Payload)
- func SetSink(fn Sink)
- func StartRetryLoop(ctx context.Context, current func() *Store)
- func ValidateURL(raw string) error
- type Delivery
- type Payload
- type Sink
- type Store
- func (as *Store) Add(h Webhook) Webhook
- func (as *Store) Delete(id string) bool
- func (as *Store) Deliver(h Webhook, payload Payload) bool
- func (as *Store) DeliveryHistory() []Delivery
- func (as *Store) Dispatch(event string, payload Payload)
- func (as *Store) GetByID(id string) (Webhook, bool)
- func (as *Store) Init(path string)
- func (as *Store) List() []Webhook
- func (as *Store) RecordDelivery(d Delivery)
- func (as *Store) ResetDedupForTest()
- func (as *Store) Update(id string, upd Webhook) bool
- type Webhook
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Fire ¶
Fire dispatches an alert through the installed sink. It is a no-op when no sink is installed (e.g. unit tests that never wire alerting), so producers never need a nil check or a dependency on the delivery layer.
func SetSink ¶
func SetSink(fn Sink)
SetSink installs the dispatch implementation. Intended to be called once at startup (publish-once); a later call atomically replaces the sink.
func StartRetryLoop ¶ added in v1.0.16
StartRetryLoop runs a background loop that retries failed deliveries. current resolves the store on every pass, so package main can pass a closure over its process-wide singleton (tolerating test reassignment — the pre-extraction loop read the global on each tick the same way).
func ValidateURL ¶ added in v1.0.16
ValidateURL checks that a webhook URL is well-formed (http/https with a non-empty host). Unlike main's validateExternalURL, it does not perform DNS resolution at config time — the SSRF check is deferred to delivery time via the ssrf-guarded dialer so that operator-configured internal endpoints remain usable.
Types ¶
type Delivery ¶ added in v1.0.16
type Delivery struct {
Timestamp string `json:"timestamp"`
WebhookID string `json:"webhookId"`
WebhookName string `json:"webhookName"`
Event string `json:"event"`
StatusCode int `json:"statusCode,omitempty"` // 0 if delivery failed before HTTP
Success bool `json:"success"`
Error string `json:"error,omitempty"`
Attempt int `json:"attempt"` // 1-based
}
Delivery records a single webhook delivery attempt.
type Payload ¶
type Payload struct {
Event string `json:"event"`
Timestamp string `json:"timestamp"`
Actor string `json:"actor"` // client IP or username
Host string `json:"host"`
Detail string `json:"detail"` // virus name / rule name / pattern
Source string `json:"source"` // "clamav","yara","threatfeed","policy","auth"
}
Payload is the JSON body delivered to webhooks for a security event.
type Sink ¶
Sink dispatches an alert. The real implementation (webhook fan-out, retry, HMAC signing, SSRF-guarded delivery) lives in package main.
type Store ¶ added in v1.0.16
type Store struct {
// contains filtered or unexported fields
}
Store holds the configured webhooks and the delivery-attempt history. The zero value is usable (main's process-wide singleton and several tests construct it as &Store{} / &AlertStore{}); Init sets the persistence path.
func (*Store) Deliver ¶ added in v1.0.16
Deliver performs one delivery attempt (attempt=1) and records the result. Exposed for main's webhook-test admin endpoint; Dispatch and the retry loop use it internally.
func (*Store) DeliveryHistory ¶ added in v1.0.16
DeliveryHistory returns the most recent delivery records (newest first).
func (*Store) Dispatch ¶ added in v1.0.16
Dispatch fans payload out to all enabled webhooks matching event. Always non-blocking: delivery happens in background goroutines. Q17: Duplicate events with the same event+detail are suppressed within dedupTTL. package main's fireAlert wrapper (installed as the alerts.Fire sink) calls this on the process-wide store.
func (*Store) GetByID ¶ added in v1.0.16
GetByID returns the webhook with the given ID (secret included — callers use it for delivery/signing, never for display).
func (*Store) Init ¶ added in v1.0.16
Init sets the persistence path and loads any persisted webhooks.
func (*Store) RecordDelivery ¶ added in v1.0.16
RecordDelivery appends a delivery record to the in-memory history ring.
func (*Store) ResetDedupForTest ¶ added in v1.0.16
func (as *Store) ResetDedupForTest()
ResetDedupForTest clears the Q17 dedup window so a test can fire the same event+detail twice and observe both deliveries (needed under -count>1 / -shuffle=on where a previous run already fired the pair).
type Webhook ¶ added in v1.0.16
type Webhook struct {
ID string `json:"id"`
Name string `json:"name"`
URL string `json:"url"`
Events []string `json:"events"` // e.g. ["threat_detected","policy_block"]
Enabled bool `json:"enabled"`
Secret string `json:"secret,omitempty"` // HMAC-SHA256 signing secret (never returned in list)
}
Webhook describes a single webhook endpoint.
Source Files