v0.4.20-beta: beta launch — new screenshots, CONTRIBUTING, SECURITY, beta badge

Author: DAB-LABS

.gitignore

@@ -18,6 +18,7 @@ __pycache__/
 
 # Local
 revisions/
+temp/
 
 # OS
 .DS_Store

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to SMART Sniffer
+
+Thanks for your interest in contributing! SMART Sniffer is in beta and we welcome bug reports, drive compatibility data, and code contributions.
+
+## Reporting Bugs
+
+[Open an issue](https://github.com/DAB-LABS/smart-sniffer/issues) with:
+
+- What you expected to happen vs. what actually happened
+- Your setup: OS, HA version, agent version, how the agent was installed
+- Relevant logs from the agent (`journalctl -u smartha-agent -f` on Linux) or HA (Settings > System > Logs)
+
+## Submitting Drive Data
+
+The most valuable contribution you can make is a `smartctl` dump from a drive we haven't tested against. This helps us catch manufacturer-specific attribute name variants that would otherwise be invisible.
+
+```bash
+sudo smartctl -a --json /dev/sdX > my-drive-dump.json
+```
+
+Attach the JSON file to an issue or PR. Feel free to redact the serial number if you prefer. The fields we care about most are the attribute names and the JSON structure, not identifying information.
+
+See [docs/smart-attribute-name-variants.md](docs/smart-attribute-name-variants.md) for the current mapping and known gaps.
+
+## Development Setup
+
+### Agent (Go)
+
+```bash
+cd agent
+go build -o smartha-agent .
+sudo ./smartha-agent --port 9099
+```
+
+Requires Go 1.22+ and `smartmontools` installed.
+
+### Integration (Python / Home Assistant)
+
+Copy `custom_components/smart_sniffer/` into your HA development instance's `custom_components/` directory. Restart HA to pick up changes.
+
+For testing without real drives, use the [Mock Agent](docs/mock-agent.md):
+
+```bash
+python3 tools/mock-agent.py --port 9100 --preload sata_hdd,nvme,usb_blocked
+```
+
+### Key Files
+
+| File | What it does |
+|------|-------------|
+| `agent/main.go` | HTTP server, smartctl execution, caching, mDNS |
+| `agent/config.go` | Config loading (YAML + CLI flags) |
+| `custom_components/smart_sniffer/attention.py` | Attention state classification logic |
+| `custom_components/smart_sniffer/sensor.py` | All sensor entities + extraction |
+| `custom_components/smart_sniffer/coordinator.py` | Data polling + notification lifecycle |
+| `custom_components/smart_sniffer/config_flow.py` | HA config flow + Zeroconf discovery |
+
+## Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Test against the mock agent if touching the integration
+4. Test with `go build` if touching the agent
+5. Open a PR with a clear description of what and why
+
+Keep PRs focused — one feature or fix per PR. If you're planning something large, open an issue first to discuss the approach.
+
+## Code Style
+
+- **Go agent:** Standard `gofmt` formatting
+- **Python integration:** Follow existing patterns in the codebase. Type hints are used throughout. No external dependencies (stdlib + HA core only).
+
+## What's Needed
+
+Check the [roadmap](README.md#roadmap) and [known issues](docs/build-journal.md#known-issues--tech-debt) for ideas. Some areas where help is especially welcome:
+
+- **Windows testing** — `install.ps1` builds but hasn't been validated end-to-end
+- **SAS/SCSI drive support** — we need `smartctl -a --json` dumps from SAS drives
+- **Drive-specific `smartctl` dumps** — any manufacturer or model we haven't seen
+- **Integration icons** — design help for the HA brands repo PR

README.md

@@ -7,6 +7,7 @@
 
 <p align="center">
   <a href="https://github.com/DAB-LABS/smart-sniffer/releases/latest"><img src="https://img.shields.io/github/v/release/DAB-LABS/smart-sniffer?style=flat-square" alt="Release"></a>
+  <img src="https://img.shields.io/badge/status-beta-orange?style=flat-square" alt="Beta">
   <a href="https://github.com/DAB-LABS/smart-sniffer/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/DAB-LABS/smart-sniffer/release.yml?style=flat-square&label=build" alt="Build"></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/DAB-LABS/smart-sniffer?style=flat-square" alt="License"></a>
 </p>
@@ -114,20 +115,36 @@ Every drive on the machine appears as its own HA device.
 
 <table>
   <tr>
-    <td align="center"><strong>SATA SSD — Sensors</strong></td>
-    <td align="center"><strong>Apple NVMe — Sensors</strong></td>
+    <td align="center"><strong>NVMe SSD — Sensors</strong></td>
+    <td align="center"><strong>NVMe SSD — Diagnostics</strong></td>
   </tr>
   <tr>
-    <td><img src="images/sensors-samsung-screenshot.png" width="320"></td>
-    <td><img src="images/sensors-apple-screenshot.png" width="320"></td>
+    <td><img src="images/nvme-sensors.png" width="300"></td>
+    <td><img src="images/nvme-diagnostics.png" width="300"></td>
   </tr>
   <tr>
+    <td align="center"><strong>SATA SSD — Sensors</strong></td>
     <td align="center"><strong>SATA SSD — Diagnostics</strong></td>
-    <td align="center"><strong>Apple NVMe — Diagnostics</strong></td>
   </tr>
   <tr>
-    <td><img src="images/diag-samsung-screenshot.png" width="320"></td>
-    <td><img src="images/diag-apple-screenshot.png" width="320"></td>
+    <td><img src="images/sata-ssd-sensors.png" width="300"></td>
+    <td><img src="images/sata-ssd-diagnostics.png" width="300"></td>
+  </tr>
+  <tr>
+    <td align="center"><strong>Attention: YES (Critical)</strong></td>
+    <td align="center"><strong>Trigger Reason in Diagnostics</strong></td>
+  </tr>
+  <tr>
+    <td><img src="images/attention-yes-sensors.png" width="300"></td>
+    <td><img src="images/attention-yes-diagnostics.png" width="300"></td>
+  </tr>
+  <tr>
+    <td align="center"><strong>Attention: MAYBE (Warning)</strong></td>
+    <td align="center"><strong>Warning Reason in Diagnostics</strong></td>
+  </tr>
+  <tr>
+    <td><img src="images/attention-maybe-sensors.png" width="300"></td>
+    <td><img src="images/attention-maybe-diagnostics.png" width="300"></td>
   </tr>
 </table>
 
@@ -289,9 +306,21 @@ Binaries output to `agent/build/`.
 - [ ] Configurable alert thresholds via options flow
 - [ ] SAS/SCSI drive support
 
+## Testing
+
+The integration has been tested against the included [Mock Agent](docs/mock-agent.md) — a standalone Python tool that simulates a `smartha-agent` with fully controllable fake drives. It serves the same API as the real agent, with a web dashboard for changing SMART attributes in real time. Useful for validating attention state transitions, notification behavior, and new drive types without waiting for real hardware to degrade.
+
+```bash
+python3 tools/mock-agent.py --port 9100 --preload sata_hdd,nvme,usb_blocked
+```
+
+Point the HA integration at `localhost:9100` and you're testing.
+
 ## Contributing
 
-Found a bug? Have a drive that isn't mapping correctly? [Open an issue.](https://github.com/DAB-LABS/smart-sniffer/issues) Drive-specific `smartctl -a --json` output samples are especially welcome — they help us catch manufacturer name variants we haven't seen yet.
+Found a bug? Have a drive that isn't mapping correctly? See [CONTRIBUTING.md](CONTRIBUTING.md) for how to help.
+
+Drive-specific `smartctl -a --json` output samples are especially welcome — they help us catch manufacturer name variants we haven't seen yet.
 
 ---
 

SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in SMART Sniffer, please report it responsibly.
+
+**Email:** david.a.bailey@gmail.com
+
+**Do not** open a public GitHub issue for security vulnerabilities. Please use email so we can assess and address the issue before public disclosure.
+
+## What to Include
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if you have one)
+
+## Scope
+
+SMART Sniffer handles bearer token authentication between the agent and Home Assistant integration. Security-relevant areas include:
+
+- **Token handling** in the Go agent (`agent/main.go`) and HA integration (`coordinator.py`, `config_flow.py`)
+- **HTTP server** exposure — the agent listens on a configurable port and serves drive health data
+- **Installer scripts** (`install.sh`, `install.ps1`) — these run with elevated privileges and download binaries from GitHub
+
+## Response
+
+We aim to acknowledge reports within 48 hours and provide a fix or mitigation plan within 7 days for confirmed vulnerabilities.

custom_components/smart_sniffer/manifest.json

@@ -9,6 +9,6 @@
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/DAB-LABS/smart-sniffer/issues",
   "requirements": [],
-  "version": "0.3.0",
+  "version": "0.4.20",
   "zeroconf": [{"type": "_smartha._tcp.local."}]
 }