netanalyzer/README.md

NetAnalyzer

Webex bot that provides store-level network and device health analysis by correlating data from Meraki, SIW (Store Information Warehouse), and Workspace ONE MDM.

What it does

• store <number> — Full detailed report of a store's registers, printers, payment terminals, network devices, MDM inventory, and their online/offline status via Meraki clients.
• analyze <number> — Higher-level health summary with an overall score and prioritized issues (network, POS systems, peripherals).

The bot helps operations teams quickly understand the connectivity and device health state of a retail location.

Architecture

┌─────────────────┐          ┌─────────────────────┐
│  Webex Bot      │◄────────►│  NetAnalyzer Server │
│  (Webex rooms)  │  Webex   │  (server.js)        │
└─────────────────┘          └─────────┬───────────┘
                                       │
                                       │ WebSocket (authenticated)
                                       ▼
                              ┌─────────────────────┐
                              │  Remote Agent       │◄──► SIW API (Basic Auth)
                              │  (remoteAgent.js)   │◄──► Workspace ONE MDM
                              └─────────────────────┘
                                       │
                                       ▼
                              Meraki API (direct from server)

Why the remote agent?
SIW and some MDM systems are only reachable from specific internal networks. The remote agent runs in that environment and proxies requests back to the main NetAnalyzer server over an authenticated WebSocket.

Prerequisites

• Node.js >= 18
• A Webex bot account with access token
• Meraki API key with organization access
• Access to your organization's SIW API and Workspace ONE (AirWatch) environment
• Ability to run the remote agent on a machine that can reach SIW/MDM

Setup

1. Clone and install

   git clone <repo>
   cd netanalyzer
   npm install
   

2. Configure environment

   cp .env.example .env
   # Edit .env with your real credentials
   

   Required values are documented in .env.example.

3. (Optional but recommended) Rotate all secrets If you previously had credentials in the repository, rotate:

   • Webex bot token
   • Meraki API key
   • SIW credentials
   • Workspace ONE client secret + tenant code
   • WS_TOKEN

Running

Main server + bot (where the Webex connection lives)

npm start
# or for development with auto-reload
npm run dev

This starts:

• The Webex bot framework (listens for messages in Webex spaces)
• The WebSocket server on the port defined in WS_PORT (default 8080)

Remote agent (run on a machine that can reach internal systems)

# On the internal machine
node remoteAgent.js

Make sure WS_URL in its environment points to the main server with the correct WS_TOKEN.

Bot Commands

In any Webex space where the bot is a member:

• store 782 — Detailed device inventory and connectivity for store 782
• analyze 782 — Quick health summary with score for store 782

The bot also responds to variations containing "store" or "analyze".

Project Structure

.
├── bot/
│   └── handlers.js          # Webex command handlers
├── config/
│   └── index.js             # Centralized configuration from env
├── integrations/
│   ├── storeDetail.js       # Full store report builder
│   └── storeHealth.js       # Health score + summary
├── services/
│   ├── meraki.js            # Meraki API client + caching
│   ├── siw.js               # SIW calls (via remote proxy)
│   ├── mdm.js               # Workspace ONE MDM client
│   └── websocket.js         # WebSocket server + proxyRequest helper
├── utils/
│   ├── formatter.js
│   └── dataMerger.js        # (currently unused)
├── remoteAgent.js           # Lightweight proxy client
├── server.js                # Main entry point (bot + ws server)
├── package.json
└── .env.example

Security Notes

• Never commit .env (it is gitignored).
• The WebSocket connection between server and remote agent is protected by a shared token (WS_TOKEN).
• All SIW communication uses Basic Auth and is only performed through the remote agent.
• Meraki and MDM calls use tokens that should be scoped to the minimum necessary permissions.

Next Steps / Roadmap

See the phased improvement plan in the project history (or ask the maintainer for current priorities):

• Phase 0: Foundational hygiene (git, secrets, docs) ← current
• Phase 1: Input validation, shared logic extraction, graceful shutdown
• Phase 2: Linting, tests, structured logging, basic resilience
• Phase 3: Domain modeling and architectural cleanup

License

ISC