patlegu/opnsense-agent

🛡️ OPNsense Agent Model (LorA V7)

A specialized language model for managing OPNsense Firewalls via function calling.

This model is a fine-tune of Mistral-7B-Instruct-v0.3 designed to translate natural language user requests into valid OPNsense API calls (JSON). It is intended to be the "brain" of an autonomous security agent (e.g., using CrewAI or LangChain).

DISCLAIMER
Do not use this in production. This is a first version that still needs a lot of work to be truly finalized.

---

🚀 Key Features

• 100% Valid JSON Output: Rigorously trained to output only valid JSON tool calls.
• Full API Coverage: Supports 36 core OPNsense functions (Firewall rules, Aliases, NAT, System internals).
• Deterministic: Version V7 was trained on a deterministic dataset to ensure strict adherence to user-provided arguments (IPs, ports, etc.).
• GGUF Ready: Optimized for local inference with Ollama (Quantized Q4_K_M).

---

📦 Usage with Ollama

Run this model locally with Ollama to interact with your firewall using natural language.

1. Pull the Model

ollama run hf.co/patlegu/opnsense-agent

2. Interactive Mode

Note: The model generates the JSON command but does not execute it directly. You need an agent script to execute the output.

>>> Block traffic from IP 192.168.1.50 on WAN interface

# Output:
{
  "tool_calls": [
    {
      "name": "add_filter_rule",
      "arguments": {
        "action": "block",
        "interface": "wan",
        "protocol": "any",
        "source": "192.168.1.50",
        "description": "Block traffic from 192.168.1.50"
      }
    }
  ]
}

3. Create Custom Modelfile (Recommended)

To prevent hallucinations and strictly enforce the OPNsense schema, use the provided Modelfile (available in this repository).

# 1. Download the Modelfile
wget https://huggingface.co/patlegu/opnsense-agent/raw/main/Modelfile

# 2. Create the custom agent model
ollama create opnsense-agent -f Modelfile

# 3. Run the agent
ollama run opnsense-agent

4. Test with Example Prompts

We provide a comprehensive list of test scenarios in ollama_test_prompts.txt covering:

• 🛡️ Firewall Rules (Block/Allow IPs, Ports)
• 🏷️ Aliases (Create, Add to, List)
• 🌐 NAT (Port Forwarding, Outbound)
• 🔧 System Admin (Apply changes, Logs, States)

Example Test:

>>> Block traffic from 192.168.1.50 on WAN interface

See ollama_test_prompts.txt for 12+ ready-to-use scenarios.

---

🐍 Usage with Python (CrewAI / LangChain)

This model shines when integrated into an agent workflow.

from crewai import Agent, Task
from langchain_openai import ChatOpenAI

# 1. Connect to local Ollama
opnsense_llm = ChatOpenAI(
    model="ollama/opnsense-agent",
    base_url="http://localhost:11434/v1",
    api_key="NA"
)

# 2. Define the Agent
firewall_admin = Agent(
    role='Firewall Admin',
    goal='Secure the network',
    backstory='Expert admin managing OPNsense via API.',
    llm=opnsense_llm,
    tools=[add_filter_rule_tool, add_alias_tool],  # Your actual Python functions
    verbose=True
)

# 3. Execute Task
task = Task(
    description="Block the attacker IP 203.0.113.66 immediately",
    agent=firewall_admin
)

---

📊 Performance (V7)

The model was evaluated on a held-out test set of 50 complex scenarios.

Metric	Score	Note
Function Selection	100%	Always chooses the correct API endpoint
Argument Accuracy	100%	Perfect extraction of IPs, ports, and enums
JSON Validity	100%	No syntax errors

(Evaluation date: Jan 2026)

---

🛠️ Supported Functions

The model understands the following 36 functions:

• Firewall: add_filter_rule, delete_filter_rule, get_filter_rule, toggle_filter_rule, set_filter_rule
• Aliases: add_alias, add_to_alias, delete_alias, delete_from_alias, get_alias, list_alias_content, set_alias, find_alias_references, flush_alias
• NAT: add_nat_port_forward, add_nat_outbound, add_nat_one_to_one, delete_nat_outbound, delete_nat_one_to_one
• States: get_firewall_states, kill_firewall_states, flush_firewall_states, get_state_summary (inferred)
• System/Diagnostics: apply_firewall_changes, revert_firewall_changes, create_firewall_savepoint, cancel_firewall_rollback, get_firewall_log, get_firewall_statistics, get_rule_statistics, get_interface_list
• Categories/GeoIP: add_category, delete_category, list_categories, get_geoip_database, list_geoip_countries, update_bogons

---

⚖️ License

Apache 2.0. Based on Mistral-7B-Instruct-v0.3.