Helper scripts

This commit is contained in:
2026-11-15 17:42:41 +01:00
parent b2f1baaac5
commit 39ba6bd7da
22 changed files with 2233 additions and 0 deletions

87
scripts/install-sensor.sh Normal file
View File

@@ -0,0 +1,87 @@
#!/bin/bash
set -euo pipefail
[ "$(id -u)" -eq 0 ] || { echo 'Run as root on the sensor' >&2; exit 1; }
STAGE=$(cd "$(dirname "$0")/.." && pwd)
python3 -c 'import yaml, requests'
[ -s /etc/leaf-controller/env ] || { echo 'Create root-only /etc/leaf-controller/env with LEAF_VYOS_KEY first' >&2; exit 1; }
[ "$(findmnt -n -o FSTYPE --target /var/log/suricata-leaf)" = tmpfs ] || { echo 'Provision the sensor log tmpfs first' >&2; exit 1; }
if systemctl is-active --quiet suricata.service; then
echo 'The stock Suricata service is active; stop it before installing a second sensor.' >&2
exit 1
fi
systemctl stop leaf-eve-rotate.timer leaf-eve-rotate.service 2>/dev/null || true
systemctl stop suricata-leaf.service leaf-controller.service 2>/dev/null || true
BACKUP=/var/backups/leaf-proto/$(date +%Y%m%d-%H%M%S)
install -d -m 700 "$BACKUP"
items=()
for item in etc/suricata-leaf etc/leaf-controller opt/leaf-controller home/yuru/leaf-proto etc/systemd/system/leaf-controller.service etc/systemd/system/suricata-leaf.service etc/systemd/system/leaf-eve-rotate.service etc/systemd/system/leaf-eve-rotate.timer etc/tmpfiles.d/leaf-suricata.conf; do
if [ -e "/$item" ]; then items+=("$item"); fi
done
tar -czf "$BACKUP/sensor-files.tar.gz" -C / "${items[@]}"
python3 - "$BACKUP" <<'PY'
import sqlite3,sys,pathlib
p=pathlib.Path('/var/lib/leaf-controller/state.sqlite')
if p.exists():
with sqlite3.connect(p) as source, sqlite3.connect(sys.argv[1]+'/state.sqlite') as target: source.backup(target)
PY
rollback() {
rc=$?
trap - ERR
echo "Installation failed; restoring previous files from $BACKUP" >&2
systemctl stop suricata-leaf leaf-controller leaf-eve-rotate.timer 2>/dev/null || true
for unit in leaf-controller.service suricata-leaf.service leaf-eve-rotate.service leaf-eve-rotate.timer; do
if ! tar -tzf "$BACKUP/sensor-files.tar.gz" | grep -qx "etc/systemd/system/$unit"; then
systemctl disable "$unit" 2>/dev/null || true
rm -f "/etc/systemd/system/$unit"
fi
done
tar -xzf "$BACKUP/sensor-files.tar.gz" -C /
if [ -f "$BACKUP/state.sqlite" ]; then
install -o leafctrl -g leafctrl -m 640 "$BACKUP/state.sqlite" /var/lib/leaf-controller/state.sqlite
rm -f /var/lib/leaf-controller/state.sqlite-wal /var/lib/leaf-controller/state.sqlite-shm
fi
systemctl daemon-reload
systemctl start leaf-controller suricata-leaf || true
exit "$rc"
}
trap rollback ERR
getent group leafctrl >/dev/null || groupadd --system leafctrl
id leafctrl >/dev/null 2>&1 || useradd --system --gid leafctrl --home-dir /nonexistent --shell /usr/sbin/nologin leafctrl
install -d -o leafctrl -g leafctrl -m 750 /var/lib/leaf-controller /var/log/leaf-controller
chown -R leafctrl:leafctrl /var/lib/leaf-controller /var/log/leaf-controller
find /var/lib/leaf-controller /var/log/leaf-controller -type f -exec chmod 640 {} +
install -d -m 755 /opt/leaf-controller/controller
cp -a "$STAGE/controller/leaf_controller" /opt/leaf-controller/controller/
chown -R root:root /opt/leaf-controller
chmod -R a+rX /opt/leaf-controller
install -d -o root -g leafctrl -m 750 /etc/leaf-controller
# Preserve site policy and TLS settings on upgrades; seed only a new install.
if [ ! -s /etc/leaf-controller/config.yaml ]; then
install -m 644 "$STAGE/config/prototype-vyos.yaml" /etc/leaf-controller/config.yaml
fi
install -d -m 755 /opt/leaf-controller/tools
install -m 755 "$STAGE/tests/live_helper.py" /opt/leaf-controller/tools/leaf-live-helper.py
install -m 755 "$STAGE/scripts/rotate-eve.py" "$STAGE/scripts/rotate-vyos-key.py" "$STAGE/scripts/vyos_show.py" "$STAGE/scripts/vyos_smoke.py" "$STAGE/scripts/vyos_ctl.py" "$STAGE/scripts/probe-vyos-read.py" /opt/leaf-controller/tools/
install -m 644 "$STAGE/suricata/leaf-eve-rotate.service" "$STAGE/suricata/leaf-eve-rotate.timer" /etc/systemd/system/
install -m 644 "$STAGE/controller/leaf-controller.service" /etc/systemd/system/leaf-controller.service
install -d -m 755 /etc/suricata-leaf/rules
install -m 644 "$STAGE/suricata/suricata-leaf.yaml" /etc/suricata-leaf/suricata-leaf.yaml
install -m 644 "$STAGE/suricata/rules/leaf-local.rules" /etc/suricata-leaf/rules/leaf-local.rules
install -m 644 "$STAGE/suricata/suricata-leaf.service" /etc/systemd/system/suricata-leaf.service
# tmpfs mount stays in place; recreate permissions after reboot via tmpfiles.
printf '%s\n' 'd /var/log/suricata-leaf 0750 root leafctrl -' \
'd /run/suricata 0770 root leafctrl -' > /etc/tmpfiles.d/leaf-suricata.conf
systemd-tmpfiles --create /etc/tmpfiles.d/leaf-suricata.conf
chown root:leafctrl /var/log/suricata-leaf
chmod 750 /var/log/suricata-leaf
find /var/log/suricata-leaf -maxdepth 1 -type f -exec chgrp leafctrl {} +
find /var/log/suricata-leaf -maxdepth 1 -type f -exec chmod 640 {} +
systemctl daemon-reload
systemctl enable suricata-leaf.service leaf-controller.service leaf-eve-rotate.timer
systemctl start suricata-leaf.service leaf-controller.service leaf-eve-rotate.timer
sleep 2
systemctl is-active --quiet suricata-leaf.service
systemctl is-active --quiet leaf-controller.service
trap - ERR
printf 'Backup: %s\n' "$BACKUP"
systemctl --no-pager --full status suricata-leaf.service leaf-controller.service

