NetAlertX/docs/API_NETTOOLS.md

Net Tools API Endpoints

The Net Tools API provides network diagnostic utilities, including Wake-on-LAN, traceroute, speed testing, DNS resolution, nmap scanning, internet connection information, and network interface info.

All endpoints require authorization via Bearer token.

---

Endpoints

1. Wake-on-LAN

• POST /nettools/wakeonlan Sends a Wake-on-LAN packet to wake a device.

Request Body (JSON):

{
  "devMac": "AA:BB:CC:DD:EE:FF"
}

Response (success):

{
  "success": true,
  "message": "WOL packet sent",
  "output": "Sent magic packet to AA:BB:CC:DD:EE:FF"
}

Error Responses:

• Invalid MAC address → HTTP 400
• Command failure → HTTP 500

---

2. Traceroute

• POST /nettools/traceroute Performs a traceroute to a specified IP address.

Request Body:

{
  "devLastIP": "192.168.1.1"
}

Response (success):

{
  "success": true,
  "output": "traceroute output as string"
}

Error Responses:

• Invalid IP → HTTP 400
• Traceroute command failure → HTTP 500

---

3. Speedtest

• GET /nettools/speedtest Runs an internet speed test using speedtest-cli.

Response (success):

{
  "success": true,
  "output": [
    "Ping: 15 ms",
    "Download: 120.5 Mbit/s",
    "Upload: 22.4 Mbit/s"
  ]
}

Error Responses:

• Command failure → HTTP 500

---

4. DNS Lookup (nslookup)

• POST /nettools/nslookup Resolves an IP address or hostname using nslookup.

Request Body:

{
  "devLastIP": "8.8.8.8"
}

Response (success):

{
  "success": true,
  "output": [
    "Server: 8.8.8.8",
    "Address: 8.8.8.8#53",
    "Name: google-public-dns-a.google.com"
  ]
}

Error Responses:

• Missing or invalid devLastIP → HTTP 400
• Command failure → HTTP 500

---

5. Nmap Scan

• POST /nettools/nmap Runs an nmap scan on a target IP address or range.

Request Body:

{
  "scan": "192.168.1.0/24",
  "mode": "fast"
}

Supported Modes:

Mode	nmap Arguments
fast	-F
normal	default
detail	-A
skipdiscovery	-Pn

Response (success):

{
  "success": true,
  "mode": "fast",
  "ip": "192.168.1.0/24",
  "output": [
    "Starting Nmap 7.91",
    "Host 192.168.1.1 is up",
    "... scan results ..."
  ]
}

Error Responses:

• Invalid IP → HTTP 400
• Invalid mode → HTTP 400
• Command failure → HTTP 500

---

6. Internet Connection Info

• GET /nettools/internetinfo Fetches public internet connection information using ipinfo.io.

Response (success):

{
  "success": true,
  "output": "IP: 203.0.113.5 City: Sydney Country: AU Org: Example ISP"
}

Error Responses:

• Failed request or empty response → HTTP 500

---

7. Network Interfaces

• GET /nettools/interfaces Fetches the list of network interfaces on the system, including IPv4/IPv6 addresses, MAC, MTU, state (up/down), and RX/TX byte counters.

Response (success):

{
  "success": true,
  "interfaces": {
    "eth0": {
      "name": "eth0",
      "short": "eth0",
      "type": "ethernet",
      "state": "up",
      "mtu": 1500,
      "mac": "00:11:32:EF:A5:6B",
      "ipv4": ["192.168.1.82/24"],
      "ipv6": ["fe80::211:32ff:feef:a56c/64"],
      "rx_bytes": 18488221,
      "tx_bytes": 1443944
    },
    "lo": {
      "name": "lo",
      "short": "lo",
      "type": "loopback",
      "state": "up",
      "mtu": 65536,
      "mac": null,
      "ipv4": ["127.0.0.1/8"],
      "ipv6": ["::1/128"],
      "rx_bytes": 123456,
      "tx_bytes": 123456
    }
  }
}

Error Responses:

• Command failure or parsing error → HTTP 500

---

Example curl Requests

Wake-on-LAN:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/nettools/wakeonlan" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"devMac":"AA:BB:CC:DD:EE:FF"}'

Traceroute:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/nettools/traceroute" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"devLastIP":"192.168.1.1"}'

Speedtest:

curl "http://<server_ip>:<GRAPHQL_PORT>/nettools/speedtest" \
  -H "Authorization: Bearer <API_TOKEN>"

Nslookup:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/nettools/nslookup" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"devLastIP":"8.8.8.8"}'

Nmap Scan:

curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/nettools/nmap" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"scan":"192.168.1.0/24","mode":"fast"}'

Internet Info:

curl "http://<server_ip>:<GRAPHQL_PORT>/nettools/internetinfo" \
  -H "Authorization: Bearer <API_TOKEN>"

Network Interfaces:

curl "http://<server_ip>:<GRAPHQL_PORT>/nettools/interfaces" \
  -H "Authorization: Bearer <API_TOKEN>"

---

MCP Tools

Network tools are available as MCP Tools for AI assistant integration:

• wol_wake_device, trigger_scan, get_open_ports

📖 See MCP Server Bridge API for AI integration details.