Design Philosophy

​

Via Appia Quality

​

Core Tenets

​

What This Means in Practice

• Would this code survive a 10-year maintenance gap?
• Can a new developer understand it in 6 months?
• Will this architecture scale to 100x traffic?

• Known limitations section in every component README
• Actual test results (not cherry-picked)
• Post-mortems for all incidents

• Compatibility over novelty
• Standard protocols over custom formats
• Graceful degradation over fail-fast

​

Scientific Honesty

​

Real Metrics, Not Marketing

• 97.6% accuracy on CTU-13 Neris botnet (real ransomware dataset)
• 17 hours continuous operation without crashes
• 36,000 events tested with 0 crypto errors
• 364 events/sec peak throughput (stress test)
• IPSet capacity limit hit at ~1,000 IPs (documented limitation)

• “99.9% accuracy” (no dataset specified)
• “Millions of events/sec” (unrealistic without hardware details)
• “Enterprise-scale” (without defining scale)
• “AI-powered” (without describing the models)

​

Transparent Limitations

Known Limitations (Day 52):
- IPSet capacity finite (max realistic: 500K IPs)
- No persistence layer yet (evicted IPs lost on restart)
- Single-node deployment (no HA/failover)
- Manual capacity management required

Does NOT Protect Against:
- Zero-day exploits (no signature-based detection)
- Encrypted malware payloads (TLS/SSL content is opaque)
- Insider threats (no authentication/authorization layer)
- Physical attacks (out of scope)

​

Reproducible Results

1. Hardware specs: CPU cores, RAM, network
2. Test methodology: Synthetic vs organic, duration, load profile
3. Raw data: Logs, screenshots, packet captures
4. Scripts: Reproducible test harnesses in /scripts/

# Exact test configuration
Vagrant VM: Debian 12, 6 CPU, 8GB RAM
Kernel: 6.1.0
Test script: /vagrant/scripts/stress_test_8h.sh
Dataset: Mixed synthetic + organic traffic
Duration: 17h 2m 10s (61,343 seconds)
Results: /vagrant/logs/stress_test_20251120_101056/

​

Collaborative AI Development

​

”Consejo de Sabios” (Council of Wise Ones)

​

AI Co-Authors

• Architecture design
• Code review and debugging
• Documentation synthesis
• Integration work across components

• Algorithm optimization
• Performance profiling
• Debugging race conditions
• Vagrantfile automation

• XDP/eBPF expertise
• Performance analysis
• Chaos testing (chaos_monkey.sh)
• Gateway mode validation

• Research assistance
• Literature review
• Hospital stress test specs
• Dataset recommendations

• Documentation review
• Routing verification (rp_filter edge case)
• Configuration validation
• Multi-language support (Spanish)

​

Why This Matters

• Reproducibility - Others can use same AI workflow
• Academic honesty - No hidden AI contributions
• Methodology transparency - Peer reviewers understand development process

• Trust - Nothing hidden about how code was developed
• Quality - Multiple AI perspectives catch more bugs
• Education - Learn how to collaborate with AI effectively

​

Example: Git Commit Attribution

# Good commit message
feat(firewall): Add IPSet capacity monitoring

Implemented circuit breaker pattern to prevent queue overflow
when IPSet reaches capacity. Graceful degradation logs warnings
but continues processing.

Co-authored-by: Claude (Anthropic)
Co-authored-by: DeepSeek
Validated-by: Grok (xAI)

# Bad commit message
feat: add monitoring
# (Who wrote this? What does it monitor? Any AI help?)

​

User Privacy & Accessibility

​

No Telemetry, Ever

• ❌ Phone home with usage statistics
• ❌ Send crash reports to external servers
• ❌ Track user behavior
• ❌ Require registration or license keys
• ❌ Upload threat data to cloud

• ✅ Keep all data on user infrastructure
• ✅ Use standard syslog/file logging
• ✅ Allow users to delete logs anytime
• ✅ Support air-gapped deployments
• ✅ Open source for auditability

​

Accessibility

• Natural language explanations, not just technical jargon
• Examples before theory
• Troubleshooting guides with actual error messages
• “Why” before “How” in architecture docs

Instead of: "Execute vector similarity search with FAISS IVF index"
We say:     "Ask in plain language: '¿Qué ha ocurrido en las últimas 24h?'"

• Single-node deployment (small organizations)
• Raspberry Pi compatible (low-budget schools)
• Multi-node clustering (enterprises)
• Docker/Kubernetes (cloud-native)

​

Design Principles

​

1. Config-Driven Architecture

const std::string log_path = "/var/log/firewall.log";
const int batch_size = 100;
const std::string ipset_name = "ml_defender_blacklist";

const auto log_path = config["logging"]["file"].asString();
const auto batch_size = config["batch_processor"]["batch_size"].asInt();
const auto ipset_name = config["ipsets"]["blacklist_test"]["name"].asString();

• Change behavior without recompilation
• A/B testing via config changes
• Multi-environment deployment (dev/staging/prod)
• Clear documentation of all tunables

​

2. Graceful Degradation

• 4 FAISS indices (Chronos, SBERT, Entity Benign, Entity Malicious)
• If 1 index fails → Continue with 3 indices
• Circuit breaker prevents cascade failures
• Health monitoring tracks coefficient of variation (CV)