View File

@@ -0,0 +1,5 @@
#!/usr/bin/env python3
"""Compatibility entry point for the scoped, redacted read-only inspector."""
from pathlib import Path
import runpy
if __name__=='__main__':runpy.run_path(str(Path(__file__).with_name('vyos_show.py')),run_name='__main__')

76
scripts/provision-ids-tmpfs.sh Executable file
View File

@@ -0,0 +1,76 @@
#!/usr/bin/env bash
# LEAF-PROTO sensor provisioning: RAM disk (tmpfs) for the suricata eve dir.
#
# eve.json under /var/log/suricata-leaf is rewritten constantly; on a
# journal/flash disk that burns write cycles and adds latency. This puts the
# directory on a size-capped tmpfs (RAM+swap backed), persisted via fstab.
# Controller state stays on persistent storage in /var/lib/leaf-controller.
# See docs/INSTALLATION.md for memory sizing and log retention.
#
# Usage: TMPFS_SIZE=6G sudo scripts/provision-ids-tmpfs.sh [mount_point]
# (default mount point /var/log/suricata-leaf, default size 8G)
set -euo pipefail
MOUNT_POINT="${1:-${MOUNT_POINT:-/var/log/suricata-leaf}}"
SIZE="${TMPFS_SIZE:-${SIZE:-8G}}"
usage() {
echo "usage: TMPFS_SIZE=8G sudo $0 [mount_point (default: /var/log/suricata-leaf)]"
}
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
echo "error: run as root (needs mount/fstab writes)" >&2
usage
exit 1
fi
if findmnt -rn -T "$MOUNT_POINT" | grep -q 'tmpfs'; then
echo "skip: $MOUNT_POINT is already on tmpfs:"
findmnt -rn -T "$MOUNT_POINT"
exit 0
fi
if ! [[ "$SIZE" =~ ^[0-9]+([MGK])?$ ]]; then
echo "error: TMPFS_SIZE must like 6G/8G/512M (got: $SIZE)" >&2
exit 1
fi
echo "warning: tmpfs is RAM-backed — $SIZE cap counts against RAM+swap."
free -h
echo "note: eve.json on this mount is lost on reboot by design;"
echo "note: controller block state lives on disk (/var/lib/leaf-controller), unaffected."
mkdir -p "$MOUNT_POINT"
# A pre-existing non-empty dir on another filesystem would be hidden under
# the tmpfs after mounting — warn, since old eve files become unreachable.
if [[ -n "$(findmnt -rn -T "$MOUNT_POINT" 2>/dev/null)" ]] &&
! findmnt -rn -T "$MOUNT_POINT" | grep -q 'tmpfs' &&
[[ -n "$(ls -A "$MOUNT_POINT" 2>/dev/null)" ]]; then
echo "warning: $MOUNT_POINT already has content on another filesystem;"
echo "warning: it will be hidden underneath the tmpfs — move it first if"
echo "warning: you need the old eve.json:"
ls -A "$MOUNT_POINT" | head -5
fi
FSTAB_LINE="tmpfs ${MOUNT_POINT} tmpfs defaults,size=${SIZE},nosuid,noexec,nodev 0 0"
if grep -qF " ${MOUNT_POINT} " /etc/fstab; then
echo "fstab already has an entry for $MOUNT_POINT — not appending:"
grep -F " ${MOUNT_POINT} " /etc/fstab
else
printf '\n# LEAF-PROTO: suricata eve on RAM disk (provision-ids-tmpfs.sh)\n%s\n' "$FSTAB_LINE" >> /etc/fstab
echo "fstab entry appended."
fi
systemctl daemon-reload
mount -a
if findmnt -rn -T "$MOUNT_POINT" | grep -q 'tmpfs'; then
echo "OK: mounted."
findmnt -rn -T "$MOUNT_POINT"
else
echo "error: mount did not come up — check /etc/fstab" >&2
exit 1
fi
df -h "$MOUNT_POINT"

