protocol-participation

name	protocol-participation
description	Live BGP and OSPF control-plane participation — peer with real routers, inject/withdraw routes, query RIB/LSDB, adjust metrics, GRE tunnel status. Use when injecting or withdrawing BGP routes, checking BGP peer state, querying the OSPF LSDB, or testing route advertisement in a lab.
license	Apache-2.0
user-invocable	true
metadata	{"openclaw":{"requires":{"bins":"[Truncated]","env":"[Truncated]"}}}

Protocol Participation — BGP + OSPF + GRE

MCP Server

Property	Value
Source	WontYouBeMyNeighbour BGP/OSPFv3/GRE modules
Transport	stdio
Tools	10
Protocol modules	BGP (20 files), OSPFv3 (8 files), GRE (4 files), Connectors (2 files)
Dependencies	scapy, networkx, mcp, fastmcp

Tools

BGP Tools

bgp_get_peers

List BGP peer sessions with state, AS, IP, uptime, and prefix counts.

Parameter	Type	Default	Description
(none)	—	—	No parameters

Returns: { peers: [{peer, peer_as, state, local_addr, is_ibgp, uptime, prefixes_received, prefixes_sent}], count }

bgp_get_rib

Query the Loc-RIB (best routes). Optionally filter by prefix.

Parameter	Type	Default	Description
prefix	string	null	Optional CIDR filter (e.g. 10.0.0.0/24)

Returns: { routes: [{network, next_hop, as_path, local_pref, med, origin, communities}], count }

bgp_inject_route

Inject a route into the BGP RIB and advertise to peers.

Parameter	Type	Default	Description
network	string	required	CIDR prefix (e.g. 192.168.1.0/24)
next_hop	string	null	Next-hop IP (defaults to self)
as_path	string	null	Comma-separated AS path (e.g. 65001,65002)
local_pref	int	100	LOCAL_PREF value

Returns: { success, network, route_info }

bgp_withdraw_route

Withdraw a route from the BGP RIB and send withdrawal to peers.

Parameter	Type	Default	Description
network	string	required	CIDR prefix to withdraw

Returns: { success, network }

bgp_adjust_local_pref

Change the LOCAL_PREF for a route in the RIB.

Parameter	Type	Default	Description
network	string	required	CIDR prefix
local_pref	int	required	New LOCAL_PREF (higher = more preferred)

Returns: { success, network, old_local_pref, new_local_pref }

OSPF Tools

ospf_get_neighbors

List OSPF neighbors with state, address, priority, and router ID.

Parameter	Type	Default	Description
(none)	—	—	No parameters

Returns: { neighbors: [{neighbor_id, state, address, priority}], count }

ospf_get_lsdb

Query the OSPF Link State Database.

Parameter	Type	Default	Description
(none)	—	—	No parameters

Returns: { lsdb: [{type, advertising_router, ls_id, sequence, age}], count }

ospf_adjust_cost

Change the OSPF cost on an interface.

Parameter	Type	Default	Description
interface	string	required	Interface name (e.g. gre-netclaw)
cost	int	required	New OSPF cost (1-65535)

Returns: { success, interface, old_cost, new_cost }

GRE Tools

gre_tunnel_status

Check GRE tunnel status via system commands (ip tunnel show, ip addr show).

Parameter	Type	Default	Description
(none)	—	—	No parameters

Returns: { tunnels: [...], addresses: [...], count }

Meta Tools

protocol_summary

Consolidated BGP + OSPF + GRE state summary in a single call.

Parameter	Type	Default	Description
(none)	—	—	No parameters

Returns: { router_id, local_as, lab_mode, bgp: {configured, peer_count, peers, rib_size}, ospf: {configured, neighbor_count, neighbors}, gre: {tunnels, addresses, count} }

---

Environment Variables

Variable	Example	Description
NETCLAW_ROUTER_ID	4.4.4.4	BGP/OSPF router ID
NETCLAW_LOCAL_AS	65001	BGP local autonomous system number
NETCLAW_BGP_PEERS	[{"ip":"172.16.0.1","as":65000}]	JSON array of BGP peers
NETCLAW_OSPF_AREAS	["0.0.0.0"]	JSON array of OSPF area IDs
NETCLAW_GRE_TUNNELS	[{"name":"gre-netclaw","local":"...","remote":"..."}]	JSON array of GRE tunnels
NETCLAW_LAB_MODE	true	Relaxes CR requirement for lab testing

