Network Health Check Integration

How the Full Chain Works

When you send "scan brighton" via Telegram, OpenClaw running on MacTruc matches the phrase to SKILL.md, invokes netrecon_brighton.py as a subprocess, reads its JSON stdout, extracts telegram_message, and sends it back to you. The Python script itself never touches Telegram — it only produces structured output. OpenClaw owns the delivery.

Telegram (you)
  → OpenClaw on MacTruc           # matches trigger, calls script
    → netrecon_brighton.py         # subprocess, stdout = JSON
      → SSH into BigMac            # cat brighton.txt
      → SSH into BigMac (×8)       # curl POST simple_ping.php per device
      → collect + format results
    → OpenClaw reads JSON stdout
  → Telegram (formatted report)    # ✅ / ❌ per device
            

Why Execution Happens on BigMac

simple_ping.php runs under XAMPP on BigMac and issues ICMP pings from BigMac's network stack. This means ping results reflect BigMac's LAN reachability — not MacTruc's. Since BigMac is the management host on the 192.168.1.x segment, its perspective is authoritative. The SSH tunnel (MacTruc → BigMac) is used only for access; all actual pinging happens on BigMac itself via localhost.

Format Rules

Plain CSV. One device per line. No header row. Hostname first, IP second, comma-separated. Lines beginning with # are treated as comments and skipped. Blank lines are ignored.

# Brighton Site — 192.168.1.x
Wireless Router,192.168.1.1
Security Module,192.168.1.15
Bunker,192.168.1.17
Garage-Main,192.168.1.18
Printer,192.168.1.20
MacDaddy,192.168.1.10
MacTruc,192.168.1.51
BigMac,192.168.1.60
            

Adding or Removing Devices

Edit brighton.txt directly on BigMac. No script changes needed — the skill reads the file fresh on every scan. Changes take effect immediately on the next trigger.

# Add a device — just append a line
echo "NAS-Storage,192.168.1.25" >> \
  /Applications/XAMPP/xamppfiles/htdocs/tools/NetRecon-Local/devices/brighton.txt

# Verify the file on BigMac from MacTruc
ssh BigMac cat /Applications/XAMPP/xamppfiles/htdocs/tools/NetRecon-Local/devices/brighton.txt
            

Verify SSH to BigMac

Confirms SSH key auth and the BigMac alias are working.

ssh BigMac echo "SSH OK"
# Expected: SSH OK
# If fails: check ~/.ssh/config and authorized_keys on BigMac

Read Device File Over SSH

Confirms the device file exists and is readable from MacTruc via SSH.

ssh BigMac cat /Applications/XAMPP/xamppfiles/htdocs/tools/NetRecon-Local/devices/brighton.txt
# Expected: 8 lines of Hostname,IP pairs
# If fails: check file path and permissions on BigMac

Verify XAMPP Apache is Running

Confirms Apache is up and serving on BigMac's localhost.

ssh BigMac curl -s -o /dev/null -w "%{http_code}" http://localhost/
# Expected: 200 (or 403 — either means Apache is running)
# If returns 000: Apache is stopped — open XAMPP Control Panel on BigMac

Test simple_ping.php Directly

Fires a single POST to the ping API from BigMac via SSH. This is exactly what the script does for each device.

ssh BigMac curl -s -m 10 -X POST \
  -H 'Content-Type: application/json' \
  --data-binary @- \
  'http://localhost/tools/NetRecon-Local/api/simple_ping.php' \
  <<< '{"hostname":"Wireless Router","ip":"192.168.1.1","device_index":0,"total_devices":1}'

# Expected JSON response:
{
  "success": true,
  "result": {
    "hostname": "Wireless Router",
    "ip": "192.168.1.1",
    "success": true,
    "response_time": 84.5,
    ...
  }
}
# If success:false — device unreachable (expected for MacDaddy)
# If connection refused — Apache not running
# If 404 — check PHP file path

Run the Script Standalone

Runs the full skill end-to-end from MacTruc terminal without involving OpenClaw or Telegram. This is the definitive sanity check.

python3 ~/.openclaw-trucbot1/skills/NetPotent/netrecon_brighton.py

# Expected: JSON with success:true, 8 results, telegram_message field populated
# MacDaddy should show success:false (device is offline)
# Total runtime: ~10-15 seconds (sequential pings)

Test End-to-End via Telegram

Send the trigger phrase to Truc via Telegram. OpenClaw should invoke the script and return the formatted report within 20–30 seconds.

# In Telegram, DM TrucBot1:
scan brighton

# Expected Telegram response:
🔍 Brighton Scan — 2026-05-17 07:20
━━━━━━━━━━━━━━━━━━━━━━━
✅ Wireless Router     192.168.1.1     UP
✅ Security Module     192.168.1.15    UP
...
❌ MacDaddy            192.168.1.10    DOWN
...
7 UP · 1 DOWN

MacDaddy (192.168.1.10) is not responding — worth a look.

Key Constants (top of file)