17
scripts/reboot-check.sh Normal file
View File

@@ -0,0 +1,17 @@
#!/usr/bin/env bash
# Read-only recovery inspection. Never reboots either the sensor or VIPERA.
set -euo pipefail
VM="${VM:-yuru@192.168.100.84}"
KEY="${LEAF_SSH_KEY:-$HOME/.ssh/id_ed25519_alice}"
ssh -F /dev/null -o BatchMode=yes -o ConnectTimeout=8 -i "$KEY" "$VM" '
set -eu
[ "$(hostname)" = LEAF-PROTO ]
systemctl is-active --quiet leaf-controller suricata-leaf leaf-eve-rotate.timer
systemctl is-enabled --quiet leaf-controller suricata-leaf leaf-eve-rotate.timer
[ "$(findmnt -n -o FSTYPE --target /var/log/suricata-leaf)" = tmpfs ]
sudo -n test -S /run/suricata/alerts.sock
printf "boot_id="; cat /proc/sys/kernel/random/boot_id
uptime -s
sudo -n python3 /opt/leaf-controller/tools/leaf-live-helper.py status
printf "RECOVERY INSPECTION PASS (no reboot performed)\n"
'

60
scripts/rotate-eve.py Normal file
View File

@@ -0,0 +1,60 @@
#!/usr/bin/env python3
"""Rename EVE and ask Suricata to reopen it; invoked each minute by a timer.
Normal bound: seven 64-MiB/hour segments plus bytes written between timer
runs. The tmpfs itself is the hard capacity limit. Not copytruncate.
"""
import argparse
import fcntl
import os
from pathlib import Path
import subprocess
import time
def rotate(path, max_bytes=64*1024*1024, max_age=3600, keep=6, reopen=None, now=None):
now = time.time() if now is None else now
try:
st = path.stat()
except FileNotFoundError:
return False
# Both mtime and ctime change on writes. Keep an independent age clock.
clock = path.with_name('.' + path.name + '.rotation-clock')
try:
last = float(clock.read_text())
except (FileNotFoundError, ValueError):
last = now
clock.write_text(str(now))
if st.st_size < max_bytes and now-last < max_age:
return False
dst = path.with_name(path.name + '.leaf-' + str(time.time_ns()).zfill(20))
path.rename(dst)
try:
reopen()
except BaseException:
if not path.exists():
dst.rename(path)
raise
clock.write_text(str(now))
for f in sorted(path.parent.glob(path.name + '.leaf-*'))[:-keep] if keep else path.parent.glob(path.name + '.leaf-*'):
f.unlink()
return True
def main():
ap=argparse.ArgumentParser(description=__doc__)
ap.add_argument('--path', type=Path, default=Path('/var/log/suricata-leaf/eve.json'))
a=ap.parse_args()
# Type=simple is active before Suricata installs signal handlers. Never
# signal a just-started engine, including manual timer/service triggers.
started = subprocess.run(['systemctl','show','--property=ActiveEnterTimestampMonotonic',
'--value','suricata-leaf.service'],
check=True,capture_output=True,text=True).stdout.strip()
if not started or int(started) == 0 or time.monotonic() - int(started)/1e6 < 60:
return
with open('/run/leaf-eve-rotation.lock', 'a') as lock:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
rotate(a.path, reopen=lambda: subprocess.run(
['systemctl','kill','--kill-whom=main','--signal=HUP','suricata-leaf.service'], check=True))
if __name__ == '__main__': main()

