shield

Documentation

Overview

Package shield reconciles elchi-shield's watched config directory on the edge host to a control-plane-supplied desired state. elchi-shield self-watches that directory (fsnotify + debounce + atomic hot-reload + last-good), so the agent only lands files atomically — it never signals shield to reload.

Sync is two-phase to keep shield's view consistent. PREPARE validates every file and stages it into a sibling temp file (".tmp", which shield's loader ignores by extension) — slow work like downloads happens here, touching no live file, so any error aborts with the directory unchanged. COMMIT then renames the staged temps into place in a fast burst that shield's debounce coalesces into a single reload of the final state.

Index

• func ConfirmReload(ctx context.Context, before ShieldState, log *logger.Logger) (appliedVersion string, reloadOk bool, reason string)
• func CorerulesetVersion(ctx context.Context) string
• func ListConfig(_ *logger.Logger) ([]*client.ShieldFile, error)
• func SyncConfig(ctx context.Context, cfg *client.ShieldConfig, log *logger.Logger) (bool, error)
• type ShieldState
  • func SnapshotState(ctx context.Context) ShieldState

Functions

func ConfirmReload

func ConfirmReload(ctx context.Context, before ShieldState, log *logger.Logger) (appliedVersion string, reloadOk bool, reason string)

ConfirmReload polls shield after a push and reports the truthful active version + whether the new config actually loaded. It returns ok=true when shield's version advances (new config live) or when nothing changed because the pushed content was identical to what's already loaded; ok=false when shield's reload-failure counter advances (rejected → kept last-good) or shield's state cannot be confirmed.

func CorerulesetVersion

func CorerulesetVersion(ctx context.Context) string

CorerulesetVersion returns the OWASP CRS version the local shield binary compiled in (from its /configz), or "" if shield is unreachable or too old to report it. Best-effort — used to tag the node on register, never a hard dependency.

func ListConfig

func ListConfig(_ *logger.Logger) ([]*client.ShieldFile, error)

ListConfig returns the files currently under shield's config dir (path relative to the root, sha256, octal mode); content is omitted. A missing dir yields an empty list (not an error).

func SyncConfig

func SyncConfig(ctx context.Context, cfg *client.ShieldConfig, log *logger.Logger) (bool, error)

SyncConfig reconciles shield's watched config directory (models.ShieldConfigPath) to match cfg. See the package doc for the two-phase model. On full_sync it also removes any managed file not in the set (deletions propagate). On a prepare-phase error the directory is left unchanged; a commit-phase error (rare — only a catastrophic rename failure) may leave earlier files applied, with the rest rolled back, and is reported. The returned changed flag reports whether anything on disk actually changed (a file committed or pruned) — false means the bundle was already fully applied, so shield has nothing to reload and the caller can skip the reload confirmation wait entirely (idempotent re-pushes, e.g. on client reconnect, would otherwise burn the full confirmation timeout per push).

Types

type ShieldState

type ShieldState struct {
	Version            string
	Empty              bool
	Failures           float64 // consecutive-reload-failure gauge (resets on success)
	CumulativeFailures uint64  // monotonic total rejected reloads (/configz)
	Reachable          bool
}

ShieldState is a snapshot of shield's active-config view captured before a push, so ConfirmReload can distinguish "loaded the new config" (version changed) from "rejected, kept last-good" (failure counter advanced).

func SnapshotState

func SnapshotState(ctx context.Context) ShieldState

SnapshotState reads shield's current active version + reload-failure counter. Best-effort: an unreachable shield yields a zero-value (Reachable=false) state, which ConfirmReload still handles.