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**

   ```bash
   git clone <repo>
   cd netanalyzer
   npm install
   ```

2. **Configure environment**

   ```bash
   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)

```bash
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)

```bash
# 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

```bash
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