patlegu/opnsense-agent-phi35

OPNsense Agent — Phi-3.5-mini LoRA

Fine-tune de microsoft/Phi-3.5-mini-instruct entraîné pour agir comme agent-outil OPNsense dans une architecture multi-agents.

L'agent reçoit des paquets CAP v1 (Coordinator-Agent Packet) depuis un coordinateur et génère des tool_calls précis vers l'API OPNsense/pfSense.

---

Architecture

Coordinateur (LLM)
      │  CAP v1 JSON : {"directive": "block_ip", "entities": {"IP_ADDRESS": ["10.0.0.1"]}, "args": {}, "context": {}}
      ▼
Agent OPNsense (ce modèle)
      │  tool_call : {"name": "block_ip", "arguments": {"ip": "10.0.0.1"}}
      ▼
API OPNsense / pfSense

L'agent ne reçoit jamais de langage naturel humain — uniquement des paquets JSON structurés.

---

Fonctions supportées (69 au total)

Domaine	Fonctions
Règles firewall	add_filter_rule, del_filter_rule, set_filter_rule, get_filter_rule, toggle_filter_rule, move_filter_rule
Alias	add_alias, del_alias, set_alias, get_alias, add_to_alias, del_from_alias, flush_alias, list_alias_content, find_alias_references, import_alias
NAT	add_nat_outbound, del_nat_outbound, add_nat_port_forward, add_nat_one_to_one, del_nat_one_to_one
Diagnostics	get_firewall_log, get_firewall_states, kill_firewall_states, flush_firewall_states, get_firewall_statistics, get_rule_statistics, get_system_status, ping_host, traceroute_host, port_probe
Configuration	apply_firewall_changes, cancel_firewall_rollback, revert_firewall_changes, create_firewall_savepoint, get_interface_list, backup_configuration, list_restore_points, revert_to_restore_point, create_restore_point
DNS / DHCP	add_dns_override, list_dns_overrides, del_dns_override, manage_dns_blocklist, search_dns_queries, get_dhcp_leases, add_static_mapping
IDS (Suricata)	get_ids_status, query_ids_alerts, toggle_ids_rule
Monit	get_monit_status, restart_monit_service
Cron	schedule_cron_job, toggle_cron_job, get_cron_jobs
Routage	get_static_routes, add_static_route, del_static_route
GeoIP / Firmware	list_geoip_countries, get_geoip_database, check_updates, get_upgrade_status, upgrade_firmware
Legacy	block_ip, unblock_ip

---

Performance

Benchmark	Score
verify_opnsense_v2.py — format CAP v1 (production)	69/69 — 100%
verify_opnsense.py — format NL (référence historique)	63/69 — 91%

---

Utilisation avec Ollama

ollama run hf.co/patlegu/opnsense-agent-phi35

Exemple d'appel CAP v1 :

import ollama, json

cap_packet = json.dumps({
    "directive": "block_ip",
    "entities": {"IP_ADDRESS": ["203.0.113.42"], "INTERFACE": ["wan"],
                  "PORT_NUMBER": [], "HOSTNAME": [], "IP_SUBNET": []},
    "args": {},
    "context": {"source": "coordinator", "confidence": 0.97}
})

response = ollama.chat(
    model="hf.co/patlegu/opnsense-agent-phi35",
    messages=[{"role": "user", "content": cap_packet}]
)
print(response["message"]["content"])
# → tool_call : block_ip({"ip": "203.0.113.42", "interface": "wan"})

---

Utilisation avec cyber-agent-engine

curl -X POST http://localhost:3000/agent/execute \
  -H "Content-Type: application/json" \
  -d '{"agent": "opnsense", "command": "{CAP_V1_JSON}"}'

---

Détails d'entraînement

Paramètre	Valeur
Base model	microsoft/Phi-3.5-mini-instruct
LoRA rank / alpha	64 / 128
Dataset	12782 exemples (format CAP v1)
Epochs	3
Learning rate	2e-4 (cosine)
Final loss	0.2806
Date	2026-03-05
Framework	Unsloth + HuggingFace TRL

---

Limitations

• Conçu pour être appelé par un coordinateur, pas directement par un humain
• Requiert le format CAP v1 — les requêtes en langage naturel libre donnent des résultats dégradés
• Testé uniquement sur OPNsense — compatibilité pfSense partielle (API similaire)

---

Licence

Apache 2.0 — voir LICENSE