automateyournetwork/forward

Forward Skill

Skill: /forward MCP Server: forward-mcp Source: https://github.com/forwardnetworks/forward-mcp

Use When

Use this skill for Forward snapshot assurance, collection, and analysis:

• Discover Forward networks, snapshots, and devices
• Verify paths and reachability
• Discover and run NQE checks
• Review predefined checks, failed checks, and vulnerability analysis
• Compare NQE, snapshot, and config diffs
• Search configurations
• Analyze blast radius for a source location to destination IPv4 subnets
• Review hardware and OS lifecycle support
• Find missing devices inferred during collection
• Support lab or real-network collection workflows

Startup

1. Start with get_default_settings to see configured defaults.
2. If no default network is set, use list_networks with a small limit and ask the user which network to use.
3. Prefer explicit network_id and snapshot_id values for repeatable results.
4. Use bounded limits by default. Use all_results only when the user needs the complete dataset.
5. In Forward SaaS, prefer FORWARD_API_BASE_URL=https://fwd.app and set FORWARD_INSTANCE_ID for local cache partitioning when multiple SaaS orgs or accounts are used on the same NetClaw host.

Tool Routing

| User intent | Preferred tools | |-------------|-----------------| | "List Forward networks" | list_networks | | "Use this network by default" | set_default_network | | "Show collection sources" | list_classic_devices, get_classic_device | | "Add lab devices" | upsert_classic_devices | | "Show collector status" | get_collector_status | | "Start collection" | start_collection_task, get_collector_task, then wait_for_latest_snapshot; use start_collection only for legacy flows | | "Show snapshots" | list_snapshots, get_latest_snapshot | | "List devices" | list_devices, get_device_basic_info | | "Find missing collection neighbors" | get_missing_devices | | "Trace paths" | search_paths_bulk, then search_paths for one-off traces | | "Trace app-aware paths" | list_l7_applications, then search_paths_bulk or search_paths with app_id, url, or domain | | "Show blast radius" | suggest_blast_radius_sources, then get_blast_radius | | "Find NQE checks" | search_nqe_queries, list_nqe_queries | | "Run an NQE check" | run_nqe_query_by_id; use start_nqe_query for long-running checks | | "Write or run ad-hoc NQE" | Prefer search_nqe_queries first; use run_nqe_query only when no built-in query fits and async NQE for long-running or large results | | "Show predefined checks" | list_predefined_checks | | "Show failed checks or intent status" | list_checks, then get_check | | "Show vulnerabilities or CVE exposure" | search_nqe_queries, then run_nqe_query_by_id with the /Security/CVEs/... query IDs | | "Draw topology from Forward" | get_snapshot_topology, then search NQE for CDP/LLDP and protocol-peer evidence when needed | | "Summarize large results" | get_nqe_result_summary, get_nqe_result_chunks, analyze_nqe_result_sql | | "Search configs" | search_configs | | "Compare NQE or intent/check results" | get_nqe_diff | | "Summarize snapshot diffs" | get_snapshot_diff_summary | | "Show route, ACL, NAT, interface, check, or vulnerability diffs" | get_snapshot_diff | | "Compare snapshots/configs" | get_config_diff | | "Check hardware or OS support" | get_device_hardware, get_hardware_support, get_os_support | | "Show locations" | list_locations, get_device_locations |

NQE Discovery Notes

Forward MCP owns the NQE catalog. Do not copy catalog contents into NetClaw. For natural-language NQE requests:

1. Prefer first-class tools when they match the intent, such as get_device_basic_info, get_device_hardware, get_hardware_support, or get_os_support.
2. Otherwise use search_nqe_queries with the user's intent.
3. Use list_nqe_queries only when the directory or query family is already known.
4. Preserve the returned FQ_... query ID in the answer and execute it with run_nqe_query_by_id.
5. Keep limits bounded unless the user asks for complete data.

