Project Description
swarm-oversight is a multi-agent spending monitor that detects coordinated attack patterns when multiple autonomous agents each stay under their individual spending limits while collectively exceeding swarm-level caps. The monitor identifies split payments, relay attacks, and payee alias evasion patterns in action logs.
What it Does
- split_payment: Detects when multiple agents pay the same payee in a short window, collectively exceeding the per-payee cap (60,000 cents)
- relay: Traces money transfers through multiple hops back to the origin agent where spend + transferred amounts exceed limits
- split_alias: Catches agents using slightly different payee names via normalized matching (85% similarity threshold with SequenceMatcher)
- relay_two_hop: Detects a → b → c transfer chains
- split_wide: Detects split payments spaced wider than the monitor's window
Key capabilities:
- 100% recall across all attack scenarios with 200 seeded runs
- 0% false alarm rate on benign runs
- Standard-library only (no model dependencies), scores fully reproducible from seed
- Dual-window detection (10-tick fast + 60-tick slow split detection)
- Origin tracing through transfer chains
Challenges & Solutions
| Challenge | Solution |
|---|---|
| Relay detection across multiple hops | upstream tracking traces money to origin agent |
| Payee name evasion | Fuzzy matching with prefix + SequenceMatcher ratio ≥ 0.85 |
| Split payments spread over wide windows | Dual windows: 10-tick + 60-tick slow_split |
| Naive attacks beaten, clever ones slipping through | Scenario generation includes split_wide, relay_two_hop, split_alias variants |
| Short 10-tick window missing delayed splits | Added long_window (60 ticks) for broader detection |
Accomplishments
- ✅ 100% recall on all attack scenarios (split_payment, relay, split_wide, relay_two_hop, split_alias)
- ✅ 0% false alarms on benign runs across 200 seeds
- ✅ Standard-library only — deterministic, reproducible, no API keys needed
- ✅ Effective relay tracing — money transferred through multiple hops correctly attributed to origin
- ✅ Payee alias detection — near-identical names normalized and merged
Metrics (200 seeds)
| Scenario | Recall | False Alarm | Mean Latency |
|---|---|---|---|
| benign | 0.00 | 0.00 | N/A |
| split_payment | 1.00 | 0.00 | — |
| relay | 1.00 | 0.00 | — |
| split_wide | 1.00 | 0.00 | — |
| relay_two_hop | 1.00 | 0.00 | — |
| split_alias | 1.00 | 0.00 | — |
Installation
pip install -e .[dev]
pytest # Run test suite
python -m swarm_oversight.harness --seeds 200 # Full scoring
Built With
- argparse
- client-credentials-auth
- dataclasses
- defaultdict
- deterministic-testing
- difflib-(sequencematcher)
- docker
- docker-compose
- fastapi
- fraud-detection
- httpx
- in-process-session
- json
- multi-agent-systems
- oauth2
- payee-alias-normalization
- paypal
- pytest
- python
- random
- relay-attack-detection
- seeded-scenarios
- spending-monitoring
- split-payment-detection
- standard-library-only