• IPSet capacity exceeded → Log warnings, continue processing
• Crypto error on 1 message → Skip message, continue with next
• etcd unavailable → Use cached config, retry with exponential backoff

​

3. Observability First

• Structured logs (JSON format)
• Metrics (packets processed, errors, latency)
• Health checks (for orchestration)
• Performance stats (every 30 seconds)

=== ESTADÍSTICAS ===
Paquetes procesados: 2080549
Paquetes enviados: 0
Tiempo activo: 61343 segundos
Tasa: 33.92 eventos/seg
Payloads sospechosos: 1550375
===================

• Prometheus metrics exporter
• Grafana dashboards
• Alert manager integration
• Distributed tracing (OpenTelemetry)

​

4. Testing as First-Class Citizen

1. Unit Tests (fast, isolated)
   • 25+ tests for sniffer components
   • Test coverage >80% for core logic
2. Integration Tests (realistic, end-to-end)
   • Full pipeline tests (sniffer → ml → firewall)
   • Crypto pipeline validation
3. Stress Tests (production-like load)
   • 36,000 events across 4 progressive tests
   • 17-hour stability test
4. Chaos Tests (failure scenarios)
   • Component crashes
   • Network partitions
   • Resource exhaustion

• Passing unit tests
• Integration test coverage
• Performance benchmarks (no regressions)

​

5. Via Appia Refactoring

• Not for style (unless affecting readability)
• Not for novelty (latest C++ features)
• Only for:
  • Eliminating hardcoded values
  • Fixing architectural debt
  • Improving observability
  • Reducing coupling

Problem: Hardcoded logger paths, duplicate config, IPSet singleton
Solution: 
  - Logger path from config.logging.file
  - IPSet names from config.ipsets map
  - Removed BatchProcessor struct defaults
  - Single source of truth (JSON)

​

Mission: Democratizing Cybersecurity

​

The Problem

• Ransomware attacks (average: $4.5M per incident)
• Expensive commercial security products ($50K-$500K/year)
• Lack of in-house security expertise
• Compliance requirements (HIPAA, FERPA)

• Enterprise-grade protection
• Affordable (ideally free/open source)
• Easy to deploy and maintain
• Transparent (no black boxes)

​

Our Solution

• ✅ Open source (MIT license)
• ✅ Production-ready (36K events tested)
• ✅ Self-hosted (no cloud dependencies)
• ✅ Documented honestly (real metrics)
• ✅ Raspberry Pi compatible (~$100 hardware)

1. Small Hospital (50-200 beds)
   • Single-node deployment
   • Protects electronic health records (EHR)
   • Blocks ransomware C&C communication
   • Cost: $500 hardware + IT staff time
2. School District (5,000 students)
   • Gateway mode deployment
   • Protects entire network
   • Parental transparency (no student tracking)
   • Cost: $2,000 hardware + IT staff time
3. Non-Profit (Remote clinic)
   • Raspberry Pi deployment
   • Offline operation (no Internet required)
   • Low power consumption
   • Cost: $100 hardware + volunteer time

​

Academic Integrity

​

For Research Papers

1. AI Collaboration Disclosure:
   This work was developed in collaboration with multiple AI systems
   (Claude, DeepSeek, Grok, ChatGPT, Qwen). All AI contributions are
   explicitly credited in code comments and commit history.
   
2. Methodology Transparency:
   • Disclose which components were AI-assisted
   • Document human review process
   • Provide reproducible test harnesses
3. Dataset Attribution:
   • CTU-13 dataset (Czech Technical University)
   • MAWI dataset (WIDE Project)
   • Synthetic traffic (custom generator, open sourced)
4. Code Availability:
   • GitHub repository link
   • Docker images for reproducibility
   • VM images (Vagrant) for exact environment

​

For Academic Use

• Use ML Defender in thesis/dissertation work
• Extend components for research projects
• Benchmark against other IDS systems
• Publish comparative analyses

• Cite the project with AI co-author disclosure
• Share improvements back (via PRs)
• Document limitations honestly
• Use real metrics (not cherry-picked results)

​

Future Vision

​

5-Year Roadmap

• Production-ready core (sniffer, ml-detector, firewall)
• 97.6% accuracy on ransomware
• Single-node deployment validated

• Multi-node clustering
• Kubernetes deployment
• Prometheus/Grafana observability
• 10+ hospital pilots

• Federated learning (privacy-preserving model updates)
• Community threat intel sharing
• 100+ production deployments
• Published research papers

• Hardware appliance (turnkey deployment)
• Professional support offering
• Certification programs (training)
• International deployments

• Standard reference architecture (NIST)
• Integration with major EHR systems
• 1,000+ deployments
• Self-sustaining community

​

Contributing to Via Appia Quality

​

How You Can Help

• Follow existing patterns (config-driven, graceful degradation)
• Include tests (unit + integration)
• Document limitations honestly
• Disclose AI assistance (if any)

• Natural language for accessibility
• Real examples from production
• Troubleshooting guides
• Translations (Spanish, others)

• Deploy in your environment
• Report actual performance metrics
• Share failure scenarios
• Contribute test datasets

• Help others on GitHub Discussions
• Write blog posts about deployments
• Present at conferences
• Mentor students

​

Contribution Guidelines