#!/bin/bash
# ==============================================================================================
# ===================================== Auth Sweep =============================================
# ==============================================================================================
#
# PURPOSE
# ─────────────────────────────────────────────────────────────────────────────
# Asks the two questions the Auth tab can answer about one host, about every host, and files
# what it finds as findings.
#
#   Is this host serving?    below the uptime threshold, and failing for longer than a restart
#   Is this host protected?  behind an auth_request block that no rule then applies to
#
# Both answers existed already and both needed somebody to open the tab and press a button on
# the right row. One host here has returned nothing but 5xx for months.
#
# ==============================================================================================
# OPERATIONAL MODEL
# ==============================================================================================
#
# A wrapper. The work is in auth_sweep.php.
#
# Reports only — nothing is started, restarted or rewritten. The remedies are "start a
# container", "edit a rule", "change a default policy", and each of those is a decision.
#
# The live half is gated on time rather than on sample count: a host must have been failing for
# longer than AUTH_SWEEP_DOWN_MIN before anything is filed, so a reboot does not produce a
# finding for every hostname on the machine.
#
# ==============================================================================================
# DESIGN PRINCIPLES
# ==============================================================================================
#
# It answers the questions nobody was going to ask.
#   Both checks were already possible from the Auth tab, and both required somebody to open it
#   and press a button on the right row. That is why one host here returned nothing but 5xx for
#   months. A check that depends on being run is a check that is not running.
#
# Files findings; never applies remedies.
#   The fixes are "start a container", "edit a rule", "change a default policy". Each of those
#   is a judgement about intent, and a sweep that guessed at intent would be repairing a
#   deliberate configuration as often as a broken one.
#
# Down is measured in time, not in samples.
#   A host must have been failing for longer than AUTH_SWEEP_DOWN_MIN before anything is filed.
#   Counting failed samples instead would file a finding for every hostname on the machine every
#   time it reboots, and a report that cries wolf after every restart stops being read.
#
# ==============================================================================================
# OPERATIONAL SAFEGUARDS
# ==============================================================================================
#
# Read-only against the auth stack. Nothing here starts a container, edits a proxy host, changes
# a rule or alters a default policy — the two questions are answered by observation alone.
#
# --dry-run reports what it would file and writes no finding. --report only reads what is
# already filed, and is silent when clean, so it cannot manufacture noise for the Sunday report.
#
# Findings are filed, not notified. A sweep that raised an alert per host would be its own
# incident every time the array restarted.
#
# ==============================================================================================
# RUNTIME MODES
# ==============================================================================================
#
# auth_sweep.sh             one pass, files findings
# auth_sweep.sh --dry-run   report what it would file, write nothing
# auth_sweep.sh --report    one-screen summary for the Sunday report; silent when clean
#
# ==============================================================================================
# CONFIGURATION
# ==============================================================================================
#
# AUTH_SWEEP_ENABLED       master switch
# AUTH_SWEEP_UPTIME_MIN    24h percentage below which a host is a candidate
# AUTH_SWEEP_DOWN_MIN      minutes it must have been failing before a finding is filed
# AUTH_SWEEP_ACCESS_CHECK  whether to run the protection half at all
#
# ==============================================================================================

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
php "$SCRIPT_DIR/auth_sweep.php" "$@"