Use run_nqe_query for ad-hoc NQE source only after checking whether a built-in query already answers the question and the expected result fits a bounded synchronous call. For long-running or large queries, use start_nqe_query, poll get_nqe_query_status, then fetch rows with get_nqe_query_result. These execute raw NQE or query IDs through Forward's native NQE APIs; they do not create or save a new query in the NQE Library. Keep ad-hoc queries narrow, set limits by default, and explain when the result is from custom source rather than a built-in Forward query. Use all_results: true only when the user needs the complete table.

Constructing Ad-Hoc NQE

Prefer built-in query IDs when they fit. When a question needs raw NQE, build it incrementally and execute it through Forward MCP:

1. Start with a tiny selector such as foreach d in network.devices select { Name: d.name }.
2. Add one model surface at a time, then run start_nqe_query, poll get_nqe_query_status, and page with get_nqe_query_result.
3. Keep filters inside NQE instead of post-processing large result sets.
4. Use schema-native types and OneOf patterns. Enumerations can be compared as NatType.LB; data-bearing OneOf values use when ... is.

Useful raw NQE patterns:

On-prem load balancer VIPs, DNAT-style rewrites, and backend targets:

foreach device in network.devices
foreach natEntry in device.natEntries
where natEntry.natType == NatType.LB
foreach rewrite in natEntry.rewrites
select {
  LoadBalancer: device.name,
  Vip: natEntry.headerMatches.ipv4Dst,
  Ports: natEntry.headerMatches.tpDst,
  Backends: rewrite.ipv4Dst,
  BackendPorts: rewrite.tpDst
}

Other VIPs in the same subnet:

targetSubnet = ipSubnet("110.240.240.0/24");
foreach device in network.devices
foreach natEntry in device.natEntries
where natEntry.natType == NatType.LB
foreach vip in natEntry.headerMatches.ipv4Dst
where vip in targetSubnet
foreach rewrite in natEntry.rewrites
select {
  LoadBalancer: device.name,
  Vip: vip,
  Ports: natEntry.headerMatches.tpDst,
  Backends: rewrite.ipv4Dst
}

Cloud VPC load balancers:

foreach cloudAccount in network.cloudAccounts
foreach vpc in cloudAccount.vpcs
foreach loadBalancer in vpc.loadBalancers
foreach rule in loadBalancer.loadBalancerRules
foreach backend in rule.backends
let server = when backend is
               server(backendServerData) -> backendServerData;
               otherwise -> null : BackendServer
where isPresent(server)
select {
  CloudAccount: cloudAccount.name,
  Vpc: vpc.name,
  LoadBalancer: loadBalancer.name,
  FrontendIps: rule.frontendIps,
  FrontendPorts: rule.frontendPorts,
  BackendIps: server.backendIps,
  BackendPorts: server.backendPorts
}

VIP route propagation:

targetVip = ipSubnet("110.240.240.240/32");
foreach device in network.devices
foreach vrf in device.networkInstances
where isPresent(vrf.afts.ipv4Unicast)
foreach route in vrf.afts.ipv4Unicast.ipEntries
where targetVip in route.prefix
where length(route.prefix) >= 24
foreach nextHop in route.nextHops
select {
  Device: device.name,
  Vrf: vrf.name,
  Prefix: route.prefix,
  OriginProtocol: nextHop.originProtocol,
  NextHopType: nextHop.nextHopType,
  NextHopIp: nextHop.ipAddress,
  Interface: nextHop.interfaceName
}

For topology, start with get_snapshot_topology for native directed links. Then search for both link evidence and protocol-peer evidence when needed. CDP/LLDP can describe physical neighbors; peer queries such as BGP can describe relationships Forward models beyond discovery protocols.

If search_nqe_queries or list_nqe_queries reports that the query index is empty, do this only in a persistent OpenClaw session and only after user confirmation:

