secubox-openwrt/package/secubox/secubox-mcp-server

SecuBox MCP Server

Model Context Protocol (MCP) server for SecuBox. Exposes device security data to AI assistants (Claude Desktop, Cursor, VS Code) via JSON-RPC 2.0 over stdio.

Version: 1.0.0

Overview

MCP (Model Context Protocol) is an open protocol by Anthropic that allows AI assistants to access local data sources. This server provides SecuBox security data to AI tools for:

• Real-time threat intelligence analysis
• CVE vulnerability lookups with mitigation advice
• WAF filter rule suggestions
• Security posture assessments
• Network and system monitoring

Installation

opkg install secubox-mcp-server

Available Tools

Security Tools

Tool	Description
crowdsec.alerts	Get active CrowdSec security alerts
crowdsec.decisions	Get active blocking decisions
waf.logs	Get WAF threat events from mitmproxy

Network Tools

Tool	Description
network.flows	Get network traffic summary
wireguard.status	Get VPN tunnel status
dns.queries	Get DNS query statistics

System Tools

Tool	Description
system.metrics	Get CPU, memory, disk, temperature
uci.get	Read OpenWrt UCI configuration
uci.set	Write UCI configuration (disabled by default)

AI-Powered Tools (Requires LocalAI)

Tool	Description
ai.analyze_threats	AI analysis of CrowdSec alerts with recommendations
ai.cve_lookup	CVE vulnerability analysis and mitigation advice
ai.suggest_waf_rules	AI-suggested mitmproxy/WAF filter patterns
ai.explain_ban	Explain why an IP was banned
ai.security_posture	Security posture assessment

Claude Desktop Integration

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "secubox": {
      "command": "ssh",
      "args": ["root@192.168.255.1", "/usr/bin/secubox-mcp"]
    }
  }
}

Then restart Claude Desktop. Ask questions like:

• "What are the current security threats on my router?"
• "Analyze CVE-2024-1234 and suggest mitigations"
• "What's my network traffic summary?"
• "Suggest WAF rules based on recent attacks"

Configuration

UCI config: /etc/config/mcp-server

config mcp-server 'main'
    option enabled '1'

    # Tool whitelist - only these tools can be invoked
    list allowed_tool 'crowdsec.alerts'
    list allowed_tool 'crowdsec.decisions'
    list allowed_tool 'waf.logs'
    list allowed_tool 'dns.queries'
    list allowed_tool 'network.flows'
    list allowed_tool 'system.metrics'
    list allowed_tool 'wireguard.status'
    list allowed_tool 'uci.get'
    # list allowed_tool 'uci.set'  # Disabled by default

    # AI tools (require LocalAI)
    list allowed_tool 'ai.analyze_threats'
    list allowed_tool 'ai.cve_lookup'
    list allowed_tool 'ai.suggest_waf_rules'
    list allowed_tool 'ai.explain_ban'
    list allowed_tool 'ai.security_posture'

    # Data classification for sovereignty
    option classification 'local_only'

Enable/Disable Tools

# Enable uci.set (careful - allows config changes)
uci add_list mcp-server.main.allowed_tool='uci.set'
uci commit mcp-server

# Disable a tool
uci del_list mcp-server.main.allowed_tool='ai.security_posture'
uci commit mcp-server

Testing

Test Protocol Locally

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | /usr/bin/secubox-mcp

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /usr/bin/secubox-mcp

# Call a tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"system.metrics","arguments":{}}}' | /usr/bin/secubox-mcp

Test via SSH

ssh root@192.168.255.1 '/usr/bin/secubox-mcp' <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"crowdsec.alerts","arguments":{"limit":10}}}
EOF

LocalAI Integration

The AI-powered tools require LocalAI running on the device:

# Install and start LocalAI
opkg install secubox-app-localai
localaictl install
localaictl model-install tinyllama
uci set localai.main.enabled=1
uci commit localai
/etc/init.d/localai start

AI tools will automatically use LocalAI at http://127.0.0.1:8081 for analysis.

Security Considerations

1. Tool Whitelist: Only tools listed in UCI config can be invoked
2. uci.set Disabled: Write access disabled by default
3. Sensitive Data Blocked: uci.get blocks password/secret/key fields
4. SSH Required: MCP runs over SSH - requires key authentication
5. Data Classification: All data marked LOCAL_ONLY by default
6. No Cloud Escalation: Server runs entirely on device

Files

File	Description
/usr/bin/secubox-mcp	Main MCP server
/usr/lib/secubox-mcp/protocol.sh	JSON-RPC protocol handler
/usr/lib/secubox-mcp/tools/*.sh	Tool implementations
/etc/config/mcp-server	UCI configuration

Dependencies

• jsonfilter — JSON parsing (OpenWrt native)
• cscli — CrowdSec CLI (for crowdsec tools)
• wg — WireGuard tools (for wireguard tools)
• secubox-app-localai — LocalAI (for AI tools)

Protocol

MCP uses JSON-RPC 2.0 over stdio:

• Transport: stdin/stdout
• Protocol Version: 2024-11-05
• Methods: initialize, tools/list, tools/call, ping

License

MIT

References

• Model Context Protocol Spec
• Claude Desktop MCP Guide
• SecuBox Documentation