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 (store / analyze / help)
├── config/
│   └── index.js             # Centralized env-driven configuration + validation
├── integrations/
│   ├── storeDetail.js       # Full store report builder (Meraki + SIW + MDM)
│   └── storeHealth.js       # Health score + summary
├── models/
│   ├── Store.js             # Store domain model (normalizes SIW location)
│   └── HealthReport.js      # Score / issue accumulator
├── services/
│   ├── meraki.js            # Meraki API client (cached, retried)
│   ├── siw.js               # SIW calls (proxied via the remote agent)
│   ├── mdm.js               # Workspace ONE MDM client (retried)
│   └── websocket.js         # WS server + proxyRequest helper
├── tests/
│   ├── *.test.js            # Unit tests
│   ├── integration/         # Integration tests using mocks
│   └── mocks/               # Service mocks for tests
├── utils/
│   ├── logger.js            # Structured JSON logger (LOG_LEVEL aware)
│   ├── merakiMatcher.js     # Device ↔ Meraki client matching
│   ├── retry.js             # withRetry wrapper (exponential backoff)
│   └── validate.js          # Input parsers
├── constants.js             # Shared constants (STORE_MODES, MDM device types)
├── remoteAgent.js           # Lightweight proxy client (run on internal host)
├── server.js                # Main entry point (bot + WS server)
├── package.json
├── eslint.config.js
├── .prettierrc.json
└── .env.example

Logging

The app emits single-line JSON to stdout/stderr via utils/logger.js. Set LOG_LEVEL in .env to one of debug | info | warn | error (default: info).

Security Notes

• Never commit .env (it is gitignored, along with .env.bak.*).
• The WebSocket connection between server and remote agent is protected by a shared WS_TOKEN. The remote agent now sends the token in an Authorization: Bearer header (the legacy ?token=... query parameter still works for older deployments but should be migrated).
• Only one remote agent may be connected at a time; a newer connection replaces the older one and any in-flight proxy requests are rejected (rather than silently hanging).
• 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.

Development

npm run lint          # eslint + prettier check
npm run lint:fix      # auto-fix lint issues
npm run format        # prettier write
npm test              # jest (unit + integration tests using mocks)
npm run test:watch

License

ISC