# 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. Gemini API         (default, free, no card)
                                              2. Local Ollama LLM   (offline backup, free)
                                              3. AWS Bedrock        (optional upgrade path)
                                              4. 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 the [Gemini API](https://aistudio.google.com) first
  (free tier, no credit card required — just a Google account), then falls back to a
  local [Ollama](https://ollama.com) LLM if Gemini is unavailable, 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 Gemini is the default, not Bedrock

This project runs entirely free with zero AWS spend: get a free API key at
[Google AI Studio](https://aistudio.google.com) (no credit card needed) and NetGuardian
gets real cloud LLM reasoning with no local hardware strain. 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 Gemini (recommended, free, no card)

1. Go to [aistudio.google.com](https://aistudio.google.com), sign in, click **Get API
   key** → **Create API key** → **Create project** (keep it separate from any other
   projects you have).
2. Set the key as an environment variable before running the server:
   ```bash
   export GEMINI_API_KEY=your_key_here   # macOS/Linux
   set GEMINI_API_KEY=your_key_here      # Windows cmd, same terminal session
   ```
3. Run `python server.py`. `reasoning_source` in tool responses will read `"gemini"`
   when this is working.

### Running with Ollama (offline backup, also free)

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

NetGuardian falls back to this automatically if no `GEMINI_API_KEY` is set or the
Gemini call fails, detecting Ollama at `http://127.0.0.1:11434` (override with the
`OLLAMA_HOST` / `OLLAMA_MODEL` env vars). Note: local models are noticeably slower
and lower-quality than Gemini on modest hardware (8GB RAM, no dedicated GPU).

## 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 — autonomously orchestrates which extra diagnostics to run, folds in recent history, then reasons through the tier chain |
| `get_network_history(limit)` | Recent diagnoses and any repeating pattern detected across them |
| `restart_network_service(service_name, confirm)` | Restarts a whitelisted service (`NetworkManager`, `dnsmasq`, `systemd-resolved`); dry-run unless `confirm=True` |

### Tool orchestration

`diagnose_network_issue` doesn't run every diagnostic every time. It always
collects a fast baseline (connectivity + bandwidth), then asks Gemini which
*extra* checks — interface health, connected devices — are actually relevant
to the specific question, and only runs those. The response includes
`extra_tools_used` so this decision is visible, not hidden. If no Gemini key
is configured, it safely defaults to running everything rather than skipping
diagnostics it can't intelligently choose between.

### Session history and pattern detection

Every diagnosis is recorded to a local SQLite database (`history.py`, no new
dependency, zero cost). Future calls fold in a summary of recent patterns —
"the router failed to respond in 2 of the last 3 checks" — so NetGuardian can
speak to trends over time instead of treating every question in total
isolation.

## 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).