# NetGuardian

A self-hosted MCP server that lets **Alexa+** answer plain-English questions about
your home network — *"is my wifi struggling?"*, *"what's using all my bandwidth?"*,
*"is anything on my network acting weird?"* — using live network/OS diagnostics and
an AWS Bedrock reasoning layer.

Built for the Amazon Developer Hackathon — **Alexa+ track**, stacked with the
**AWS Builder** and **Open Source** mini challenges.

## Why this exists

Most people can't self-diagnose home network problems — they just know "the wifi
is bad" and have no path from that feeling to an actual fix. NetGuardian gives
Alexa+ real diagnostic data (ping latency, bandwidth per interface, connected
devices, interface error counters) and lets an LLM turn that into one clear,
spoken sentence with an actual next step.

## Architecture

```
Alexa+  --(MCP, Streamable HTTP, spec 2025-11-25)-->  NetGuardian server
                                                              |
                                            network_tools.py (psutil, ping, ARP)
                                                              |
                                            reasoning.py
                                              1. Local Ollama LLM  (default, free, no AWS)
                                              2. AWS Bedrock       (optional upgrade path)
                                              3. Rule-based fallback (always available)
```

- **Transport**: MCP Streamable HTTP per spec `2025-11-25` — single `/mcp` endpoint,
  session tracked via `Mcp-Session-Id` header.
- **Diagnostics**: `network_tools.py` — gateway/internet ping, per-interface
  bandwidth sampling, ARP-table device listing, interface error/drop counters.
- **Reasoning**: `reasoning.py` tries a local [Ollama](https://ollama.com) LLM first
  (free, offline, no AWS account needed), then an optional AWS Bedrock call if
  credentials are configured (`bedrock_client.py`), then a deterministic rule-based
  summary as a last resort. The tool response always reports which tier answered via
  `reasoning_source`, so it's clear during a demo — or to anyone reading the code —
  exactly what produced the diagnosis.

### Why Ollama is the default, not Bedrock

This project runs entirely free with zero AWS spend: install Ollama, pull a small
model, and NetGuardian gets real LLM reasoning with no AWS account or payment method
involved. Bedrock (`bedrock_client.py`) is left in as a documented, working upgrade
path — set AWS credentials and it activates automatically — but it is intentionally
not required to run or demo NetGuardian.

### Running with Ollama (recommended, free)

```bash
# Install Ollama: https://ollama.com/download
ollama pull llama3.2
ollama serve   # usually starts automatically after install
```

NetGuardian will detect it automatically at `http://localhost:11434` (override with
the `OLLAMA_HOST` / `OLLAMA_MODEL` env vars).

## Tools exposed

| Tool | Purpose |
|---|---|
| `get_network_status` | Gateway/internet reachability + live bandwidth per interface |
| `list_connected_devices` | Devices visible in the local ARP/neighbor table |
| `get_interface_health` | Per-interface up/down state, link speed, error/drop counters |
| `diagnose_network_issue(question)` | The main conversational tool — gathers diagnostics, asks Bedrock, returns a plain-English answer |
| `restart_network_service(service_name, confirm)` | Restarts a whitelisted service (`NetworkManager`, `dnsmasq`, `systemd-resolved`); dry-run unless `confirm=True` |

## Setup

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in AWS credentials for the Bedrock layer
```

## Run locally

```bash
python server.py
```

The server binds to `0.0.0.0:8811` by default (override with `NETGUARDIAN_HOST`
/ `NETGUARDIAN_PORT`) and serves the MCP endpoint at `/mcp`.

Test it directly:

```bash
curl -i -X POST http://127.0.0.1:8811/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'
```

Grab the `Mcp-Session-Id` header from the response and pass it as
`Mcp-Session-Id` on subsequent `tools/list` / `tools/call` requests.

## Deploying for the demo (AWS EC2) — optional

This step is only needed if you want a publicly reachable endpoint for live
Alexa+ integration testing, or if you choose to enable the Bedrock upgrade
path. NetGuardian runs and demos fine locally with Ollama alone.


1. Launch a small EC2 instance (free-tier eligible, e.g. `t3.micro`, Amazon Linux
   or Ubuntu).
2. Attach an IAM role with `bedrock:InvokeModel` permission — don't hardcode AWS
   keys on the instance if you can avoid it.
3. Open the security group to allow inbound traffic on your chosen port from
   wherever you'll demo from.
4. Clone this repo, `pip install -r requirements.txt`, and run `python server.py`.
5. Point your Alexa+ Agent Skill / MCP client config at
   `http://<ec2-public-ip>:8811/mcp`.

This is also the AWS Builder mini-challenge integration: EC2 hosts the server,
Bedrock powers the reasoning tool — both load-bearing, not decorative.

## Safety notes

- `restart_network_service` only accepts a small whitelist of services and
  defaults to a dry run. It will not touch anything outside that whitelist.
- The Bedrock call has an explicit fallback path so a missing/expired AWS
  credential degrades the diagnosis quality — it does not crash the tool.

## License

MIT — see [LICENSE](LICENSE).