add prometheus export

README.md

@@ -1,22 +1,82 @@
 # mac_watcher
 
-Scrape the MAC table from HP ProCurve switch and altert if a untrusted MAC is found.
+Polls a switch MAC address table via SNMP. Sends email alerts for unknown MACs. Exposes a Prometheus metrics endpoint reflecting the current switch state.
 
+## Requirements
 
-## Overview ##
-Scrape all known MAC addresses via snmp from a HP ProCurve switch.
-If a reported MAC is not i a white list, a alert is sent via email.
+- Debian Linux
+- Python 3.11+
+- `snmpwalk` (`apt install snmp`)
+- Python dependencies: `pip install -r requirements.txt --break-system-packages`
 
+## Install
 
-## Install ##
+```
+apt install snmp
+cd /opt
+git clone https://git.mosad.xyz/localhorst/mac_watcher.git
+cd /opt/mac_watcher
+pip install -r requirements.txt --break-system-packages
+```
 
-- `pip install mac-vendor-lookup`
-- `cd /opt/`
-- `git clone https://git.mosad.xyz/localhorst/mac_watcher.git`
-- `cd /opt/mac_watcher/`
-- Set the constants in `config.py`
-- `chmod +x /opt/mac_watcher/mac_watcher.py` 
-- `cp scripts/mac-watcher.service /etc/systemd/system/mac-watcher.service`
-- `systemctl daemon-reload && systemctl enable --now mac-watcher.service`
+Edit `config.py` and set all values.
 
+```
+chmod +x /opt/mac_watcher/mac_watcher.py
+cp scripts/mac-watcher.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now mac-watcher.service
+```
 
+## Configuration
+
+All settings are in `config.py`.
+
+| Setting | Description |
+|---|---|
+| `switch_ip_addr` | IP of the managed switch |
+| `switch_snmp_community` | SNMP v2c community string |
+| `snmp_poll_interval` | Seconds between polls |
+| `snmpwalk_bin` | Full path to `snmpwalk` binary |
+| `trusted_mac_addresses` | Known/allowed MACs — case-insensitive, normalized at startup |
+| `vendor_cache_file` | Path to persistent vendor cache JSON |
+| `exporter_host` | Bind address for Prometheus exporter |
+| `exporter_port` | Port for Prometheus exporter |
+| `exporter_prefix` | Metric name prefix |
+| `mail_*` | SMTP credentials and recipients |
+
+## Prometheus Metrics
+
+Endpoint: `http://<host>:<exporter_port>/metrics`
+
+### Device presence
+
+Single gauge reflecting the **last SNMP readout as-is**. Every MAC currently in the switch table is emitted with value `1`. MACs from previous readouts that are no longer present are dropped. Between startup and the first successful poll no device series are emitted.
+
+```
+mac_watcher_device_present{mac="AA:BB:CC:DD:EE:FF",trusted="true"}  1
+mac_watcher_device_present{mac="11:22:33:44:55:66",trusted="false"} 1
+```
+
+The `trusted` label reflects whether the MAC is in `trusted_mac_addresses`.
+
+### Exporter / cache statistics
+
+```
+mac_watcher_exporter_uptime_seconds
+mac_watcher_exporter_requests_total
+mac_watcher_snmp_polls_total
+mac_watcher_vendor_cache_size
+mac_watcher_vendor_cache_hits_total
+mac_watcher_vendor_cache_misses_total
+```
+
+### prometheus.yml example
+
+```yaml
+scrape_configs:
+  - job_name: 'mac_watcher'
+    static_configs:
+      - targets: ['localhost:9200']
+    scrape_interval: 60s
+```