120
scripts/rotate-vyos-key.py Normal file
View File

@@ -0,0 +1,120 @@
#!/usr/bin/env python3
"""Rotate exactly one explicitly selected LEAF key. Never prints API bodies/keys.
Run on sensor: sudo python3 .../rotate-vyos-key.py --old-id <LEAF-owned-id>
Other applications' credentials are preserved. Retrying after retirement/save
failure requires inspecting router key IDs first; no blind mass-delete mode.
"""
import argparse
import os
from pathlib import Path
import re
import secrets
import string
import subprocess
import sys
import time
sys.path.insert(0, '/opt/leaf-controller/controller')
from leaf_controller.config import load_config, read_key_env
from leaf_controller.vyos_client import VyosClient, VyosApiError
ENV_PATH = '/etc/leaf-controller/env'
CFG_PATH = '/etc/leaf-controller/config.yaml'
SERVICE = 'leaf-controller.service'
KEYS_PATH = ['service', 'https', 'api', 'keys', 'id']
def atomic_env(text):
tmp=ENV_PATH+'.new'
fd=os.open(tmp, os.O_WRONLY|os.O_CREAT|os.O_TRUNC, 0o600)
os.fchmod(fd, 0o600)
with os.fdopen(fd, 'w') as f:
f.write(text); f.flush(); os.fsync(f.fileno())
os.replace(tmp, ENV_PATH)
fd=os.open(str(Path(ENV_PATH).parent), os.O_DIRECTORY)
try: os.fsync(fd)
finally: os.close(fd)
def restart_service():
subprocess.run(['systemctl','restart',SERVICE], check=True, capture_output=True)
subprocess.run(['systemctl','is-active','--quiet',SERVICE], check=True, capture_output=True)
def wait_auth(client, group, accepted=True, attempts=24):
for i in range(attempts):
try:
client.group_members(group)
if accepted: return
except VyosApiError as exc:
if not accepted and exc.status in (401,403): return
except Exception:
pass
if i+1<attempts: time.sleep(5)
raise RuntimeError('credential verification timed out')
def rotate(old, new, old_id, new_id, old_key, new_key, env_text, group):
body=old.retrieve('showConfig', KEYS_PATH[:-1])
ids=(body.get('data') or {}).get('id', {})
if old_id not in ids or ids[old_id].get('key') != old_key:
raise RuntimeError('selected key ID does not match the current controller credential')
if new_id in ids:
raise RuntimeError('candidate ID already exists')
swapped=False
installed=False
try:
# A timeout can still commit; rollback attempts candidate deletion either way.
installed=True
old.configure({'op':'set','path':KEYS_PATH+[new_id,'key',new_key]})
wait_auth(new, group)
# Persist both keys before the local switch; old credential remains a recovery path.
new.save_config()
out,n=re.subn(r'(?m)^LEAF_VYOS_KEY=.*$', "LEAF_VYOS_KEY='"+new_key+"'", env_text)
if n!=1: raise RuntimeError('expected exactly one credential assignment')
swapped=True
atomic_env(out)
restart_service()
wait_auth(new, group, attempts=2)
except BaseException:
# Restore the credential before restarting. If recovery fails, retain candidate.
if swapped:
atomic_env(env_text)
restart_service()
if installed:
old.configure({'op':'delete','path':KEYS_PATH+[new_id]})
old.save_config()
raise
# Retirement is a separate phase: rollback is unsafe after this commit.
new.configure({'op':'delete','path':KEYS_PATH+[old_id]})
new.save_config() # Failure is fatal; never claim persistence succeeded.
wait_auth(old, group, accepted=False)
def main():
ap=argparse.ArgumentParser(description=__doc__)
ap.add_argument('--old-id', required=True)
a=ap.parse_args()
if os.geteuid()!=0: ap.error('run as root on the sensor')
cfg=load_config(CFG_PATH)
if cfg.get('vyos.key_env','LEAF_VYOS_KEY')!='LEAF_VYOS_KEY':
ap.error('this tool requires the standard LEAF_VYOS_KEY assignment')
text=Path(ENV_PATH).read_text()
old_key=read_key_env(ENV_PATH)
new_key=''.join(secrets.choice(string.ascii_letters+string.digits) for _ in range(32))
new_id='leaf-'+str(time.time_ns())
def client(key):
return VyosClient(cfg.vyos_url(), key, cert_pin=cfg.get('vyos.tls_cert_pin') or None,
ca_bundle=cfg.get('vyos.ca_bundle'), tls_verify=cfg.get('vyos.tls_verify',True),
timeout=float(cfg.get('vyos.timeout',75)), retries=1)
try:
rotate(client(old_key),client(new_key),a.old_id,new_id,old_key,new_key,text,cfg.get('block_group'))
except BaseException:
# Deliberately omit exception details: router responses can contain secrets.
print('ROTATION FAILED. Inspect service and router key IDs before retrying. Candidate ID: '+new_id,
file=sys.stderr)
return 1
print('ROTATION COMPLETE: selected old ID retired, config persisted, new ID='+new_id)
return 0
if __name__=='__main__': raise SystemExit(main())