---

FRR Lab Testbed

A Docker-based 3-router FRR topology is provided in lab/frr-testbed/ for testing:

NetClaw (AS 65001) ──GRE── Edge1 (AS 65000) ──OSPF── Core (RR) ──OSPF── Edge2
  host/WSL                  1.1.1.1              2.2.2.2           3.3.3.3
  172.16.0.2                172.16.0.1
  eBGP                      iBGP→Core            iBGP hub          iBGP→Core

# Start lab
cd lab/frr-testbed && docker compose up -d

# Create GRE tunnel (requires sudo)
sudo bash scripts/setup-gre.sh

# Verify
bash scripts/verify.sh

---

Workflows

1. Route Injection with Change Control

servicenow-change-workflow → CR approved
→ bgp_inject_route(network, next_hop, local_pref)
→ bgp_get_rib(prefix) → verify route in table
→ pyats-routing → verify on remote devices
→ gait-session-tracking → record change

2. Traffic Engineering via LOCAL_PREF

bgp_get_rib() → current routes
→ bgp_adjust_local_pref(network, local_pref)
→ bgp_get_peers() → verify advertisement
→ gait-session-tracking

3. OSPF Cost Manipulation

ospf_get_neighbors() → verify adjacencies
→ ospf_adjust_cost(interface, cost)
→ ospf_get_lsdb() → verify LSA update
→ pyats-routing → verify SPF reconvergence
→ gait-session-tracking

4. Protocol Health Check

protocol_summary() → full state snapshot
→ bgp_get_peers() → check all Established
→ ospf_get_neighbors() → check all Full
→ gre_tunnel_status() → check all tunnels up
→ gait-session-tracking

5. Controlled Route Withdrawal

servicenow-change-workflow → CR approved
→ bgp_get_rib(prefix) → verify route exists
→ bgp_withdraw_route(network)
→ bgp_get_rib(prefix) → verify withdrawal
→ pyats-routing → verify removal on peers
→ gait-session-tracking

6. Lab Testing (no CR required)

NETCLAW_LAB_MODE=true
→ bgp_inject_route / bgp_withdraw_route
→ bgp_get_rib → verify
→ ospf_adjust_cost → test convergence
→ protocol_summary → snapshot

---

Integration with Other Skills

Skill	Integration
servicenow-change-workflow	MUST gate all route inject/withdraw/cost changes in production
gait-session-tracking	Record every protocol mutation in the audit trail
pyats-routing	Cross-verify protocol state from the device CLI side
uml-diagram	Generate BGP state machines and OSPF area diagrams
markmap-viz	Visualise RIB hierarchy and OSPF LSDB as mind maps
netbox-reconcile	Cross-reference peering with NetBox IPAM/circuits
drawio-diagram	Topology diagrams showing GRE underlay + BGP/OSPF overlay
cml-topology-builder	Provision lab topologies that NetClaw can then peer with

---

Safety Rules

1. NEVER inject or withdraw routes without an approved ServiceNow CR — unless NETCLAW_LAB_MODE=true
2. ALWAYS verify current RIB (bgp_get_rib) before injecting to prevent routing loops
3. ALWAYS verify peer state (bgp_get_peers) before advertising — only to Established peers
4. ALWAYS record protocol changes in GAIT (gait-session-tracking)
5. GRE tunnels require sudo — the install wizard handles initial setup; runtime queries via gre_tunnel_status do not require elevated privileges
6. Lab mode (NETCLAW_LAB_MODE=true) relaxes the CR requirement for the FRR testbed — never set this in production

Guardrails

• Route mutations are gated — ServiceNow CR approval required in production
• Read operations are always safe — bgp_get_peers, bgp_get_rib, ospf_get_neighbors, ospf_get_lsdb, gre_tunnel_status, protocol_summary
• GRE is the default tunnel transport — native Linux kernel support, every major vendor supports it (Cisco, Juniper, Arista, FRR, Nokia), RFC 2784/2890 compliant
• Raw sockets require root for protocol speakers — BGP (TCP/179), OSPF (IP/89), GRE (IP/47)
• No secrets in protocol state — RIB/LSDB queries return routing information, not credentials