gandalf/secubox-openwrt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
21a8f06058
secubox-openwrt/package/secubox/secubox-mcp-server
History
…
..
files
Makefile
README.md

README.md

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