19
scripts/vyos_ctl.py Normal file
View File

@@ -0,0 +1,19 @@
#!/usr/bin/env python3
"""Read-only lab client. Membership writes belong to the durable controller.
Legacy add/del/drop-chain commands have been retired; they bypassed ownership.
"""
import argparse
import json
from pathlib import Path
import sys
sys.path[:0]=[str(Path(__file__).resolve().parents[1]/'controller'),'/opt/leaf-controller/controller']
from leaf_controller.ops import configured_client,redact
def main():
p=argparse.ArgumentParser(description=__doc__)
p.add_argument('command',choices=['members','forward-rule'],default='members',nargs='?')
a=p.parse_args();cfg,c=configured_client()
if a.command=='members':print(json.dumps(c.group_members(cfg.get('block_group'))))
else:print(json.dumps(redact(c.retrieve('showConfig',['firewall','ipv4','forward']))))
if __name__=='__main__':main()

13
scripts/vyos_show.py Normal file
View File

@@ -0,0 +1,13 @@
#!/usr/bin/env python3
"""Read-only firewall, mirror and protected-path inspection. No credential dump."""
import json
from pathlib import Path
import sys
sys.path[:0]=[str(Path(__file__).resolve().parents[1]/'controller'),'/opt/leaf-controller/controller']
from leaf_controller.ops import configured_client, redact
def main():
_,c=configured_client()
for path in (['firewall'],['interfaces'],['protocols','ospf'],['protocols','static']):
print(json.dumps({'path':path,'data':redact(c.retrieve('showConfig',path).get('data'))}))
if __name__=='__main__':main()

15
scripts/vyos_smoke.py Normal file
View File

@@ -0,0 +1,15 @@
#!/usr/bin/env python3
"""Read-only pinned API smoke check. Does not add members or save router config."""
import json
from pathlib import Path
import sys
sys.path[:0]=[str(Path(__file__).resolve().parents[1]/'controller'),'/opt/leaf-controller/controller']
from leaf_controller.ops import configured_client
def main():
cfg,c=configured_client()
info=c.info();members=c.group_members(cfg.get('block_group'))
c.verify_enforcement(cfg.get('block_group'),cfg.get('policy.block_src',False))
print(json.dumps({'version':info.get('version'),'members':members,'enforcement_hooks':True}))
print('READ-ONLY SMOKE PASS')
if __name__=='__main__':main()