1. Run hydrate_database with regenerate_embeddings: false.
2. Run refresh_query_index.
3. Retry search_nqe_queries or list_nqe_queries.

Safety Rules

Default to read-only Forward tools. Require explicit human confirmation before tools that create, update, delete, clear, hydrate, rebuild, start/cancel collection, or set persistent defaults. This includes collector/source, credential, network, snapshot, location, entity/relation, observation, local cache/index, and set_default_network operations. Creating new Forward networks requires full org admin privileges; do not use create_network unless the user explicitly confirms that role. Updating an existing Forward network requires network admin privileges.

Never put Forward credentials in repository files. Use ~/.openclaw/.env. For private CA deployments, use FORWARD_CA_CERT_PATH; do not disable TLS verification.

Workflows

Diffs

1. Use get_snapshot_diff_summary first for a bounded overview.
2. Use get_snapshot_diff for focused route, ACL, NAT, interface, check, file/config, inventory-query, routing-loop, or vulnerability diffs.
3. Use get_nqe_diff for arbitrary NQE and intent-style query diffs.
4. Use get_config_diff when the user specifically asks for config text drift.

Blast Radius

1. Use suggest_blast_radius_sources if the source name or location filter is uncertain.
2. Use get_blast_radius with source_device for a device source, or source when the prompt already supplies Forward LocationFilter JSON.
3. Keep dst_subnets, timeout_seconds, and paging_options bounded.
4. Use blast radius for security/exposure questions; use NQE for tabular snapshot facts and search_paths_bulk for specific path traces.

Checks and CVEs

1. Use list_checks with statuses such as FAIL, WARN, or ERROR to triage intent/check state for a snapshot.
2. Use get_check for the detailed rows behind a specific failed check.
3. Use list_predefined_checks when the user asks what built-in checks exist.
4. Use NQE for CVE posture. Prefer search_nqe_queries for natural-language discovery, then run_nqe_query_by_id.
5. Useful built-in CVE query paths include /Security/CVEs/CVE violations by CVE, /Security/CVEs/CVE violations by device, /Security/CVEs/CVE violation details by device, and /Security/CVEs/Vendor CVE metadata.
6. Use get_nqe_diff for CVE query drift between snapshots. Use get_snapshot_diff with diff_type: "vulnerabilities" for the Forward vulnerability diff domain.

Collection and Lab Demo

1. Treat collection setup and start/cancel actions as admin workflows.
2. Use them only on lab/admin networks or after explicit user confirmation.
3. Treat collector installation/onboarding as a separate prerequisite. Anyone can install or onboard a collector, but a network admin must assign that collector to the target network. The stable Linux collector download URL is https://fwd.app/api/software/client?type=LINUX.
4. Before starting collection, run get_collector_status and list_classic_devices.
5. Prefer start_collection_task, poll it with get_collector_task, then use wait_for_latest_snapshot. Use start_collection only when task creation is unavailable in the target deployment.

Topology Drawing

1. Prefer Forward NQE evidence for collected topology questions: link queries plus relevant protocol-peer queries.
2. If the NQE result only shows management-plane neighbors or incomplete links in a real or emulated network, use the originating topology source as the edge source and Forward as the collected assurance source.
3. Use the available lab backend, source-of-truth, inventory, or discovery tool to identify device names, management IPs, physical links, and credentials before Forward collection.
4. Before start_collection, confirm the assigned Forward collector can reach the target management network. If not, the missing step is collector installation, assignment, or routing.
5. Render a normalized node/edge list with Draw.io, Markmap, or another diagram skill. Never infer links from names or management IPs alone.

Result Discipline

• Summarize large tables before presenting them.
• Preserve network IDs, snapshot IDs, query IDs, and device names in the answer.
• When a path or NQE result is inconclusive, say what data was missing and which next read-only Forward tool should be run.
• For config and NQE diffs, separate intended changes from unexpected changes.
• For snapshot diffs, start with counts/summary and drill into the changed domain that matters.