These are the only values you'd ever need to change to adapt the skill to a different site or environment.

REMOTE_HOST = "BigMac"       # SSH alias from ~/.ssh/config

DEVICE_FILE = (              # Path on BigMac to device CSV
    "/Applications/XAMPP/xamppfiles/htdocs"
    "/tools/NetRecon-Local/devices/brighton.txt"
)

PING_URL = (                 # URL on BigMac localhost — curl hits this
    "http://localhost/tools/NetRecon-Local/api/simple_ping.php"
)

SSH Hardening Options

All SSH calls use the same hardened options as backup_truc.py. BatchMode=yes prevents interactive password prompts (fails fast if key auth is broken). ConnectTimeout=30 prevents indefinite hangs. ServerAliveInterval keeps the connection alive during long scans.

SSH_OPTIONS = [
    "-o", "BatchMode=yes",           # no interactive prompts
    "-o", "ConnectTimeout=30",       # fail fast if BigMac unreachable
    "-o", "StrictHostKeyChecking=accept-new",
    "-o", "ServerAliveInterval=15",  # keep alive during scan
    "-o", "ServerAliveCountMax=3",
]

Execution Flow (per device)

The script SSHes into BigMac once to read the device file, then SSHes again for each device to fire a curl POST. Each SSH connection is independent — there is no persistent session. This is intentional: simpler, more resilient, and consistent with the backup skill pattern.

# Step 1 — read device list (1 SSH call)
ssh BigMac cat '{DEVICE_FILE}'

# Step 2 — ping each device (1 SSH call per device)
ssh BigMac curl -s -m 10 -X POST \
  -H 'Content-Type: application/json' \
  --data-binary @- '{PING_URL}' \
  <<< '{json_payload}'

# Step 3 — format and print JSON to stdout
print(json.dumps(output, indent=2))

JSON Output Structure

OpenClaw reads this from stdout. The telegram_message field is pre-formatted and sent directly. The results array is available for future chaining to other skills or logging.

{
  "success": true,
  "skill": "netrecon_brighton",
  "trigger": "scan brighton",
  "scanned_at": "2026-05-17 07:11",
  "device_count": 8,
  "up": 7,
  "down": 1,
  "results": [
    {
      "hostname": "Wireless Router",
      "ip": "192.168.1.1",
      "success": true,           # true = UP, false = DOWN
      "response_time": 84.5,     # ms — ~1100ms means timeout (DOWN)
      "error": null              # non-null = script/curl error (not DOWN)
    },
    ...
  ],
  "telegram_message": "..."      # pre-formatted, sent as-is by OpenClaw
}

Role of SKILL.md

OpenClaw scans all SKILL.md files in the skills directory at startup. The YAML frontmatter provides the skill name. The Trigger Phrases section tells the AI what natural language patterns to match. The Actions section tells it what command to run and how to interpret the output. The Python script itself is never seen by OpenClaw — only its stdout JSON.

Registered Trigger Phrases

"scan brighton"
"ping brighton"
"check brighton"
"run a brighton scan"
"how's brighton looking?"
"what's up on brighton?"

Response Behavior (from SKILL.md Actions)

OpenClaw is instructed to:

1. Send telegram_message field directly — it is pre-formatted, do not reformat
2. If any devices are DOWN → follow up with named callout:
   "MacDaddy (192.168.1.10) is not responding — worth a look."
3. On failure → surface error field clearly, do not dump raw JSON

Add a New Site (e.g., "scan condo")

Copy the skill pattern. Create condo.txt on BigMac with the new site's device list. Duplicate netrecon_brighton.py as netrecon_condo.py, update the DEVICE_FILE constant. Create a new SKILL.md or add trigger phrases to the existing one pointing to the new script.

# New constants in netrecon_condo.py
DEVICE_FILE = (
    "/Applications/XAMPP/xamppfiles/htdocs"
    "/tools/NetRecon-Local/devices/condo.txt"
)

Proactive State-Change Alerts (netrecon_watch.py)

Run a scheduled scan via cron or a LaunchAgent on MacTruc. Compare results against a persisted state file (JSON). If any device's status changes — UP→DOWN or DOWN→UP — fire a Telegram alert immediately. No alert if nothing changed.

# Conceptual flow
previous_state = load_json("~/.netpotent/brighton_state.json")
current_state  = run_scan()
deltas         = diff(previous_state, current_state)

if deltas:
    send_telegram_alert(deltas)    # only on change

save_json(current_state)           # persist for next run

Auto-Ticket on DOWN Detection

Chain the BrightDone/HESK ticketing skill into the watch loop. When a device transitions to DOWN, automatically open a ticket with device name, IP, timestamp, and site — pre-populated, no human input required.

# In watch loop, when device goes DOWN:
if device.was_up and not device.is_up:
    create_hesk_ticket(
        subject  = f"{device.hostname} UNREACHABLE",
        body     = f"IP: {device.ip} | Site: Brighton | {timestamp}",
        category = "Network"
    )