{"id":50354099,"url":"https://github.com/krisarmstrong/seed","last_synced_at":"2026-05-29T22:00:36.840Z","repository":{"id":358146216,"uuid":"1108961448","full_name":"krisarmstrong/seed","owner":"krisarmstrong","description":"Portable network diagnostic appliance — real-time link, switch, DHCP, DNS, Wi-Fi, and security posture from any network jack.","archived":false,"fork":false,"pushed_at":"2026-05-23T00:48:23.000Z","size":76207,"stargazers_count":1,"open_issues_count":342,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T01:22:39.634Z","etag":null,"topics":["cisa-kev","cve","go","hipaa","network-diagnostics","network-monitoring","network-tools","raspberry-pi","security","wifi"],"latest_commit_sha":null,"homepage":"https://mustardseednetworks.com/seed","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krisarmstrong.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-03T06:38:02.000Z","updated_at":"2026-05-23T00:48:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/krisarmstrong/seed","commit_stats":null,"previous_names":["krisarmstrong/seed"],"tags_count":327,"template":false,"template_full_name":null,"purl":"pkg:github/krisarmstrong/seed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krisarmstrong%2Fseed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krisarmstrong%2Fseed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krisarmstrong%2Fseed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krisarmstrong%2Fseed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krisarmstrong","download_url":"https://codeload.github.com/krisarmstrong/seed/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krisarmstrong%2Fseed/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33672125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cisa-kev","cve","go","hipaa","network-diagnostics","network-monitoring","network-tools","raspberry-pi","security","wifi"],"created_at":"2026-05-29T22:00:25.219Z","updated_at":"2026-05-29T22:00:36.830Z","avatar_url":"https://github.com/krisarmstrong.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Seed\n\n\u003e Portable network diagnostic appliance with real-time web UI.\n\n[![CI](https://github.com/krisarmstrong/seed/actions/workflows/ci.yml/badge.svg)](https://github.com/krisarmstrong/seed/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/krisarmstrong/seed?logo=github)](https://github.com/krisarmstrong/seed/releases/latest)\n[![CodeQL](https://github.com/krisarmstrong/seed/actions/workflows/codeql.yml/badge.svg)](https://github.com/krisarmstrong/seed/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/krisarmstrong/seed/badge)](https://scorecard.dev/viewer/?uri=github.com/krisarmstrong/seed)\n[![Go Reference](https://pkg.go.dev/badge/github.com/krisarmstrong/seed.svg)](https://pkg.go.dev/github.com/krisarmstrong/seed)\n[![Go Report Card](https://goreportcard.com/badge/github.com/krisarmstrong/seed)](https://goreportcard.com/report/github.com/krisarmstrong/seed)\n[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)\n\nThe Seed is a network diagnostic appliance from **Mustard Seed Networks**.\nPlug it into any network jack and the web UI shows link status, switch\ninformation, DHCP/DNS health, gateway reachability, Wi-Fi survey data, and\nsecurity posture in real time. Built to run on a Raspberry Pi or any modern\nLinux box.\n\n## Modules\n\n| Module | Purpose | Color |\n|--------|---------|-------|\n| **Roots** | Path analysis, traceroute, deep connectivity | Amber |\n| **Canopy** | Wi-Fi planning, surveys, coverage heat maps | Green |\n| **Shell** | Security posture, hardening, vulnerability checks | Orange |\n| **Sap** | Live telemetry, monitoring, data flow | Cyan |\n| **Harvest** | Reporting, compliance, exports | Gold |\n\n## Features\n\n- **Real-time diagnostics** — live updates over WebSocket\n- **Link status** — speed, duplex, advertised capabilities, flap counts\n- **Switch discovery** — LLDP / CDP / EDP / FDP / Foundry\n- **DHCP analysis** — phase timing breakdown (Discover/Offer/Request/Ack)\n- **DNS testing** — forward + reverse lookups with timing\n- **Gateway health** — ping, traceroute, latency tracking\n- **VLAN detection** — tagged and native VLAN identification\n- **Wi-Fi** — signal strength, channel survey, security info (nl80211)\n- **Path discovery** — multi-hop topology mapping\n- **Health checks** — TCP / UDP / HTTP probes with thresholds\n- **Vulnerability scanning** — CISA KEV + CVE feeds\n- **Threshold alerts** — configurable green / yellow / red indicators\n- **Modern UI** — Tailwind v4 design system, dark/light themes, mobile-responsive\n- **i18n-ready** — translated UI namespaces\n- **Secure** — HTTPS by default with self-signed cert; password-only after first-run setup\n\n## Quick Start\n\n### Prerequisites\n\n- Linux (Raspberry Pi 4 or any modern x86/arm64 box)\n- Go 1.26+\n- Node.js 26+\n- libpcap-dev\n\n### Hardware notes\n\n| Capability | Recommended adapter |\n|------------|---------------------|\n| Basic diagnostics | any |\n| Wi-Fi survey | nl80211-compatible (Intel AX200/210) |\n| Cable diagnostics (TDR) | Intel I350/I210 or Broadcom BCM5719/5720 |\n\nSee [HARDWARE.md](HARDWARE.md) for the full compatibility matrix.\n\nThe Seed needs raw-socket access for diagnostics. On Linux either:\n\n```bash\n# run as root\nsudo ./seed\n\n# or grant capabilities once\nsudo setcap cap_net_raw,cap_net_admin=+ep ./seed\n./seed\n```\n\n### Install + run\n\n```bash\ngit clone https://github.com/krisarmstrong/seed.git\ncd seed\nmake build            # builds frontend + backend in one step\nsudo ./seed           # listens on https://localhost:8443\n```\n\nOr grab a package from the [releases page](https://github.com/krisarmstrong/seed/releases)\n(`.deb`, `.rpm`, macOS `.pkg`, Windows `.zip`) or install via Homebrew:\n\n```bash\nbrew install krisarmstrong/tap/seed\n```\n\n### First run\n\n1. Open `https://\u003cdevice-ip\u003e:8443` (accept the self-signed cert).\n2. Walk the first-run setup wizard to create the admin password — there is\n   no shipped default password.\n\n### First-time TLS trust setup (optional)\n\nSeed serves its UI over HTTPS with a self-signed certificate. To eliminate\nthe browser warning, install that certificate into your OS trust store:\n\n```bash\nsudo seed install-ca\n```\n\nThis adds seed's root certificate to the macOS Keychain, the Linux system\nCA bundle (Debian/Ubuntu via `update-ca-certificates`, RHEL/Fedora via\n`update-ca-trust`), or the Windows Certificate Store. After the install\ncommand finishes it prints the certificate's SHA-256 fingerprint. Compare\nit against what your browser shows (\"View certificate → Details →\nFingerprints\") and against the value served at `/__version`:\n\n```bash\nseed install-ca --print-fingerprint\ncurl -k https://localhost:8443/__version | jq -r .tlsFingerprint\n```\n\nThe two values must match.\n\nTo remove the certificate from the trust store:\n\n```bash\nsudo seed install-ca --uninstall\n```\n\n## Configuration\n\n`seed.yaml` (and `SEED_*` env vars) configure the appliance:\n\n```yaml\nserver:\n  port: 8443      # HTTPS\n  https: true\n\ninterface:\n  default: eth0\n\nthresholds:\n  dhcp:  { warning: 500ms, critical: 2s }\n  dns:   { warning: 100ms, critical: 500ms }\n  ping:  { warning:  50ms, critical: 200ms }\n```\n\nCommon environment overrides:\n\n```bash\nSEED_HTTP_PORT=8443\nSEED_LOG_LEVEL=info       # debug | info | warn | error\nSEED_DB_PATH=/var/lib/seed/data.db\n```\n\n## Architecture\n\n```\nui/src/              → React/TypeScript frontend (Vite)\n                            ↓ npm run build\ninternal/api/ui/     → Built assets (embedded via go:embed)\n                            ↓\ncmd/seed/            → Entry point\ninternal/\n├── api/             → HTTP/WebSocket handlers\n├── database/        → SQLite store + migrations\n├── network/         → Link, DHCP, DNS, Wi-Fi, cable, path probes\n├── config/          → YAML + env loading\n├── auth/            → JWT + first-run setup\n├── telemetry/       → Metrics, structured logging\n├── i18n/locales/    → Translation namespaces\n└── version/         → Build metadata (injected via ldflags)\n```\n\nThe frontend builds **directly into `internal/api/ui/`** and is embedded\nvia `//go:embed` — no copy step, no runtime dependency on the source tree.\n\n## Build\n\n| Command | Purpose |\n|---------|---------|\n| `make build` | Full build (frontend + backend) |\n| `make test` | Go + frontend unit/integration tests |\n| `make test-e2e` | Playwright UI tests |\n| `make lint` | golangci-lint + Biome |\n| `make security` | govulncheck + gosec + npm audit + gitleaks |\n| `make fmt-check` | Format check (Go + TS) |\n| `make fmt-all` | Auto-format everything |\n| `make packages` | `.deb` + `.rpm` via GoReleaser |\n| `make pkg` | macOS `.pkg` |\n| `make verify` | Full local CI gate (lint + test + security + build) |\n\nFrontend-only iteration:\n```bash\ncd ui\nnpm run dev          # http://localhost:3000 with proxy to backend\nnpm run lint\nnpm run test\nnpm run e2e\n```\n\nVerified versions: **Go 1.26.3**, Node.js 26, golangci-lint v2.12.1.\nCross-platform releases (linux/macOS/windows × amd64/arm64) are built by\n`release.yml` on tag push and signed with cosign keyless OIDC.\n\n## Container\n\n```bash\ndocker run --rm --net host --cap-add NET_RAW --cap-add NET_ADMIN \\\n  ghcr.io/krisarmstrong/seed:latest\n```\n\nMulti-arch images (linux/amd64, linux/arm64) built on native runners with\nSLSA-3 provenance and Syft-generated SBOM.\n\n## Frontend design system\n\nThe UI uses a Tailwind v4 CSS-first theme with semantic tokens:\n\n- [`ui/src/styles/DESIGN_SYSTEM.md`](ui/src/styles/DESIGN_SYSTEM.md) —\n  full token reference (colors, typography, spacing, components)\n- [`STYLE_GUIDE.md`](STYLE_GUIDE.md) — coding conventions\n\n## Versioning \u0026 Releases\n\nConventional commits drive [release-please](https://github.com/googleapis/release-please).\nTags trigger `release.yml` which builds binaries, packages, container\nimages, and (when configured) updates the Homebrew tap.\n\n## License\n\n[Business Source License 1.1](LICENSE) — free for non-commercial use;\ncommercial use requires a license. Converts to Apache-2.0 on the change\ndate stated in the LICENSE file.\n\nFor commercial licensing inquiries: `kris.armstrong@icloud.com`.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the vulnerability-disclosure policy.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Related projects\n\nThe Seed is the diagnostic appliance. Two sibling tools complete the\nMustard Seed Networks testing toolkit:\n\n- **[stem](https://github.com/krisarmstrong/stem)** — RFC-compliant network performance testing\n- **[niac-go](https://github.com/krisarmstrong/niac-go)** — network device simulator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrisarmstrong%2Fseed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrisarmstrong%2Fseed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrisarmstrong%2Fseed/lists"}