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()

27
tests/checkpoint_e2e.py Normal file
View File

@@ -0,0 +1,27 @@
#!/usr/bin/env python3
"""Offline file-mode checkpoint proof; never stops the live sensor.
Socket mode has no alert backlog while disconnected. File mode checkpoint
behavior is verified here; live socket reconnect is a separate drill.
"""
import json
import tempfile
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'controller'))
from leaf_controller.eve import EveTailer
def main():
with tempfile.TemporaryDirectory() as tmp:
path=Path(tmp)/'eve.json'
path.write_text('')
t=EveTailer(str(path)); t._open(); ck=(*t._ino,t._pos); t.close()
path.write_text('{"event_type":"alert","n":1}\n{"event_type":"alert","n":2}\n')
t=EveTailer(str(path),checkpoint=ck); events=t.events()
assert next(events)['n']==1
ck=(*t._ino,t._pos); events.close()
t=EveTailer(str(path),checkpoint=ck); events=t.events()
assert next(events)['n']==2
events.close()
print('CHECKPOINT PASS: restart resumes at the next unread record')
if __name__=='__main__': main()

189
tests/drill_synsensor.py Normal file
View File

@@ -0,0 +1,189 @@
#!/usr/bin/env python3
"""Sensor-side synthetic injector for the live socket drills.
Uses AF_PACKET raw sockets and requires root. Frames are addressed to
the selected gateway MAC. Traffic is visible to the sensor only when its
path crosses the configured mirror; select the interface and route accordingly.
Bounded by design: source and destination must be TEST-NET
(192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24) unless --allow-real-src
is passed (then src stays the sensor's real address). count is capped.
--pcap writes a fixture without sending traffic.
Modes:
icmp echo-request -> sid 1000001 (leaf_action block, any src)
syn TCP SYN ->port -> sid 1000030 when src is 203.0.113.0/24
--no-arp: do not ping the gateway first; use the existing ARP entry only.
--src SRC: forge src (TEST-NET enforced); ARP is still only ever
for the gateway MAC, the forged src never touches ARP.
"""
import argparse
import ipaddress
import re
import socket
import struct
import subprocess
import time
from pathlib import Path
TESTNET = ('192.0.2.0/24', '198.51.100.0/24', '203.0.113.0/24')
_NETS = tuple(ipaddress.ip_network(n) for n in TESTNET)
def in_testnet(addr):
ip = ipaddress.ip_address(addr)
return any(ip in net for net in _NETS)
def checksum(data):
if len(data) % 2:
data += b'\x00'
total = sum(struct.unpack('!%dH' % (len(data) // 2), data))
while total >> 16:
total = (total & 0xffff) + (total >> 16)
return (~total) & 0xffff
def syn_packet(src, dst, dport, index, smac, dmac, flags=2):
a, b = socket.inet_aton(src), socket.inet_aton(dst)
tcp = struct.pack('!HHIIBBHHH', 40000 + index % 20000, dport,
7000 + index, 0, 0x50, flags, 1024, 0, 0)
pseudo = a + b + struct.pack('!BBH', 0, 6, len(tcp))
tcp = tcp[:16] + struct.pack('!H', checksum(pseudo + tcp)) + tcp[18:]
ip = struct.pack('!BBHHHBBH4s4s', 0x45, 0, 40, index % 65536, 0, 64, 6,
0, a, b)
ip = ip[:10] + struct.pack('!H', checksum(ip)) + ip[12:]
return dmac + smac + b'\x08\x00' + ip + tcp
def icmp_packet(src, dst, index, smac, dmac):
payload = b'LEAFDRILL' + bytes((index % 100,) * 8)
icmp = struct.pack('!BBHHH', 8, 0, 0, 0x4C42, index % 65536) + payload
ck = checksum(icmp)
icmp = icmp[:2] + struct.pack('!H', ck) + icmp[4:]
total = 20 + len(icmp)
a, b = socket.inet_aton(src), socket.inet_aton(dst)
ip = struct.pack('!BBHHHBBH4s4s', 0x45, 0, total, index % 65536, 0, 64,
1, 0, a, b)
ip = ip[:10] + struct.pack('!H', checksum(ip)) + ip[12:]
return dmac + smac + b'\x08\x00' + ip + icmp
def pcap_write(path, packets):
with path.open('wb') as f:
f.write(struct.pack('<IHHIIII', 0xa1b2c3d4, 2, 4, 0, 0, 65535, 1))
t = time.time()
for i, data in enumerate(packets):
stamp = t + i * 0.001
f.write(struct.pack('<IIII', int(stamp), int(stamp % 1 * 1e6),
len(data), len(data)) + data)
def resolve_gateway_mac(gateway, interface):
text = subprocess.run(['ip', 'neigh', 'show', gateway, 'dev', interface],
capture_output=True, text=True).stdout
match = re.search(r'lladdr ([0-9a-f:]{17})', text)
return bytes.fromhex(match.group(1).replace(':', '')) if match else None
def route_via(dst):
"""Resolve (gw, dev) for a destination via the kernel routing table."""
out = subprocess.run(['ip', 'route', 'get', dst],
capture_output=True, text=True).stdout
m = re.search(r'via (\S+) dev (\S+)', out)
return m.groups() if m else (None, None)
def mac(value):
return bytes.fromhex(value.replace(':', ''))
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument('mode', choices=['icmp', 'syn'])
ap.add_argument('--dst', required=True,
help='comma-separated TEST-NET destinations (one-shot '
'flows per dst in (a)); single dst for bursts in (b)')
ap.add_argument('--count', type=int, default=1, help='packets per dst')
ap.add_argument('--port', type=int, default=22)
ap.add_argument('--src', default='', help='spoofed TEST-NET source')
ap.add_argument('--allow-real-src', action='store_true',
help='use the interface address as src (no spoofing)')
ap.add_argument('--interface', default='eth0')
ap.add_argument('--gateway', default='', help='override next-hop (default: '
'kernel route for first --dst)')
ap.add_argument('--no-arp', action='store_true',
help='skip gateway ping probe, use cached ARP entry only')
ap.add_argument('--interval', type=float, default=0.25)
ap.add_argument('--pcap', type=Path,
help='write fixture pcap instead of sending (never on live)')
a = ap.parse_args()
nets = list(_NETS)
dsts = [d.strip() for d in a.dst.split(',') if d.strip()]
if not dsts or not all(in_testnet(d) for d in dsts):
ap.error('--dst must be TEST-NET address(es) only')
if a.src and not in_testnet(a.src):
ap.error('--src must be TEST-NET')
if a.src and a.allow_real_src:
ap.error('--src and --allow-real-src are mutually exclusive')
if not 1 <= a.count <= 500 or not 1 <= a.port <= 65535:
ap.error('count must be 1..500 and port 1..65535')
smac = dmac = b'\x00' * 6 # PCAP fixtures need no real Ethernet endpoint
def build(src, dst, i):
if a.mode == 'icmp':
return icmp_packet(src, dst, i, smac, dmac)
return syn_packet(src, dst, a.port, i, smac, dmac)
if a.pcap:
packets = []
for dst in dsts:
for i in range(a.count):
packets.append(build(a.src or '198.51.100.7', dst, i))
pcap_write(a.pcap, packets)
print('wrote %d packets to %s' % (len(packets), a.pcap))
return
gw, dev = route_via(dsts[0])
if a.gateway:
gw = a.gateway
iface = dev or a.interface
if not gw:
ap.error('no via-route for %s on this sensor' % dsts[0])
smac = mac(Path('/sys/class/net', iface, 'address').read_text().strip())
dmac = resolve_gateway_mac(gw, iface)
if dmac is None:
if a.no_arp:
ap.error('gateway MAC not cached and --no-arp set')
subprocess.run(['ping', '-c1', '-W1', gw], capture_output=True)
dmac = resolve_gateway_mac(gw, iface)
if dmac is None:
ap.error('gateway MAC unresolved for %s' % gw)
if not a.src and not a.allow_real_src:
ap.error('src defaults to real interface address: pass --src '
'or --allow-real-src')
if a.allow_real_src:
out = subprocess.run(['ip', '-4', 'addr', 'show', iface],
capture_output=True, text=True).stdout
m = re.search(r'inet (\d+\.\d+\.\d+\.\d+)/', out)
if not m:
ap.error('no inet address on interface')
real = m.group(1)
sent = 0
with socket.socket(socket.AF_PACKET, socket.SOCK_RAW, socket.htons(0x0800)) as s:
s.bind((iface, 0))
for dst in dsts:
src = a.src or real
for i in range(a.count):
s.send(build(src, dst, i))
sent += 1
time.sleep(a.interval)
print('sent %d %s packets -> %s' % (sent, a.mode, ','.join(dsts)))
if __name__ == '__main__':
main()

117
tests/live_e2e.py Normal file
View File

@@ -0,0 +1,117 @@
#!/usr/bin/env python3
"""Bounded lab proof: real packets, fresh alerts, router drop counters, TTL cleanup.
Run on workstation: python3 tests/live_e2e.py --output /path/to/evidence.json
Requires deployed LEAF services. Temporarily uses TTL=180; restores config on exit.
"""
import argparse,json,subprocess,time
from pathlib import Path
def main():
ap=argparse.ArgumentParser(description=__doc__)
ap.add_argument('--sensor',default='yuru@192.168.100.84') # lease drifts; verify by hostname LEAF-PROTO
ap.add_argument('--lxc',default='root@172.19.32.3')
ap.add_argument('--second-lxc',default='root@172.19.32.5')
ap.add_argument('--ssh-key',default=str(Path.home()/'.ssh/id_ed25519_alice'))
ap.add_argument('--output',type=Path,required=True)
a=ap.parse_args(); root=Path(__file__).resolve().parents[1]
ssh=['ssh','-F','/dev/null','-i',a.ssh_key,'-o','BatchMode=yes','-o','ConnectTimeout=8']
scp=['scp','-F','/dev/null','-i',a.ssh_key,'-o','BatchMode=yes']
def run(host,cmd):
return subprocess.run(ssh+[host,cmd],capture_output=True,text=True,check=True,timeout=150).stdout
def status(since=0.0):
return json.loads(run(a.sensor,f'sudo -n python3 /tmp/leaf-live-helper.py status --since {since}'))
def syn(n):
print(run(a.lxc,f'python3 /tmp/leaf-send-syn.py 203.0.113.12 192.0.2.201 22 {n}').strip(),flush=True)
def ping(n):
# Different source hosts guarantee distinct Suricata ICMP flows.
for i in range(n):
host=a.lxc if i%2==0 else a.second_lxc
run(host,'ping -c 1 -W 1 192.0.2.202 >/dev/null 2>&1 || test $? -eq 1')
evidence={'started':time.time(),'passed':False}
changed=False
try:
subprocess.run(scp+[str(root/'tests/live_helper.py'),a.sensor+':/tmp/leaf-live-helper.py'],check=True)
subprocess.run(scp+[str(root/'tests/syn_packets.py'),a.lxc+':/tmp/leaf-send-syn.py'],check=True)
baseline=status(); evidence['baseline']=baseline
targets={'203.0.113.12','192.0.2.202'}
if baseline['members'] or baseline['blocks']: raise RuntimeError('live proof requires an idle empty block group/state for counter attribution')
run(a.sensor,'sudo -n python3 /tmp/leaf-live-helper.py short-ttl')
changed=True
run(a.sensor,'sudo -n systemctl restart leaf-controller')
t0=time.time();evidence['traffic_started']=t0
capture=subprocess.Popen(ssh+[a.sensor,f"sudo -n timeout 15 tcpdump -ni eth1 -c 24 -w /tmp/leaf-live-wave-{int(t0)}.pcap 'tcp and src host 203.0.113.12'"],stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True)
time.sleep(1);syn(24);ping(2)
out,err=capture.communicate(timeout=20)
evidence['capture']={'exit':capture.returncode,'summary':err.strip()}
if capture.returncode!=0 or '24 packets captured' not in err: raise RuntimeError('capture did not prove 24 packets')
deadline=time.time()+180
while time.time()<deadline:
current=status(t0)
applied={row['ip'] for row in current['blocks'] if row['applied']}
verified={row['ip'] for row in current['audit'] if row.get('action')=='block' and row.get('verified')}
if targets <= set(current['members']) & applied & verified: break
print('waiting for router commits',flush=True);time.sleep(3)
else: raise RuntimeError('both blocks were not verified')
evidence['blocked']=current
# Detection evidence comes from the controller's own audit trail
# (decisions.jsonl, surfaced by the helper as audit rows), NOT from
# /var/log/suricata-leaf/eve.json: since the unix_stream migration,
# the eve FILE only carries stats; alerts flow over the socket and
# land as 'decision' rows with sid. Both sids must be represented.
ids=[r['sid'] for r in current['audit'] if r.get('action')=='decision']
if not {1000030,1000001} <= set(ids):
# 'decision' rows are written the moment the alert lands on the
# socket; the block row lands up to ~60 s later (VyOS commit). If
# the reads disagree, re-poll briefly before declaring failure.
grace=time.time()+30
while not {1000030,1000001} <= set(ids):
if time.time()>=grace: raise RuntimeError('fresh detection evidence missing')
time.sleep(5)
current=status(t0); evidence['blocked']=current
ids=[r['sid'] for r in current['audit'] if r.get('action')=='decision']
print('Both blocks verified; testing real drop counters',flush=True)
before=current['drop_counters'];syn(3);ping(1)
current=status(t0); evidence['enforced']=current
for rule in ('8','9'):
if current['drop_counters'].get(rule,0)<=before.get(rule,0): raise RuntimeError('drop counter did not increment for rule '+rule)
print('Source and destination drop counters increased; waiting for TTL cleanup',flush=True)
deadline=time.time()+300
while time.time()<deadline:
current=status(t0)
tracked={row['ip'] for row in current['blocks']}
if not targets & (set(current['members']) | tracked): break
time.sleep(5)
else: raise RuntimeError('TTL cleanup did not remove test members')
evidence['expired']=current
# With no remaining IDS-BLOCK members, post-expiry probes must not
# increase either IDS drop counter.
before=current['drop_counters'].get('8',0); before9=current['drop_counters'].get('9',0)
syn(3);ping(1)
time.sleep(2)
current=status(t0);evidence['after_expiry_probes']=current
if current['drop_counters'].get('8',0)>before or current['drop_counters'].get('9',0)>before9:
raise RuntimeError('test drop counters still increment after expiry')
unblocked={e['ip'] for e in current['audit'] if e.get('action')=='unblock' and e.get('verified')}
if not targets<=unblocked: raise RuntimeError('verified unblock audit missing')
final=status();evidence['final']=final
if final['protected_hashes']!=baseline['protected_hashes']: raise RuntimeError('protected router configuration changed')
evidence['passed']=True
print('LIVE E2E PASS: capture -> alert -> durable decisions -> verified router blocks -> drop counters -> TTL cleanup',flush=True)
finally:
try:
if changed:
try:
if not evidence['passed']:
run(a.sensor,f'sudo -n python3 /tmp/leaf-live-helper.py cleanup --since {evidence.get("traffic_started",evidence["started"])}')
finally:
print(run(a.sensor,'sudo -n python3 /tmp/leaf-live-helper.py restore && sudo -n systemctl restart leaf-controller').strip(),flush=True)
except Exception as exc:
evidence['restoration_error']=str(exc)
evidence['passed']=False
raise
finally:
evidence['finished']=time.time()
a.output.parent.mkdir(parents=True,exist_ok=True)
a.output.write_text(json.dumps(evidence,indent=2)+'\n')
if __name__=='__main__':main()

60
tests/live_helper.py Normal file
View File

@@ -0,0 +1,60 @@
"""Sensor-side helper for the bounded live proof. Never emits credentials."""
import argparse,json,sys,time,sqlite3,re,hashlib
from pathlib import Path
import yaml
sys.path.insert(0,'/opt/leaf-controller/controller')
from leaf_controller.vyos_client import VyosClient
p=argparse.ArgumentParser();p.add_argument('command',choices=['status','short-ttl','restore','cleanup']);p.add_argument('--since',type=float,default=0)
a=p.parse_args()
config=Path('/etc/leaf-controller/config.yaml'); backup=Path('/run/leaf-e2e-config.original.yaml')
if a.command=='short-ttl':
if backup.exists(): raise SystemExit('Previous live test backup exists; restore it first')
backup.write_bytes(config.read_bytes());backup.chmod(0o600)
cfg=yaml.safe_load(config.read_text());cfg['policy']['ttl_seconds']=180; cfg['batch_delay']=3
config.write_text(yaml.safe_dump(cfg,sort_keys=False));print('temporary TTL=180, batching=3s');raise SystemExit
if a.command=='restore':
if backup.exists(): config.write_bytes(backup.read_bytes());backup.unlink()
print('original controller configuration restored');raise SystemExit
if a.command=='cleanup':
con=sqlite3.connect('/var/lib/leaf-controller/state.sqlite',timeout=10)
with con:
con.execute("UPDATE blocks SET expires=? WHERE ip IN (?,?) AND first_seen>=?",
(time.time(), '203.0.113.12', '192.0.2.202', a.since))
print('Requested expiry for this run only'); raise SystemExit
from leaf_controller.config import load_config, read_key_env
cfg=load_config(str(config))
key=read_key_env('/etc/leaf-controller/env', cfg.get('vyos.key_env', 'LEAF_VYOS_KEY'))
c=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=75,retries=1)
result={'now':time.time(),'members':c.group_members('IDS-BLOCK')}
text=c._post('/show',{'op':'show','path':['firewall','ipv4','name','VEXLAN-MAOSPF-v4']}).get('data','')
result['drop_counters']={}
for line in text.splitlines():
match=re.match(r'^\s*([89])\s+drop\s+\S+\s+(\d+)\s+(\d+)',line)
if match: result['drop_counters'][match[1]]=int(match[2])
text=c._post('/show',{'op':'show','path':['firewall','ipv4','forward','filter']}).get('data','')
result['forward_destination_drops']=0
for line in text.splitlines():
match=re.match(r'^\s*10\s+drop\s+\S+\s+(\d+)\s+(\d+)',line)
if match: result['forward_destination_drops']=int(match[1])
result['named_drop_counters']=dict(result['drop_counters'])
result['drop_counters']['8']=result['drop_counters'].get('8',0)+result['forward_destination_drops']
con=sqlite3.connect('/var/lib/leaf-controller/state.sqlite')
result['blocks']=[dict(zip(['ip','kind','expires','applied'],r)) for r in con.execute('select ip,kind,expires,applied from blocks')]
result['audit']=[]
for line in Path('/var/log/leaf-controller/decisions.jsonl').read_text().splitlines():
try: row=json.loads(line)
except ValueError: continue
if row.get('ts',0)>=a.since and row.get('ip') in ('203.0.113.12','192.0.2.202'): result['audit'].append(row)
# The live EVE file is stats-only and can temporarily be absent during rename.
# Detection evidence is the audit trail above; do not interpret no file alerts
# as proof of no detections, or depend on stats-file availability for API status.
result['alerts']=None
result['alert_evidence']='controller audit; socket alerts are not journaled to EVE'
result['protected_hashes']={}
if a.since==0:
for path in [['interfaces','ethernet','eth0'],['protocols','ospf'],['protocols','static']]:
data=c.retrieve('showConfig',path).get('data')
result['protected_hashes']['/'.join(path)]=hashlib.sha256(json.dumps(data,sort_keys=True).encode()).hexdigest()
print(json.dumps(result))

144
tests/live_negative.py Normal file
View File

@@ -0,0 +1,144 @@
#!/usr/bin/env python3
"""Negative IDS counter drill: benign traffic does not match the IDS drop while a blocked
src sits in IDS-BLOCK. Run on workstation: python3 tests/live_negative.py \
--output /path/to/evidence.json
Flow: trigger a real block (sid 1000030 injector, spoofed src 203.0.113.12),
then from a DIFFERENT host (second LXC) with a clean TEST-NET src (192.0.2.97)
push benign TCP SYN
flows (count below the 12-packet sid threshold) at the existing transit dst on
a port the drill never touches. Proof while the block is active:
- benign SYN packets are captured on the ingress mirror (does not establish destination receipt);
- the IDS-BLOCK member for the blocked src is still present and verified;
- rule-9 drop counter grows ONLY for the re-probed blocked src, not benign;
- the benign source is absent from IDS-BLOCK and the state database.
Then TTL expiry cleans up like live_e2e does. TTL=180 for the run; config
restored on exit. Never adds listeners/services on the router; uses existing
transit destinations. Health and capture metrics are included in the results.
"""
import argparse,json,subprocess,time,ipaddress
from pathlib import Path
BLOCKED='203.0.113.12'
def main():
ap=argparse.ArgumentParser(description=__doc__)
ap.add_argument('--sensor',default='yuru@192.168.100.84')
ap.add_argument('--lxc',default='root@172.19.32.3')
ap.add_argument('--benign-host',default='root@172.19.32.5')
ap.add_argument('--benign-src',default='192.0.2.97')
ap.add_argument('--ssh-key',default=str(Path.home()/'.ssh/id_ed25519_alice'))
ap.add_argument('--output',type=Path,required=True)
a=ap.parse_args(); root=Path(__file__).resolve().parents[1]
try:
addr=ipaddress.IPv4Address(a.benign_src)
except ValueError:
ap.error('--benign-src must be a TEST-NET IPv4 address')
if not any(addr in ipaddress.ip_network(n) for n in ('192.0.2.0/24','198.51.100.0/24','203.0.113.0/24')) or a.benign_src==BLOCKED:
ap.error('--benign-src must be a distinct TEST-NET address')
ssh=['ssh','-F','/dev/null','-i',a.ssh_key,'-o','BatchMode=yes','-o','ConnectTimeout=8']
scp=['scp','-F','/dev/null','-i',a.ssh_key,'-o','BatchMode=yes']
def run(host,cmd):
return subprocess.run(ssh+[host,cmd],capture_output=True,text=True,check=True,timeout=150).stdout
def status(since=0):
return json.loads(run(a.sensor,f'sudo -n python3 /tmp/leaf-live-helper.py status --since {since}'))
def syn(host,src,dst,port,n):
print(run(host,f'python3 /tmp/leaf-send-syn.py {src} {dst} {port} {n}').strip(),flush=True)
def metrics_tail():
lines=run(a.sensor,'sudo -n journalctl -u leaf-controller --since "-4 min" --no-pager | grep "leaf.metrics" | tail -4')
capture=run(a.sensor,'sudo -n tail -n 2 /var/log/leaf-controller/capture.log 2>/dev/null || true')
return {'health':[l.split('leaf.metrics: ',1)[1] for l in lines.splitlines() if 'leaf.metrics'],
'capture_windows':[json.loads(l) for l in capture.splitlines() if l]}
evidence={'started':time.time(),'passed':False}
changed=False
try:
subprocess.run(scp+[str(root/'tests/live_helper.py'),a.sensor+':/tmp/leaf-live-helper.py'],check=True)
subprocess.run(scp+[str(root/'tests/syn_packets.py'),a.lxc+':/tmp/leaf-send-syn.py'],check=True)
subprocess.run(scp+[str(root/'tests/syn_packets.py'),a.benign_host+':/tmp/leaf-send-syn.py'],check=True)
baseline=status(); evidence['baseline']=baseline
if baseline['members'] or baseline['blocks']: raise RuntimeError('negative proof requires idle empty group/state for counter attribution')
if BLOCKED in set(baseline['members']): raise RuntimeError('drill address already blocked; refusing to alter existing ownership')
if a.benign_src in set(baseline['members']): raise RuntimeError('benign src already blocked; run clean of it first')
# An empty baseline allows rule-9 changes to be attributed to the
# test source. Ingress capture establishes observation, not delivery.
clean_member_state = not baseline['members']
run(a.sensor,'sudo -n python3 /tmp/leaf-live-helper.py short-ttl')
changed=True
run(a.sensor,'sudo -n systemctl restart leaf-controller')
t0=time.time(); evidence['traffic_started']=t0
capture=subprocess.Popen(ssh+[a.sensor,f"sudo -n timeout 15 tcpdump -ni eth1 -c 24 -w /tmp/leaf-neg-block-{int(t0)}.pcap 'tcp and src host 203.0.113.12 and dst port 22'"],stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True)
time.sleep(1); syn(a.lxc,BLOCKED,'192.0.2.201',22,24)
out,err=capture.communicate(timeout=20)
evidence['block_trigger']={'exit':capture.returncode,'summary':err.strip()}
if capture.returncode!=0 or '24 packets captured' not in err: raise RuntimeError('block-trigger capture did not prove 24 packets')
deadline=time.time()+180
while time.time()<deadline:
current=status(t0)
applied={row['ip'] for row in current['blocks'] if row['applied']}
verified={row['ip'] for row in current['audit'] if row.get('action')=='block' and row.get('verified')}
if BLOCKED in set(current['members']) and BLOCKED in applied and BLOCKED in verified: break
print('waiting for router commit',flush=True);time.sleep(3)
else: raise RuntimeError('block was not verified')
evidence['blocked']=current
print(f'block verified; benign flows from {a.benign_src} under active block',flush=True)
before_neg=current['drop_counters']
neg=subprocess.Popen(ssh+[a.sensor,f"sudo -n timeout 15 tcpdump -ni eth1 -c 12 -w /tmp/leaf-neg-benign-{int(t0)}.pcap 'tcp and src host {a.benign_src} and dst port 80'"],stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True)
time.sleep(1); syn(a.benign_host,a.benign_src,'192.0.2.201',80,6)
time.sleep(2); syn(a.benign_host,a.benign_src,'192.0.2.201',80,6)
out,err=neg.communicate(timeout=20)
evidence['benign_capture']={'exit':neg.returncode,'summary':err.strip()}
if neg.returncode!=0 or '12 packets captured' not in err: raise RuntimeError('benign flow was not observed on the ingress mirror under active block')
current=status(t0); evidence['during_benign']=current
if BLOCKED not in set(current['members']): raise RuntimeError('blocked member vanished during benign window')
if a.benign_src in set(current['members']): raise RuntimeError('benign src entered IDS-BLOCK')
if a.benign_src in {row['ip'] for row in current['blocks']}: raise RuntimeError('benign src entered state db')
if clean_member_state and current['drop_counters'].get('9',0)!=before_neg.get('9',0):
raise RuntimeError('rule-9 drop counter grew for benign src')
print('benign flows observed without IDS drop-counter growth; re-probing blocked src',flush=True)
before=current['drop_counters']; syn(a.lxc,BLOCKED,'192.0.2.201',22,3)
current=status(t0); evidence['enforced']=current
if current['drop_counters'].get('9',0)<=before.get('9',0): raise RuntimeError('rule-9 drop counter did not grow for blocked src')
if clean_member_state:
again=status(t0); before2=again['drop_counters']; syn(a.benign_host,a.benign_src,'192.0.2.201',80,3)
current=status(t0); evidence['benign_reprobe']=current
if current['drop_counters'].get('9',0)!=before2.get('9',0): raise RuntimeError('rule-9 counter grew for benign re-probe')
# Socket mode has no file alerts. State/member absence above and counters
# are the evidence; ingress capture cannot prove destination delivery.
print('drop counter grew only for blocked src; waiting for TTL cleanup',flush=True)
deadline=time.time()+300
while time.time()<deadline:
current=status(t0)
tracked={row['ip'] for row in current['blocks']}
if BLOCKED not in set(current['members'])|tracked: break
time.sleep(5)
else: raise RuntimeError('TTL cleanup did not remove drill member')
evidence['expired']=current
counters=current['drop_counters']; syn(a.lxc,BLOCKED,'192.0.2.201',22,3)
current=status(t0); evidence['after_expiry_probes']=current
if current['drop_counters']!=counters: raise RuntimeError('drill drop counters still increment after expiry')
unblocked={row['ip'] for row in current['audit'] if row.get('action')=='unblock' and row.get('verified')}
if BLOCKED not in unblocked: raise RuntimeError('verified unblock audit missing')
final=status(); evidence['final']=final
if final['protected_hashes']!=baseline['protected_hashes']: raise RuntimeError('protected router configuration changed')
evidence['metrics']=metrics_tail()
evidence['passed']=True
print('NEGATIVE DRILL PASS: block verified -> benign flows observed on mirror -> '
'rule-9 grows only for blocked src -> benign never entered IDS-BLOCK -> TTL cleanup',flush=True)
finally:
try:
if changed:
try:
if not evidence['passed']:
run(a.sensor,f'sudo -n python3 /tmp/leaf-live-helper.py cleanup --since {evidence.get("traffic_started",evidence["started"])}')
finally:
print(run(a.sensor,'sudo -n python3 /tmp/leaf-live-helper.py restore && sudo -n systemctl restart leaf-controller').strip(),flush=True)
except Exception as exc:
evidence['restoration_error']=str(exc)
evidence['passed']=False
raise
finally:
evidence['finished']=time.time()
a.output.parent.mkdir(parents=True,exist_ok=True)
a.output.write_text(json.dumps(evidence,indent=2)+'\n')
if __name__=='__main__':main()

176
tests/mock_vyos_server.py Normal file
View File

@@ -0,0 +1,176 @@
#!/usr/bin/env python3
"""Mock VyOS HTTP API (2026.03 subset) for offline E2E tests.
Endpoints: GET /info ; POST /configure|/retrieve|/show|/config-file (multipart form: data, key)
State: in-memory address-group; member list mirrored to --state-file on every mutation.
Semantics mirrored from docs: bad key -> 401; semantic errors -> success:false + error.
"""
from __future__ import annotations
import argparse
import email.parser
import json
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
STATE = {"members": set(), "config_comments": {}}
LOCK = threading.Lock()
def dump_state(path: str) -> None:
with open(path, "w") as fh:
json.dump({"members": sorted(STATE["members"])}, fh)
def parse_form(handler) -> dict:
ctype = handler.headers.get("Content-Type", "")
length = int(handler.headers.get("Content-Length", "0"))
body = handler.rfile.read(length)
if "multipart/form-data" in ctype:
import email
import email.policy
msg = email.parser.BytesParser(policy=email.policy.compat32).parsebytes(
b"Content-Type: " + ctype.encode() + b"\r\nMIME-Version: 1.0\r\n\r\n" + body)
out = {}
for part in msg.walk():
if part.get_content_type() == "multipart/form-data":
continue
disp = part.get("Content-Disposition", "")
if "name=" not in disp:
continue
name = disp.split('name="', 1)[1].split('"', 1)[0]
out[name] = part.get_payload(decode=True).decode()
return out
# urlencoded fallback
from urllib.parse import parse_qs
return {k: v[0] for k, v in parse_qs(body.decode()).items()}
class Handler(BaseHTTPRequestHandler):
key_expected = "testkey"
state_file = "mock_state.json"
log_lines = []
def log_message(self, fmt, *args): # quiet
Handler.log_lines.append(fmt % args)
def _send(self, code: int, obj) -> None:
body = json.dumps(obj).encode()
self.send_response(code)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_GET(self):
if self.path == "/info":
self._send(200, {"version": "VYOS mock (22.04 mock for 2026.03 semantics)",
"api": {"status": "healthy"}})
else:
self._send(404, {"success": False, "error": "not found"})
def do_POST(self):
form = parse_form(self)
if form.get("key") != self.key_expected:
self._send(401, {"success": False, "error": "bad auth token"})
return
try:
payload = json.loads(form.get("data", "{}"))
except json.JSONDecodeError:
self._send(400, {"success": False, "error": "data is not valid json"})
return
path = self.path.rstrip("/")
try:
if path == "/configure":
self.handle_configure(payload)
elif path == "/retrieve":
self.handle_retrieve(payload)
elif path == "/show":
self._send(200, {"success": True, "data": "\n".join(
f"[{k}] {v}" for k, v in STATE["config_comments"].items())})
elif path == "/config-file":
if payload.get("op") == "save":
self._send(200, {"success": True})
else:
self._send(400, {"success": False, "error": "unknown op"})
else:
self._send(404, {"success": False, "error": "no endpoint"})
except Exception as exc: # mock: keep simple
self._send(500, {"success": False, "error": f"mock internal: {exc}"})
# ------------------------------------------------------------ configure
def _group_path(self, tokens) -> bool:
return (len(tokens) >= 6 and tokens[:4] ==
["firewall", "group", "address-group", "IDS-BLOCK"] and
tokens[4] == "address")
@staticmethod
def _member(tokens) -> str:
return tokens[5]
def handle_configure(self, payload) -> None:
ops = payload if isinstance(payload, list) else [payload]
with LOCK:
for op in ops:
if not isinstance(op, dict):
self._send(400, {"success": False, "error": "op must be object"})
return
kind, tokens = op.get("op"), op.get("path", [])
if kind not in ("set", "delete", "comment") or not self._group_path(tokens):
self._send(400, {"success": False,
"error": f"mock: unhandled op/path {kind} {tokens}"})
return
member = self._member(tokens)
if kind == "comment":
STATE["config_comments"][member] = op.get("comment", "")
continue
if kind == "set":
STATE["members"].add(member)
else:
STATE["members"].discard(member)
dump_state(self.state_file)
self._send(200, {"success": True,
"comments": [STATE["config_comments"].get(self._member(o["path"]), "")
for o in ops
if isinstance(o.get("path"), list) and self._group_path(o["path"])]})
# ------------------------------------------------------------ retrieve
def handle_retrieve(self, payload) -> None:
if payload.get("op") == "showConfig" and payload.get("path") == ["firewall"]:
self._send(200, {"success": True, "data": {"ipv4": {"forward": {"filter": {"rule": {
"8": {"action": "drop", "destination": {"group": {"address-group": "IDS-BLOCK"}}},
"9": {"action": "drop", "source": {"group": {"address-group": "IDS-BLOCK"}}}
}}}}}})
return
if payload.get("op") != "returnValues":
self._send(400, {"success": False, "error": "mock: only returnValues supported"})
return
tokens = payload.get("path", [])
if (len(tokens) == 5 and tokens[:4] ==
["firewall", "group", "address-group", "IDS-BLOCK"] and tokens[4] == "address"):
with LOCK:
self._send(200, {"success": True, "data": sorted(STATE["members"])})
else:
self._send(400, {"success": False, "error": f"mock: no values for {tokens}"})
def main() -> None:
ap = argparse.ArgumentParser()
ap.add_argument("--port", type=int, default=18443)
ap.add_argument("--state-file", default="mock_state.json")
ap.add_argument("--key", default="testkey")
args = ap.parse_args()
Handler.state_file = args.state_file
Handler.key_expected = args.key
try: # allow pre-seeding foreign members
with open(args.state_file) as fh:
STATE["members"] = set(json.load(fh).get("members", []))
except FileNotFoundError:
pass
srv = ThreadingHTTPServer(("127.0.0.1", args.port), Handler)
print(f"mock vyos api on 127.0.0.1:{args.port} state={args.state_file}", flush=True)
srv.serve_forever()
if __name__ == "__main__":
main()

31
tests/replay_fixture.py Normal file
View File

@@ -0,0 +1,31 @@
#!/usr/bin/env python3
"""Run on the sensor as root: offline packet/rule proof with isolated outputs."""
import json,subprocess,tempfile
from pathlib import Path
import yaml
from syn_packets import packet
import struct,time
def main():
root=Path(tempfile.mkdtemp(prefix='leaf-replay-'))
pcap=root/'fixture.pcap'
with pcap.open('wb') as out:
out.write(struct.pack('<IHHIIII',0xa1b2c3d4,2,4,0,0,65535,1))
for i in range(24):
frame=packet('203.0.113.12','192.0.2.201',22,i)
out.write(struct.pack('<IIII',int(time.time()),i*1000,len(frame),len(frame))+frame)
cfg=yaml.safe_load(Path('/etc/suricata-leaf/suricata-leaf.yaml').read_text())
cfg['outputs']=[{'eve-log': {'enabled': True, 'filetype': 'regular',
'filename': str(root/'eve.json'), 'types': [{'alert': {'metadata': True}}, 'stats']}}]
conf=root/'config.yaml';conf.write_text('%YAML 1.1\n---\n'+yaml.safe_dump(cfg))
subprocess.run(['suricata','-r',str(pcap),'-c',str(conf),'-l',str(root),'--runmode','single'],check=True)
events=[json.loads(line) for line in (root/'eve.json').read_text().splitlines()]
alerts=[e for e in events if e.get('event_type')=='alert']
stats=[e['stats'] for e in events if e.get('event_type')=='stats'][-1]
assert [e['alert']['signature_id'] for e in alerts]==[1000030,1000030],alerts
assert stats['decoder']['pkts']==24 and stats['decoder']['invalid']==0
assert stats['tcp']['syn']==24 and stats['tcp']['invalid_checksum']==0
assert stats['defrag']['ipv4']['fragments']==0
print('OFFLINE REPLAY PASS: 24 valid SYNs, zero fragments/checksum errors, two sid 1000030 alerts')
print('Artifacts:',root)
if __name__=='__main__':main()

166
tests/run_e2e.sh Normal file
View File

@@ -0,0 +1,166 @@
#!/usr/bin/env bash
# E2E prototype test: mock VyOS API + fake Suricata EVE -> controller decisions.
# Run from repo root: bash tests/run_e2e.sh
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
T="$ROOT/tests/.e2e"
PORT=18443
VAULT="$(python3 -c 'import secrets; print(secrets.token_urlsafe(18))')" # ephemeral test credential
rm -rf "$T"; mkdir -p "$T"
trap 'kill $(cat "$T/pids" 2>/dev/null) 2>/dev/null' EXIT
# seed a foreign member directly into mock state (controller should adopt+expire it)
python3 - "$T/mock_state.json" <<'PY'
import json,sys
json.dump({"members": ["198.51.100.7"]}, open(sys.argv[1],"w"))
PY
# --- 1. mock vyos api ---------------------------------------------------
python3 "$ROOT/tests/mock_vyos_server.py" --port $PORT --key "$VAULT" \
--state-file "$T/mock_state.json" > "$T/mock.log" 2>&1 &
echo $! >> "$T/pids"
sleep 1
grep -q "mock vyos api" "$T/mock.log" || { echo "FAIL: mock api not started"; cat "$T/mock.log"; exit 1; }
# --- 2. controller config ------------------------------------------------
cat > "$T/config.yaml" <<YAML
vyos:
url: http://127.0.0.1:$PORT
key_env: LEAF_VAULT
tls_verify: true
block_group: IDS-BLOCK
adopt_foreign_members: true
eve:
path: $T/eve.json
alert_socket:
path: "${LEAF_E2E_SOCKET:-}"
queue_size: 1000
policy:
mode: threshold
min_hits: 2
window_seconds: 300
ttl_seconds: 6
max_blocks: 10
block_src: true
state_db: $T/state.sqlite
audit_log: $T/decisions.jsonl
poll_interval: 0.5
sync_interval: 4.0
YAML
touch "$T/eve.json"
send_event() {
if [ -n "${LEAF_E2E_SOCKET:-}" ]; then
python3 -c 'import socket,sys; s=socket.socket(socket.AF_UNIX); s.connect(sys.argv[1]); s.sendall(sys.stdin.buffer.read()); s.close()' "$LEAF_E2E_SOCKET"
else
cat >> "$T/eve.json"
fi
}
# --- 3. run controller ---------------------------------------------------
( cd "$ROOT/controller" && LEAF_VAULT=$VAULT exec python3 -m leaf_controller.main \
--config "$T/config.yaml" ) > "$T/controller.log" 2>&1 &
echo $! >> "$T/pids"
sleep 2
alert() { # sid dest_ip action
python3 -c '
import json,sys
print(json.dumps({"timestamp":"2026-11-03T12:00:00.000000Z","event_type":"alert",
"src_ip":"203.0.113.7","dest_ip":sys.argv[2],"src_port":41000,"dest_port":80,
"proto":"TCP","alert":{"signature_id":int(sys.argv[1]),"signature":"e2e test",
"severity":2,"action":"allowed",
"metadata":{"leaf_action":[sys.argv[3]]}}}))' "$1" "$2" "$3" | send_event; }
# --- 4. threshold: first hit no-op, second hit must block 192.0.2.5 ------
alert 1000001 192.0.2.5 block; sleep 1.5
alert 1000001 192.0.2.5 block; sleep 2
grep -q "192.0.2.5" "$T/mock_state.json" || { echo "FAIL: expected block of 192.0.2.5"; cat "$T/controller.log"; exit 1; }
# --- 5. allow-list: LAN dest must never be blockable ----------------------
alert 1000001 10.66.0.9 block; alert 1000001 10.66.0.9 block; sleep 2
grep -q "10.66.0.9" "$T/mock_state.json" && { echo "FAIL: allowlisted IP was blocked!"; exit 1; }
# --- 6. log rotation: rotate eve.json, new events must still be seen -----
mv "$T/eve.json" "$T/eve.json.1"; touch "$T/eve.json"
send_event() {
if [ -n "${LEAF_E2E_SOCKET:-}" ]; then
python3 -c 'import socket,sys; s=socket.socket(socket.AF_UNIX); s.connect(sys.argv[1]); s.sendall(sys.stdin.buffer.read()); s.close()' "$LEAF_E2E_SOCKET"
else
cat >> "$T/eve.json"
fi
}
alert 1000002 192.0.2.9 block; sleep 1
alert 1000002 192.0.2.9 block; sleep 2
grep -q "192.0.2.9" "$T/mock_state.json" || { echo "FAIL: rotation: expected block of 192.0.2.9"; cat "$T/controller.log"; exit 1; }
# --- 7. foreign member adoption: 198.51.100.7 was adopted, then expires --
grep -q "adopted foreign member 198.51.100.7" "$T/controller.log" || { echo "FAIL: foreign member not adopted"; grep -i adopt "$T/controller.log"; exit 1; }
# --- 8. TTL expiry: both blocked IPs disappear within ~10s ---------------
end=$((SECONDS+15))
while [ $SECONDS -lt $end ]; do
if ! grep -q "192.0.2.5" "$T/mock_state.json" && ! grep -q "192.0.2.9" "$T/mock_state.json"; then break; fi
sleep 1
done
grep -q "192.0.2.5" "$T/mock_state.json" && { echo "FAIL: TTL expiry didn't unblock 192.0.2.5"; cat "$T/mock_state.json"; exit 1; }
grep -q "192.0.2.9" "$T/mock_state.json" && { echo "FAIL: TTL expiry didn't unblock 192.0.2.9"; cat "$T/mock_state.json"; exit 1; }
# --- 9b. src-mode: block_src metadata + policy.block_src=true ------------
# attacker src from TEST-NET, victim on allowlisted LAN -> src must be blocked,
# victim dest must NOT be blocked, and allowlisted src must be ignored.
# allowlisted (RFC1918-floor) src must never be blocked, even in src mode
cat > "$T/fakeeve_floor.py" <<'PY'
import json,sys
print(json.dumps({"timestamp":"2026-11-03T12:04:00.000000Z","event_type":"alert",
"src_ip":"10.130.0.5","dest_ip":"10.66.0.9","src_port":41000,"dest_port":22,
"proto":"TCP","alert":{"signature_id":1000020,"signature":"e2e floor test","severity":2,
"action":"allowed","metadata":{"leaf_action":["block_src"]}}}))
PY
python3 "$T/fakeeve_floor.py" | send_event; sleep 1
python3 "$T/fakeeve_floor.py" | send_event; sleep 2
grep -q "10.130.0.5" "$T/mock_state.json" && { echo "FAIL: allowlisted src was blocked!"; exit 1; }
cat > "$T/fakeeve_src.py" <<'PY'
import json,sys
# src from TEST-NET (blockable) hitting allowlisted dest
line = json.dumps({"timestamp":"2026-11-03T12:05:00.000000Z","event_type":"alert",
"src_ip":"198.51.100.42","dest_ip":"10.66.0.9","src_port":41001,"dest_port":22,
"proto":"TCP","alert":{"signature_id":1000020,"signature":"e2e src test","severity":2,
"action":"allowed","metadata":{"leaf_action":["block_src"]}}})
print(line)
PY
python3 "$T/fakeeve_src.py" | send_event; sleep 1
python3 "$T/fakeeve_src.py" | send_event; sleep 2
grep -q "198.51.100.42" "$T/mock_state.json" || { echo "FAIL: src-mode block of 198.51.100.42 missing"; cat "$T/controller.log"; exit 1; }
# --- 9c. unix_stream socket replay: fake suricata client -> controller ----
# exercises the real AF_UNIX path end-to-end: the controller listens, a
# client connects and streams newline-delimited JSON; the same threshold
# pair must block 192.0.2.42 through the socket path alone
if [ -n "${LEAF_E2E_SOCKET:-}" ]; then
python3 - "$LEAF_E2E_SOCKET" <<'PY'
import json, socket, sys
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(sys.argv[1])
rec = {"timestamp": "2026-11-03T12:06:00.000000Z", "event_type": "alert",
"src_ip": "203.0.113.77", "dest_ip": "192.0.2.42",
"src_port": 41002, "dest_port": 80, "proto": "TCP",
"alert": {"signature_id": 1000001, "signature": "socket e2e",
"severity": 2, "action": "allowed",
"metadata": {"leaf_action": ["block"]}}}
for _ in range(2):
s.sendall((json.dumps(rec) + "\n").encode())
s.close()
PY
sleep 2
grep -q "192.0.2.42" "$T/mock_state.json" || { echo "FAIL: socket replay: expected block of 192.0.2.42"; cat "$T/controller.log"; exit 1; }
fi
# --- 10. audit log sanity --------------------------------------------------
grep -q '"action": "block"' "$T/decisions.jsonl" || { echo "FAIL: audit missing block entries"; exit 1; }
grep -q '"action": "unblock"' "$T/decisions.jsonl" || { echo "FAIL: audit missing unblock entries"; exit 1; }
echo "E2E PASS"

59
tests/syn_packets.py Normal file
View File

@@ -0,0 +1,59 @@
#!/usr/bin/env python3
"""Bounded TEST-NET SYN generator; --pcap writes a fixture without sending traffic."""
import argparse
import ipaddress
import re
import socket
import struct
import subprocess
import time
from pathlib import Path
def checksum(data):
if len(data)%2: data += b'\0'
total=sum(struct.unpack('!%dH'%(len(data)//2),data))
while total>>16: total=(total&0xffff)+(total>>16)
return (~total)&0xffff
def packet(src,dst,dport,index,smac=b'\x02\0\0\0\0\1',dmac=b'\x02\0\0\0\0\2',flags=2):
a,b=socket.inet_aton(src),socket.inet_aton(dst)
tcp=struct.pack('!HHIIBBHHH',40000+index%20000,dport,7000+index,0,0x50,flags,1024,0,0)
pseudo=a+b+struct.pack('!BBH',0,6,len(tcp))
tcp=tcp[:16]+struct.pack('!H',checksum(pseudo+tcp))+tcp[18:]
ip=struct.pack('!BBHHHBBH4s4s',0x45,0,40,index%65536,0,64,6,0,a,b)
ip=ip[:10]+struct.pack('!H',checksum(ip))+ip[12:]
return dmac+smac+b'\x08\0'+ip+tcp
def main():
ap=argparse.ArgumentParser(description=__doc__)
ap.add_argument('src'); ap.add_argument('dst'); ap.add_argument('port',type=int); ap.add_argument('count',type=int)
ap.add_argument('--pcap',type=Path); ap.add_argument('--interface',default='eth0'); ap.add_argument('--gateway',default='172.19.32.1')
a=ap.parse_args()
nets=[ipaddress.ip_network(n) for n in ('192.0.2.0/24','198.51.100.0/24','203.0.113.0/24')]
if not all(any(ipaddress.ip_address(ip) in n for n in nets) for ip in (a.src,a.dst)):
ap.error('source and destination must be TEST-NET addresses')
if not 1<=a.count<=500 or not 1<=a.port<=65535: ap.error('count must be 1..500 and port 1..65535')
if a.pcap:
with a.pcap.open('wb') as f:
f.write(struct.pack('<IHHIIII',0xa1b2c3d4,2,4,0,0,65535,1))
t=time.time()
for i in range(a.count):
data=packet(a.src,a.dst,a.port,i)
stamp=t+i*.001
f.write(struct.pack('<IIII',int(stamp),int(stamp%1*1e6),len(data),len(data))+data)
print('wrote',a.count,'packets to',a.pcap)
return
def mac(value): return bytes.fromhex(value.replace(':',''))
smac=mac(Path('/sys/class/net',a.interface,'address').read_text().strip())
subprocess.run(['ping','-c1','-W1',a.gateway],capture_output=True)
text=subprocess.run(['ip','neigh','show',a.gateway,'dev',a.interface],capture_output=True,text=True,check=True).stdout
match=re.search(r'lladdr ([0-9a-f:]{17})',text)
if not match: ap.error('gateway MAC unresolved')
with socket.socket(socket.AF_PACKET,socket.SOCK_RAW,socket.htons(0x0800)) as s:
s.bind((a.interface,0))
for i in range(a.count):
s.send(packet(a.src,a.dst,a.port,i,smac,mac(match.group(1))))
time.sleep(.01)
print('sent',a.count,'SYNs',a.src,'->',a.dst+':'+str(a.port))
if __name__=='__main__': main()

135
tests/test_alertsock.py Normal file
View File

@@ -0,0 +1,135 @@
"""Framing tests for the suricata unix_stream listener (suricata is the
client; the controller owns the listening socket). Uses real AF_UNIX
connections, no suricata binary needed."""
import os
import socket
import tempfile
import time
import unittest
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'controller'))
from leaf_controller.alertsock import AlertSocket
class AlertSocketTest(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.path = os.path.join(self.tmp.name, 'alerts.sock')
self.sock = AlertSocket(self.path, 100)
self.sock.bind()
self.sock.start()
def tearDown(self):
self.sock.close()
self.tmp.cleanup()
def _client(self):
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(self.path)
return s
def _wait(self, n=1, pred=None, timeout=5.0):
"""wait until drain() has >= n records, or pred() is true"""
deadline = time.time() + timeout
recs = []
while time.time() < deadline:
recs = self.sock.drain()
if len(recs) >= n and (pred is None or pred()):
return recs
time.sleep(0.05)
return recs
def _rec(self, n):
return ('{"event_type": "alert", "n": %d}\n' % n).encode()
def test_single_connection_streams_records(self):
s = self._client()
s.sendall(self._rec(1) + self._rec(2))
s.close()
recs = self._wait(2)
self.assertEqual([r['n'] for r in recs], [1, 2])
def test_partial_line_frames_only_on_newline(self):
s = self._client()
s.sendall(b'{"event_type": "alert", "n"')
time.sleep(0.3)
self.assertEqual(self.sock.drain(), [])
s.sendall(b': 7}\n')
recs = self._wait(1)
self.assertEqual([r['n'] for r in recs], [7])
s.close()
def test_non_alert_records_counted_other_never_queued(self):
# ingress gate: the socket output block carries alerts only; a
# stray stats record must never reach policy/state
s = self._client()
s.sendall(b'{"event_type": "stats", "x": 1}\n')
s.close()
self._wait(0, pred=lambda: self.sock.counts['other'] >= 1)
self.assertEqual(self.sock.drain(), [])
self.assertGreaterEqual(self.sock.counts['other'], 1)
def test_reconnect_yields_continuous_stream(self):
self._client().close()
s = self._client()
s.sendall(self._rec(1) + self._rec(2))
s.close()
recs = self._wait(2)
self.assertEqual([r['n'] for r in recs], [1, 2])
self.assertGreaterEqual(self.sock.counts['connections'], 2)
def test_garbage_and_non_object_lines_counted_not_hung_controller(self):
s = self._client()
s.sendall(b'not-json\n[1,2,3]\n' + self._rec(1))
s.close()
# unparseable line -> parse_errors; valid JSON but not an alert
# object -> other gate; the good record must still flow through
recs = self._wait(1, pred=lambda: self.sock.counts['parse_errors'] >= 1
and self.sock.counts['other'] >= 1)
self.assertEqual([r['n'] for r in recs], [1])
self.assertGreaterEqual(self.sock.counts['parse_errors'], 1)
self.assertGreaterEqual(self.sock.counts['other'], 1)
def test_queue_overflow_drops_are_counted(self):
# bounded queue: a stalled consumer forces the eager-drain semantics
# and losses must be visible in counts, never silently dropped
self.sock.close()
self.sock = AlertSocket(self.path, 1)
self.sock.bind()
self.sock.start()
s = self._client()
s.sendall(self._rec(1) + self._rec(2) + self._rec(3))
s.close()
deadline = time.time() + 5.0
while time.time() < deadline and self.sock.counts['queue_drops'] < 1:
time.sleep(0.05)
self.assertGreaterEqual(self.sock.counts['queue_drops'], 1)
recs = self.sock.drain()
self.assertEqual(len(recs), 1) # exactly the survivor of the burst
def test_close_removes_socket_file(self):
self.assertTrue(os.path.exists(self.path))
self.sock.close()
self.assertFalse(os.path.exists(self.path))
def test_bind_replaces_stale_socket_path(self):
# An unowned socket whose listener has exited can be reclaimed.
# Active listeners and separately locked socket paths are protected.
self.sock.close()
stale = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
stale.bind(self.path)
stale.close()
self.sock = AlertSocket(self.path, 10)
self.sock.bind()
self.sock.start()
s = self._client()
s.sendall(self._rec(1))
s.close()
recs = self._wait(1)
self.assertEqual([r['n'] for r in recs], [1])
if __name__ == '__main__':
unittest.main()

448
tests/test_controller.py Normal file
View File

@@ -0,0 +1,448 @@
"""Offline regression tests. No lab access or router writes."""
import copy
import json
import os
from pathlib import Path
import sys
import tempfile
import threading
import time
import unittest
from unittest.mock import patch
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'controller'))
from leaf_controller.config import Config, DEFAULTS
from leaf_controller.eve import EveTailer
from leaf_controller.main import Controller
from leaf_controller.vyos_client import (
PinMismatchError, VyosClient, VyosApiError, normalize_pin)
class Router:
member_op = staticmethod(VyosClient.member_op)
def __init__(self, members=()):
self.members = set(members)
self.commits = []
self.fail = False
self.after_commit = None
def op_with_retry(self, fn, *args): return fn(*args)
def group_members(self, group): return sorted(self.members)
def configure(self, ops):
self.commits.append(ops)
for op in ops:
ip = op['path'][-1]
if op['op'] == 'set': self.members.add(ip)
else: self.members.discard(ip)
if self.after_commit: self.after_commit()
if self.fail: raise TimeoutError('commit acknowledged too late')
return {'success': True}
def save_config(self): pass
class Tests(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.root = Path(self.tmp.name)
raw = copy.deepcopy(DEFAULTS)
raw.update(state_db=str(self.root/'state.sqlite'), audit_log=str(self.root/'audit.jsonl'))
raw['policy'].update(mode='immediate', block_src=True)
with patch.object(Config, 'vyos_key', return_value='offline-test'):
self.ctl = Controller(Config(raw), dry_run=False)
self.router = self.ctl.client = Router()
def tearDown(self):
self.ctl.close()
self.tmp.cleanup()
def alert(self, ip='192.0.2.77', action='block', src='203.0.113.11'):
return {'event_type':'alert','src_ip':src,'dest_ip':ip,
'alert':{'signature_id':1000001,'metadata':{'leaf_action':[action]}}}
def test_decision_is_durable_without_api(self):
self.ctl.handle_event(self.alert())
self.assertIsNotNone(self.ctl.state.get('192.0.2.77'))
self.assertFalse(self.router.commits)
def test_batch_dedup_readback_and_expiry(self):
for ip in ('192.0.2.77','192.0.2.78','192.0.2.77'):
self.ctl.handle_event(self.alert(ip))
self.ctl.sync_router_state()
self.assertEqual(len(self.router.commits),1)
self.assertEqual(len(self.router.commits[0]),2)
self.assertTrue(self.ctl.state.get('192.0.2.77').applied)
self.ctl.state.con.execute('UPDATE blocks SET expires=?',(time.time()-1,))
self.ctl.state.con.commit()
self.ctl.sync_router_state()
self.assertEqual(self.router.members,set())
self.assertEqual(self.ctl.state.all_blocks(),[])
def test_expired_startup_not_adopted(self):
self.ctl.state.upsert_hit('192.0.2.77','dest',1,1,now=time.time()-10)
self.router.members.add('192.0.2.77')
self.ctl.sync_router_state()
self.assertIsNone(self.ctl.state.get('192.0.2.77'))
self.assertFalse(self.router.members)
def test_state_owned_group_removes_stale_router_members(self):
self.ctl.cfg.raw['adopt_foreign_members']=False
self.router.members.add('192.0.2.77')
self.ctl.sync_router_state()
self.assertFalse(self.router.members)
self.assertEqual(self.ctl.state.all_blocks(),[])
def test_timeout_verified_before_resubmit(self):
self.ctl.handle_event(self.alert())
self.router.fail=True
with self.assertRaises(TimeoutError): self.ctl.sync_router_state()
self.router.fail=False
self.ctl.sync_router_state()
self.assertEqual(len(self.router.commits),1)
self.assertTrue(self.ctl.state.get('192.0.2.77').applied)
def test_refresh_during_delete_is_retained(self):
self.ctl.state.upsert_hit('192.0.2.77','dest',1,1,now=time.time()-10)
self.router.members.add('192.0.2.77')
self.router.after_commit=lambda: self.ctl.handle_event(self.alert())
self.ctl.sync_router_state()
self.assertGreater(self.ctl.state.get('192.0.2.77').expires,time.time())
self.assertFalse(self.ctl.state.get('192.0.2.77').applied)
self.router.after_commit=None
self.ctl.sync_router_state()
self.assertIn('192.0.2.77',self.router.members)
def test_slow_commit_does_not_block_decisions(self):
self.ctl.handle_event(self.alert())
started, release = threading.Event(), threading.Event()
self.router.after_commit=lambda: (started.set(),release.wait(3))
def worker():
try: self.ctl.sync_router_state()
finally: self.ctl.state.close()
t=threading.Thread(target=worker); t.start()
self.assertTrue(started.wait(2))
t0=time.monotonic()
for n in range(10): self.ctl.handle_event(self.alert(f'192.0.2.{n+100}'))
elapsed=time.monotonic()-t0
release.set(); t.join(3)
self.assertLess(elapsed,1)
self.assertEqual(self.ctl.state.count_active(),11)
def test_floor_src_ipv6_and_bad_events(self):
for ip in ('10.0.249.0','172.19.32.3','192.168.100.83','127.0.0.1','0.0.0.0','255.255.255.255','::1','bogus'):
self.ctl.handle_event(self.alert(ip))
for e in ({'event_type':'alert','alert':None}, {'event_type':'alert','alert':{'signature_id':'bad'}}, {'event_type':'tls'}):
self.ctl.handle_event(e)
self.assertEqual(self.ctl.state.count_active(),0)
self.ctl.handle_event(self.alert(action='block_src'))
self.assertIsNotNone(self.ctl.state.get('203.0.113.11'))
def test_dry_run_cannot_seed_live_blocks(self):
dry = Controller(self.ctl.cfg, dry_run=True)
try:
dry.handle_event(self.alert())
self.assertIsNotNone(dry.state.get('192.0.2.77'))
self.assertIsNone(self.ctl.state.get('192.0.2.77'))
finally: dry.close()
def test_cap(self):
self.ctl.cfg.raw['policy']['max_blocks']=1
self.ctl.handle_event(self.alert())
self.ctl.handle_event(self.alert('192.0.2.78'))
self.assertEqual(self.ctl.state.count_active(),1)
def test_single_instance_and_wal(self):
with self.assertRaises(SystemExit): Controller(self.ctl.cfg,dry_run=False)
self.assertEqual(self.ctl.state.con.execute('pragma journal_mode').fetchone()[0],'wal')
def test_drift_repaired(self):
self.ctl.handle_event(self.alert()); self.ctl.sync_router_state()
self.router.members.clear(); self.ctl.sync_router_state()
self.assertIn('192.0.2.77',self.router.members)
def test_partial_write_rotation_truncation(self):
f=self.root/'eve.json'; f.write_bytes(b'')
tail=EveTailer(str(f),from_start=True); fh=tail._open()
f.write_bytes(b'{"event_type":')
self.assertEqual(tail._read_ready(fh),[])
with f.open('ab') as w: w.write(b'"alert"}\n')
lines=tail._read_ready(fh)
self.assertEqual(tail._parse(lines[0]),{'event_type':'alert'})
f.write_bytes(b'')
self.assertTrue(tail._needs_reopen())
f.rename(self.root/'eve.old'); f.write_text('{}\n')
self.assertTrue(tail._needs_reopen())
tail.close()
def test_rotation_drains_more_than_one_batch(self):
f=self.root/'eve.json'; f.write_text('{}\n'*1100)
tail=EveTailer(str(f),poll_interval=.001,from_start=True)
tail._open()
f.rename(self.root/'eve.old'); f.write_text('{"new":true}\n')
events=tail.events()
received=[next(events) for _ in range(1101)]
self.assertEqual(received[-1],{'new':True})
self.assertEqual(received[:-1],[{}]*1100)
events.close()
def test_checkpoint_resumes_alerts_written_during_shutdown(self):
f=self.root/'eve.json'; f.write_text('')
tail=EveTailer(str(f)); tail._open()
self.ctl.state.save_checkpoint(*tail._ino, tail._pos)
tail.close()
# controller is down; suricata keeps appending
with f.open('ab') as w: w.write(b'{"event_type":"alert","missed":true}\n')
ck=self.ctl.state.get_checkpoint()
resumed=EveTailer(str(f), checkpoint=ck); fh=resumed._open()
self.assertEqual([resumed._parse(l) for l in resumed._read_ready(fh)],
[{'event_type':'alert','missed':True}])
resumed.close()
def test_checkpoint_ignored_on_first_run_never_replays_history(self):
f=self.root/'eve.json'; f.write_text('{"ancient":true}\n')
t=EveTailer(str(f)); fh=t._open()
self.assertEqual(t._read_ready(fh),[])
self.assertIsNone(self.ctl.state.get_checkpoint())
t.close()
def test_checkpoint_across_rotation_reads_new_file_from_start(self):
f=self.root/'eve.json'; f.write_text('{"old":true}\n')
t=EveTailer(str(f)); t._open()
self.ctl.state.save_checkpoint(*t._ino, t._pos); t.close()
f.rename(self.root/'eve.old'); f.write_text('{"fresh":true}\n')
r=EveTailer(str(f), checkpoint=self.ctl.state.get_checkpoint()); fh=r._open()
self.assertEqual([r._parse(l) for l in r._read_ready(fh)],[{'fresh':True}])
r.close()
def test_audit_log_rotation_bounded(self):
from leaf_controller.main import Audit
p=str(self.root/'dec.jsonl')
a=Audit(p, max_bytes=50, keep=2)
for i in range(20): a.write({'i':i,'pad':'x'*80})
a.close()
rotated=list(self.root.glob('dec.jsonl.*'))
self.assertEqual(len(rotated),2) # exactly 'keep' retained
for old in rotated:
self.assertTrue(old.stat().st_size>0)
# every rotated line is a valid decision record
recs=[]
for f in rotated:
with open(f) as fh:
recs += [json.loads(l) for l in fh]
self.assertTrue(all(r['pad']=='x'*80 for r in recs))
def test_new_file_after_startup_is_not_skipped(self):
f=self.root/'missing-eve.json'
tail=EveTailer(str(f))
self.assertIsNone(tail._open())
f.write_text('{"event_type":"alert"}\n')
fh=tail._open()
self.assertEqual(len(tail._read_ready(fh)),1)
tail.close()
def test_idle_reader_waits(self):
f=self.root/'eve.json'; f.touch()
tail=EveTailer(str(f),poll_interval=.05)
events=tail.events(); start=time.monotonic()
self.assertIsNone(next(events))
self.assertGreaterEqual(time.monotonic()-start,.04)
events.close()
def test_packet_headers_and_checksums(self):
import pathlib, sys
from syn_packets import packet, checksum
import socket, struct
frame=packet('203.0.113.12','192.0.2.201',22,0)
ip,tcp=frame[14:34],frame[34:]
self.assertEqual(len(frame),54)
self.assertEqual(struct.unpack('!H',ip[6:8])[0],0)
self.assertEqual(ip[8:10],bytes([64,6]))
self.assertEqual(tcp[13],2)
self.assertEqual(checksum(ip),0)
pseudo=socket.inet_aton('203.0.113.12')+socket.inet_aton('192.0.2.201')+struct.pack('!BBH',0,6,20)
self.assertEqual(checksum(pseudo+tcp),0)
def test_unattached_firewall_hook_rejected(self):
client=VyosClient('http://example.invalid','test')
hook={'action':'drop','source':{'group':{'address-group':'IDS-BLOCK'}}}
fw={'ipv4':{'forward':{'filter':{'rule':{'10':{'action':'drop','destination':{'group':{'address-group':'IDS-BLOCK'}}}}}},'name':{'unused':{'rule':{'9':hook}}}}}
with patch.object(client,'retrieve',return_value={'data':fw}):
with self.assertRaises(VyosApiError): client.verify_enforcement('IDS-BLOCK',True)
fw['zone']={'zone':{'MAOSPF':{'from':{'VEXLAN':{'firewall':{'name':'unused'}}}}}}
with patch.object(client,'retrieve',return_value={'data':fw}): client.verify_enforcement('IDS-BLOCK',True)
def test_show_uses_path(self):
client=VyosClient('http://example.invalid','test')
with patch.object(client,'_post',return_value={'success':True,'data':'counters'}) as post:
self.assertEqual(client.show(['firewall']), 'counters')
post.assert_called_once_with('/show',{'op':'show','path':['firewall']})
def test_ambiguous_api_success_rejected(self):
client=VyosClient('http://example.invalid','test')
response=type('Response',(),{'status_code':200,'json':lambda _: {}})()
with patch.object(client.sess,'post',return_value=response):
with self.assertRaises(VyosApiError): client.configure([])
def test_readback_failure_keeps_pending(self):
self.ctl.handle_event(self.alert())
self.router.group_members=lambda group: []
with self.assertRaises(VyosApiError): self.ctl.sync_router_state()
self.assertFalse(self.ctl.state.get('192.0.2.77').applied)
class MetricsTests(unittest.TestCase):
"""Stats records update metrics without entering the policy path."""
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.root = Path(self.tmp.name)
raw = copy.deepcopy(DEFAULTS)
raw.update(state_db=str(self.root/'state.sqlite'),
audit_log=str(self.root/'audit.jsonl'))
raw['metrics'].update(capture_interval=0, capture_max_bytes=200,
capture_log_keep=2)
with patch.object(Config, 'vyos_key', return_value='offline-test'):
self.ctl = Controller(Config(raw), dry_run=False)
self.router = self.ctl.client = Router()
def tearDown(self):
self.ctl.close()
self.tmp.cleanup()
def stats(self, packets=1000, dropped=0, engine_alerts=3, uptime=120):
"""Mirrors the live eve.json shape: capture/decoder/detect sub-objects,
no 'ifaces' at totals level (threads: no + totals: yes)."""
return {'event_type': 'stats', 'stats': {
'uptime': uptime, 'memcap_pressure': 0,
'capture': {'kernel_packets': packets, 'kernel_drops': dropped,
'errors': 0},
'decoder': {'pkts': packets, 'bytes': packets * 200, 'invalid': 0},
'detect': {'alert': engine_alerts, 'alerts_suppressed': 0,
'alert_queue_overflow': 0}}}
def thread_stats(self, packets=500):
"""Live thread records (flush=False): per-thread counters, no uptime."""
return {'event_type': 'stats', 'stats': {
'capture': {'kernel_packets': packets, 'kernel_drops': 0,
'errors': 0},
'decoder': {'pkts': packets, 'bytes': packets * 100, 'invalid': 0},
'engine': {'alert': 1, 'alerts_suppressed': 0,
'alert_queue_overflow': 0}}}
def test_stats_never_touch_state_router_or_audit(self):
# Verify that stats cannot produce policy decisions:
# 1) routed stats can only ever be counted
for i in range(20):
self.ctl._route(self.stats(packets=100 * i))
self.ctl._route({'event_type': 'dns', 'src_ip': '192.0.2.77'})
self.ctl._route({'event_type': 'http', 'src_ip': '192.0.2.78'})
# 2) even a stats record handed straight to handle_event cannot act
self.ctl.handle_event(self.stats())
self.assertEqual(self.ctl.state.all_blocks(), [])
self.assertEqual(self.ctl.state.count_active(), 0)
self.assertFalse(self.router.commits)
self.assertFalse(self.router.members)
self.assertEqual((self.root/'audit.jsonl').read_text(), '')
self.assertFalse(list(self.root.glob('capture.log*')))
def test_health_line_once_per_full_window(self):
self.ctl._route(self.stats(packets=1000))
self.ctl._emit_metrics(1000.0) # baseline adoption only
self.ctl._route(self.stats(packets=2000, dropped=1))
with self.assertLogs('leaf.metrics', level='INFO') as logs:
self.ctl._emit_metrics(1030.0) # a full window: one line
self.ctl._route(self.stats(packets=2100))
self.ctl._emit_metrics(1040.0) # partial window: stays silent
health = [l for l in logs.output if 'health:' in l]
self.assertEqual(len(health), 1)
self.assertIn('cps=33.3', health[0]) # 1000 pkts / 30 s window
self.assertIn('dropped+=1', health[0])
def test_counter_restart_never_goes_negative(self):
self.ctl._route(self.stats(packets=5000))
self.ctl._emit_metrics(1000.0)
self.ctl._route(self.stats(packets=100, uptime=30)) # suricata restart
rep = self.ctl.metrics.report(1030.0)
self.assertTrue(rep['restart'])
self.assertEqual(rep['delta']['packets'], 100)
self.assertGreaterEqual(rep['cps'], 0)
def test_totals_authoritative_over_thread_records(self):
# live emits alternating thread(flush=False)+totals; mixing the two
# counter sets would produce bogus rates
self.ctl._route(self.thread_stats(packets=500)) # only kind seen: adopted
self.ctl._emit_metrics(1000.0) # baseline
self.ctl._route(self.stats(packets=2000)) # totals authoritative
self.ctl._route(self.thread_stats(packets=100)) # must not override
rep = self.ctl.metrics.report(1030.0)
self.assertFalse(rep['restart'])
self.assertEqual(rep['delta']['packets'], 1500)
def test_capture_log_bounded_by_size(self):
t = 10000.0
for i in range(1, 40):
self.ctl._route(self.stats(packets=1000 * i, dropped=i))
self.ctl._emit_metrics(t)
t += 40
current = self.root/'capture.log'
rotated = sorted(self.root.glob('capture.log.*'))
# bounded growth is the point: current + at most keep rotated files.
# Audit rotates write-then-check, so the newest line may itself sit in
# the most recent rotated file; current can legitimately be empty.
self.assertLessEqual(len(rotated), 2)
self.assertTrue(current.exists())
recs = []
for p in [current] + rotated:
for l in p.read_text().splitlines():
rec = json.loads(l)
self.assertIn('dropped', rec)
self.assertIn('delta', rec)
recs.append(rec)
assert recs
# Each retained line is a complete window snapshot.
# This check covers the size bound; retention order is tested separately.
self.assertTrue(any(r['dropped'] > 0 for r in recs))
# audit rotation is: append, size-check, rotate, prune-to-keep — so an
# over-cap write can land on disk briefly before the prune settles:
# worst settled state is current (~cap) + keep rotated (~cap each)
disk = sum(x.stat().st_size for x in [current] + rotated)
self.assertLess(disk, 200 * 4 + 400) # (keep+2) x cap + slop
class TLSPinTests(unittest.TestCase):
"""Cert-pin trust against a local TLS server with a throwaway cert."""
@classmethod
def setUpClass(cls):
import shutil, ssl, subprocess
from http.server import BaseHTTPRequestHandler, HTTPServer
if shutil.which('openssl') is None:
raise unittest.SkipTest('openssl required for TLS pin tests')
cls.tmp = tempfile.TemporaryDirectory()
key, crt = cls.tmp.name + '/k.pem', cls.tmp.name + '/c.pem'
subprocess.run(['openssl', 'req', '-x509', '-newkey', 'rsa:2048', '-nodes',
'-keyout', key, '-out', crt, '-days', '1',
'-subj', '/CN=localhost'],
check=True, capture_output=True)
out = subprocess.run(['openssl', 'x509', '-in', crt, '-noout',
'-fingerprint', '-sha256'],
check=True, capture_output=True, text=True).stdout
cls.pin = out.split('=')[1].strip()
class H(BaseHTTPRequestHandler):
def do_GET(self):
body = b'{"success": true, "data": {"proto": "pin-test"}}'
self.send_response(200)
self.send_header('Content-Type', 'application/json')
self.send_header('Content-Length', str(len(body)))
self.end_headers()
self.wfile.write(body)
def log_message(self, *a):
pass
cls.srv = HTTPServer(('127.0.0.1', 0), H)
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ctx.load_cert_chain(crt, key)
cls.srv.socket = ctx.wrap_socket(cls.srv.socket, server_side=True)
cls.port = cls.srv.socket.getsockname()[1]
threading.Thread(target=cls.srv.serve_forever, daemon=True).start()
cls.url = f'https://127.0.0.1:{cls.port}'
@classmethod
def tearDownClass(cls):
cls.srv.shutdown(); cls.srv.server_close(); cls.tmp.cleanup()
def test_pin_normalizes_colon_hex(self):
self.assertEqual(normalize_pin(self.pin), self.pin.lower().replace(':', ''))
self.assertEqual(normalize_pin('sha256:' + self.pin.upper()),
self.pin.lower().replace(':', ''))
with self.assertRaises(ValueError):
normalize_pin('not-a-pin')
def test_pinned_client_connects(self):
c = VyosClient(self.url, 'k', cert_pin=self.pin, timeout=10, retries=1)
self.assertEqual(c.info().get('proto'), 'pin-test')
def test_wrong_pin_aborts_before_request(self):
wrong = 'ab' * 32
c = VyosClient(self.url, 'k', cert_pin=wrong, timeout=10, retries=1)
with self.assertRaises(PinMismatchError):
c.info()
if __name__=='__main__': unittest.main()

View File

@@ -0,0 +1,58 @@
#!/usr/bin/env python3
"""Offline unit tests for the drill injector builders (pure local)."""
import importlib.util
import struct
import unittest
from pathlib import Path
spec = importlib.util.spec_from_file_location(
'drill_synsensor', Path(__file__).resolve().parent.parent
/ 'tests' / 'drill_synsensor.py')
ds = importlib.util.module_from_spec(spec)
spec.loader.exec_module(ds)
def onesc(buf):
if len(buf) % 2:
buf += b'\x00'
t = sum(struct.unpack('!%dH' % (len(buf) // 2), buf))
t = (t & 0xFFFF) + (t >> 16)
t = (t & 0xFFFF) + (t >> 16)
return t
class Builders(unittest.TestCase):
def test_icmp_checksums(self):
p = ds.icmp_packet('192.168.100.84', '192.0.2.44', 7,
b'\x11\x22\x33\x44\x55\x66', b'\x66\x55\x44\x33\x22\x11')
self.assertEqual(p[12:14], b'\x08\x00')
ip = p[14:34]
self.assertEqual(onesc(ip) & 0xFFFF, 0xFFFF) # hdr sum incl cksum
icmp = p[34:]
self.assertEqual(icmp[0], 8)
z = icmp[:2] + b'\x00\x00' + icmp[4:]
t = onesc(z)
self.assertEqual((~t) & 0xFFFF, struct.unpack('!H', icmp[2:4])[0])
def test_syn_pseudo_checksum(self):
p = ds.syn_packet('203.0.113.5', '192.0.2.5', 22, 3,
b'\x00' * 6, b'\x00' * 6)
ip = p[14:34]
self.assertEqual(onesc(ip) & 0xFFFF, 0xFFFF)
tcp = p[34:]
self.assertEqual(tcp[13] & 0x02, 0x02) # SYN flag
a, b = ip[12:16], ip[16:20]
ph = a + b + struct.pack('!BBH', 0, 6, len(tcp))
z = tcp[:16] + b'\x00\x00' + tcp[18:]
t = onesc(ph + z)
self.assertEqual((~t) & 0xFFFF, struct.unpack('!H', tcp[16:18])[0])
def test_testnet_guard(self):
self.assertTrue(ds.in_testnet('192.0.2.5'))
self.assertTrue(ds.in_testnet('203.0.113.12'))
self.assertFalse(ds.in_testnet('172.16.0.1'))
self.assertFalse(ds.in_testnet('192.168.100.84'))
if __name__ == '__main__':
unittest.main()

211
tests/test_repairs.py Normal file
View File

@@ -0,0 +1,211 @@
"""Regression tests for ingestion, replay, persistence and credential handling."""
import copy
import importlib.util
import json
import os
from pathlib import Path
import socket
import sys
import tempfile
import threading
import time
import unittest
from unittest.mock import patch, Mock
sys.path.insert(0, str(Path(__file__).resolve().parents[1]/'controller'))
from leaf_controller.alertsock import AlertSocket, MAX_RECORD
from leaf_controller.config import Config, DEFAULTS, load_config, read_key_env
from leaf_controller.eve import EveTailer
from leaf_controller.main import Audit, Controller
from leaf_controller.vyos_client import VyosClient
from test_controller import Router
ROOT=Path(__file__).resolve().parents[1]
def module(name, path):
spec=importlib.util.spec_from_file_location(name, ROOT/path)
m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m);return m
rotation=module('key_rotation', 'scripts/rotate-vyos-key.py')
retention=module('eve_rotation', 'scripts/rotate-eve.py')
injector=module('injector','tests/drill_synsensor.py')
class Repairs(unittest.TestCase):
def setUp(self):
self.tmp=tempfile.TemporaryDirectory();self.root=Path(self.tmp.name)
def tearDown(self): self.tmp.cleanup()
def controller(self):
raw=copy.deepcopy(DEFAULTS)
raw.update(state_db=str(self.root/'state'),audit_log=str(self.root/'audit'))
raw['alert_socket']['path']=str(self.root/'alerts.sock')
raw['policy'].update(mode='immediate',block_src=True)
with patch.object(Config,'vyos_key',return_value='fake'):
c=Controller(Config(raw))
c.client=Router();self.addCleanup(c.close);return c
def event(self):
return dict(event_type='alert',src_ip='203.0.113.12',dest_ip='192.0.2.202',
alert=dict(signature_id=1000001,metadata=dict(leaf_action=['block'])))
def test_dry_run_preserves_live_socket_and_audit(self):
c=self.controller();c._sock.bind()
before=os.stat(c._sock.path).st_ino
dry=Controller(c.cfg,dry_run=True)
try:
dry.handle_event(self.event())
self.assertIsNone(dry._sock)
finally: dry.close()
self.assertEqual(os.stat(c._sock.path).st_ino,before)
self.assertEqual((self.root/'audit').read_text(),'')
def test_distinct_state_cannot_steal_socket(self):
a=AlertSocket(str(self.root/'sock'));a.bind();self.addCleanup(a.close)
b=AlertSocket(a.path)
with self.assertRaises(OSError):b.bind()
self.assertTrue(Path(a.path).exists())
def test_unmanaged_active_listener_preserved(self):
path=str(self.root/'sock')
with socket.socket(socket.AF_UNIX) as s:
s.bind(path);s.listen()
with self.assertRaises(OSError):AlertSocket(path).bind()
self.assertTrue(Path(path).exists())
def test_non_socket_path_preserved(self):
p=self.root/'sock';p.write_text('preserve')
with self.assertRaises(OSError):AlertSocket(str(p)).bind()
self.assertEqual(p.read_text(),'preserve')
def test_shutdown_persists_accepted_queue(self):
c=self.controller();c._sock._enqueue(json.dumps(self.event()).encode())
c.close()
from leaf_controller.state import State
state=State(str(self.root/'state'))
try:self.assertIsNotNone(state.get('192.0.2.202'))
finally:state.close()
def test_oversized_and_recursive_frames_do_not_kill_reader(self):
a=AlertSocket(str(self.root/'sock'));a.bind();a.start();self.addCleanup(a.close)
with socket.socket(socket.AF_UNIX) as s:
s.connect(a.path)
s.sendall(b'x'*(MAX_RECORD+65536)+b'\n'+b'['*2000+b']'*2000+b'\n'+
json.dumps(self.event()).encode()+b'\n')
self.assertTrue(a.available.wait(3))
self.assertGreaterEqual(a.counts['parse_errors'],1)
self.assertEqual(a.counts['parse_errors']+a.counts['other'],2)
self.assertEqual(len(a.drain()),1)
self.assertTrue(a._thread.is_alive())
def test_partial_eof_counted(self):
a=AlertSocket(str(self.root/'sock'));a.bind();a.start();self.addCleanup(a.close)
with socket.socket(socket.AF_UNIX) as s:s.connect(a.path);s.sendall(b'{')
end=time.monotonic()+2
while a.counts['parse_errors']==0 and time.monotonic()<end:time.sleep(.01)
self.assertEqual(a.counts['parse_errors'],1)
def test_checkpoint_does_not_skip_unread_batch(self):
p=self.root/'eve';p.write_text('{"n":1}\n{"n":2}\n{"n":3}\n')
t=EveTailer(str(p),from_start=True);g=t.events()
self.assertEqual(next(g),{'n':1});ck=(*t._ino,t._pos);g.close()
self.assertEqual(ck[2],len('{"n":1}\n'))
t=EveTailer(str(p),checkpoint=ck);g=t.events()
self.assertEqual(next(g),{'n':2});g.close()
def test_replayed_file_hit_does_not_inflate_threshold(self):
c=self.controller();c.cfg.raw['policy'].update(mode='threshold',min_hits=2)
c.state._local.event_key='1:2:10'
c.handle_event(self.event());c.handle_event(self.event())
self.assertIsNone(c.state.get('192.0.2.202'))
c.state._local.event_key='1:2:20';c.handle_event(self.event())
self.assertIsNotNone(c.state.get('192.0.2.202'))
def test_failed_save_retried_after_membership_already_matches(self):
c=self.controller();c.cfg.raw['save_config']=True;c.handle_event(self.event())
c.client.save_config=Mock(side_effect=[RuntimeError('save failed'),None])
with self.assertRaises(RuntimeError):c.sync_router_state()
self.assertTrue(c.state.router_dirty())
c.sync_router_state()
self.assertEqual(c.client.save_config.call_count,2)
self.assertEqual(len(c.client.commits),1)
self.assertFalse(c.state.router_dirty())
def test_audit_keeps_latest_in_rapid_rotation(self):
p=self.root/'log';a=Audit(str(p),max_bytes=1,keep=3)
for i in range(20):a.write({'i':i})
a.close()
rows=[json.loads(f.read_text())['i'] for f in self.root.glob('log.*')]
self.assertEqual(sorted(rows),[17,18,19])
def test_tls_pins_do_not_mutate_global_or_other_clients(self):
from urllib3.poolmanager import pool_classes_by_scheme
before=dict(pool_classes_by_scheme)
a=VyosClient('https://localhost','x',cert_pin='a'*64)
b=VyosClient('https://localhost','x',cert_pin='b'*64)
self.assertEqual(pool_classes_by_scheme,before)
self.assertFalse(a.sess.trust_env)
self.assertEqual(a.sess.adapters['https://'].poolmanager.pool_classes_by_scheme['https'].ConnectionCls.leaf_pin,'a'*64)
self.assertEqual(b.sess.adapters['https://'].poolmanager.pool_classes_by_scheme['https'].ConnectionCls.leaf_pin,'b'*64)
def test_rotation_reopens_and_keeps_newest(self):
p=self.root/'eve';p.write_text('first\n');calls=[]
for i in range(9):
p.write_text(str(i))
retention.rotate(p,max_bytes=1,keep=3,reopen=lambda:(calls.append(1),p.write_text('')))
self.assertEqual(len(calls),9)
self.assertEqual(sorted(int(f.read_text()) for f in self.root.glob('eve.leaf-*')),[6,7,8])
def test_rotation_reopen_failure_restores_file(self):
p=self.root/'eve';p.write_text('original')
with self.assertRaises(RuntimeError):
retention.rotate(p,max_bytes=1,reopen=Mock(side_effect=RuntimeError()))
self.assertEqual(p.read_text(),'original')
def test_env_quotes_are_parsed_without_evaluation(self):
p=self.root/'env';p.write_text("LEAF_VYOS_KEY='abc123'\n")
self.assertEqual(read_key_env(p),'abc123')
def test_invalid_queue_and_ttl_rejected(self):
p=self.root/'config'
for value in ('alert_socket: {queue_size: 0}', 'policy: {ttl_seconds: -1}', 'policy: {min_hits: 1.5}'):
p.write_text(value)
with self.assertRaises(ValueError):load_config(p)
def test_key_rotation_preserves_other_app_ids(self):
old=Mock();new=Mock();old.retrieve.return_value={'data':{'id':{'leaf':{'key':'old'},'other':{'key':'unrelated'}}}}
with patch.object(rotation,'wait_auth'),patch.object(rotation,'atomic_env'),patch.object(rotation,'restart_service'):
rotation.rotate(old,new,'leaf','leaf-new','old','new','LEAF_VYOS_KEY=old\n','IDS-BLOCK')
self.assertEqual(new.configure.call_args.args[0]['path'],rotation.KEYS_PATH+['leaf'])
self.assertEqual(new.configure.call_count,1)
def test_key_rotation_restart_failure_rolls_back(self):
old=Mock();new=Mock();old.retrieve.return_value={'data':{'id':{'leaf':{'key':'old'}}}}
with patch.object(rotation,'wait_auth'),patch.object(rotation,'atomic_env') as write,patch.object(rotation,'restart_service',side_effect=[RuntimeError('failed'),None]):
with self.assertRaises(RuntimeError):rotation.rotate(old,new,'leaf','new-id','old','new','LEAF_VYOS_KEY=old\n','IDS-BLOCK')
self.assertEqual(write.call_args.args[0],'LEAF_VYOS_KEY=old\n')
self.assertEqual(old.configure.call_args.args[0]['path'],rotation.KEYS_PATH+['new-id'])
new.configure.assert_not_called()
def test_key_rotation_refuses_nonmatching_id(self):
old=Mock();old.retrieve.return_value={'data':{'id':{'other':{'key':'different'}}}}
with self.assertRaises(RuntimeError):rotation.rotate(old,Mock(),'other','new','old','new','text','group')
old.configure.assert_not_called()
def test_live_injector_uses_resolved_ethernet_addresses(self):
fake=Mock();fake.__enter__=Mock(return_value=fake);fake.__exit__=Mock(return_value=False)
with patch.object(sys,'argv',['injector','syn','--src','203.0.113.12','--dst','192.0.2.201','--count','1','--interval','0']),patch.object(injector,'route_via',return_value=('10.0.249.0','eth1')),patch.object(Path,'read_text',return_value='11:22:33:44:55:66'),patch.object(injector,'resolve_gateway_mac',return_value=bytes.fromhex('665544332211')),patch.object(injector.socket,'socket',return_value=fake):
injector.main()
self.assertEqual(fake.send.call_args.args[0][:12],bytes.fromhex('665544332211112233445566'))
def test_hourly_rotation_clock_survives_continuous_writes(self):
p=self.root/'eve';p.write_text('one')
self.assertFalse(retention.rotate(p,max_bytes=999999,now=100,reopen=lambda:None))
p.write_text('two')
self.assertTrue(retention.rotate(p,max_bytes=999999,now=3701,reopen=lambda:p.write_text('')))
def test_rotation_skips_engine_startup(self):
with patch.object(sys,'argv',['rotate-eve']),patch.object(retention.subprocess,'run',return_value=Mock(stdout='100000000')),patch.object(retention.time,'monotonic',return_value=101),patch.object(retention,'rotate') as r:
retention.main()
r.assert_not_called()
def test_diagnostics_redact_nested_credentials(self):
from leaf_controller.ops import redact
result=redact({'service':{'api':{'keys':{'id':{'leaf':{'key':'secret'}}}}},
'password':'secret', 'interfaces':{'eth1':{'address':['10.0.249.1/31']}}})
self.assertNotIn('secret',json.dumps(result))
self.assertEqual(result['interfaces']['eth1']['address'],['10.0.249.1/31'])
def test_file_identity_can_count_both_candidate_targets(self):
c=self.controller();c.cfg.raw['policy'].update(mode='threshold',min_hits=2)
c.state._local.event_key='one-file-record'
event=self.event();event['alert']['metadata']['leaf_action']=['block','block_src']
c.handle_event(event)
self.assertEqual(c.state.hit_count(1000001,'192.0.2.202',300),1)
self.assertEqual(c.state.hit_count(1000001,'203.0.113.12',300),1)
def test_malformed_stats_does_not_poison_following_alerts(self):
c=self.controller()
for stats in ({'capture':[1]}, {'uptime':'bad'}, {'uptime':float('inf')}):
c._route({'event_type':'stats','stats':stats})
c._route(self.event())
self.assertIsNotNone(c.state.get('192.0.2.202'))
def test_nonfinite_signature_does_not_stop_processing(self):
c=self.controller();bad=self.event();bad['alert']['signature_id']=float('inf')
c.handle_event(bad);c.handle_event(self.event())
self.assertIsNotNone(c.state.get('192.0.2.202'))