networking · diff
git:20260313.e5b700b to git:20260313.02a8e7c
153 added, 198 removed. Audit A to A.
---
name: networking
description: >-
Network infrastructure for self-hosted environments: VLANs, firewalls (nftables,
OPNsense, pfSense), DNS (Pi-hole, AdGuard Home, split-horizon), reverse proxies
(Caddy, Traefik, Nginx Proxy Manager), VPN (WireGuard, Tailscale), TLS/SSL
certificate management, DHCP, and security hardening. Invoke when task involves
any interaction with network configuration — designing, implementing, debugging,
reviewing, or planning network architecture.
---
# Networking
- Security is a non-negotiable default, not an optional add-on. Every network design
- decision must account for trust boundaries.
+ Security is a non-negotiable default, not an optional add-on. Every network design decision must account for trust
+ boundaries.
## References
- Extended configuration examples, comparison tables, and detailed patterns for the
- rules below live in `${CLAUDE_SKILL_DIR}/references/`.
+ Extended configuration examples, comparison tables, and detailed patterns for the rules below live in
+ `${CLAUDE_SKILL_DIR}/references/`.
- | Topic | Reference | Contents |
- |-------|-----------|----------|
- | VLAN design, trunk/access ports, inter-VLAN policy, Layer 2 security | [`${CLAUDE_SKILL_DIR}/references/vlan-segmentation.md`] | Segment table, firewall rule matrix, hardware requirements, DHCP snooping, DAI, port security, L2 attack mitigation |
- | nftables syntax, OPNsense/pfSense hardening, IPv6 firewall rules | [`${CLAUDE_SKILL_DIR}/references/firewall-rules.md`] | Chain types/hooks/priorities, connection tracking, NAT, rate limiting, sets/maps, ICMPv6 policy, dual-stack rules |
- | Pi-hole, AdGuard Home, split-horizon, mDNS, Unbound, DoH/DoT | [`${CLAUDE_SKILL_DIR}/references/dns-architecture.md`] | Tool comparison table, deployment patterns, Avahi reflector config, recursive vs authoritative, encrypted DNS, IPv6 DNS |
- | Caddy, Traefik, Nginx Proxy Manager, Cloudflare tunnels | [`${CLAUDE_SKILL_DIR}/references/reverse-proxy.md`] | Caddyfile examples, Traefik Docker labels, decision matrix, snippet patterns, tunnel patterns, auth proxy integration |
- | WireGuard, Tailscale, Headscale, site-to-site, HA with OSPF | [`${CLAUDE_SKILL_DIR}/references/vpn-tunnels.md`] | Config examples, topology comparison, subnet router, hybrid WG+TS, HA failover with BIRD/OSPF |
- | Let's Encrypt, ACME, wildcard certs, acme.sh | [`${CLAUDE_SKILL_DIR}/references/tls-certificates.md`] | Challenge types table, ACME client comparison, certificate storage patterns, TLS config |
- | SSH, fail2ban, CrowdSec, IDS/IPS, monitoring, hardening | [`${CLAUDE_SKILL_DIR}/references/security-hardening.md`] | sshd_config, SSH CA, fail2ban vs CrowdSec, Suricata IDS, Prometheus stack, monitoring metrics, IPv6 hardening |
- | Authelia, Authentik, forward auth, SSO patterns | [`${CLAUDE_SKILL_DIR}/references/auth-proxies.md`] | Authelia vs Authentik comparison, ForwardAuth with Traefik/Caddy, SSO/MFA patterns, deployment guidance |
+ | Topic | Reference | Contents |
+ | -------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+ | VLAN design, trunk/access ports, inter-VLAN policy, Layer 2 security | [`${CLAUDE_SKILL_DIR}/references/vlan-segmentation.md`] | Segment table, firewall rule matrix, hardware requirements, DHCP snooping, DAI, port security, L2 attack mitigation |
+ | nftables syntax, OPNsense/pfSense hardening, IPv6 firewall rules | [`${CLAUDE_SKILL_DIR}/references/firewall-rules.md`] | Chain types/hooks/priorities, connection tracking, NAT, rate limiting, sets/maps, ICMPv6 policy, dual-stack rules |
+ | Pi-hole, AdGuard Home, split-horizon, mDNS, Unbound, DoH/DoT | [`${CLAUDE_SKILL_DIR}/references/dns-architecture.md`] | Tool comparison table, deployment patterns, Avahi reflector config, recursive vs authoritative, encrypted DNS, IPv6 DNS |
+ | Caddy, Traefik, Nginx Proxy Manager, Cloudflare tunnels | [`${CLAUDE_SKILL_DIR}/references/reverse-proxy.md`] | Caddyfile examples, Traefik Docker labels, decision matrix, snippet patterns, tunnel patterns, auth proxy integration |
+ | WireGuard, Tailscale, Headscale, site-to-site, HA with OSPF | [`${CLAUDE_SKILL_DIR}/references/vpn-tunnels.md`] | Config examples, topology comparison, subnet router, hybrid WG+TS, HA failover with BIRD/OSPF |
+ | Let's Encrypt, ACME, wildcard certs, acme.sh | [`${CLAUDE_SKILL_DIR}/references/tls-certificates.md`] | Challenge types table, ACME client comparison, certificate storage patterns, TLS config |
+ | SSH, fail2ban, CrowdSec, IDS/IPS, monitoring, hardening | [`${CLAUDE_SKILL_DIR}/references/security-hardening.md`] | sshd_config, SSH CA, fail2ban vs CrowdSec, Suricata IDS, Prometheus stack, monitoring metrics, IPv6 hardening |
+ | Authelia, Authentik, forward auth, SSO patterns | [`${CLAUDE_SKILL_DIR}/references/auth-proxies.md`] | Authelia vs Authentik comparison, ForwardAuth with Traefik/Caddy, SSO/MFA patterns, deployment guidance |
## VLAN Segmentation
### Segment by Trust Level
Separate traffic into functional zones based on trust, not device count:
- **Management** (VLAN 10): Hypervisors, switches, routers, IPMI/iLO -- highest trust
- **Trusted/Lab** (VLAN 20): VMs, containers, workstation -- high trust
- **IoT** (VLAN 30): Smart devices, cameras, sensors -- low trust, restricted
- **Guest** (VLAN 40): Visitor devices -- zero trust, internet only
- **Storage** (VLAN 50): NAS, iSCSI, backup targets -- high trust, limited access
- **DMZ** (VLAN 99): Publicly exposed services -- medium trust, no inward access
- Start with 3-4 VLANs. Add more only with a clear security or performance reason.
- Over-segmentation adds complexity without proportional benefit. Separate
- production self-hosted services from experimental lab services -- prevent
+ Start with 3-4 VLANs. Add more only with a clear security or performance reason. Over-segmentation adds complexity
+ without proportional benefit. Separate production self-hosted services from experimental lab services -- prevent
experimentation from causing downtime for household-facing apps.
### Inter-VLAN Policy
- VLANs without firewall rules provide zero security benefit. Every VLAN boundary
- needs explicit allow/deny policy. Default deny between all VLANs, then explicitly
- allow required flows. Always permit established/related return traffic.
+ VLANs without firewall rules provide zero security benefit. Every VLAN boundary needs explicit allow/deny policy.
+ Default deny between all VLANs, then explicitly allow required flows. Always permit established/related return traffic.
### Infrastructure Requirements
- Managed (VLAN-aware) switches with 802.1Q support
- Router/firewall capable of VLAN termination and inter-VLAN routing
- Access points with per-SSID VLAN tagging
- Set native VLAN on trunks to an unused VLAN (not VLAN 1)
## Firewalls
### nftables
Modern Linux firewall replacing iptables. Use `inet` family for dual-stack rules.
- Core structure: **tables** contain **chains**, chains contain **rules**. Base chains
- attach to Netfilter hooks (`input`, `forward`, `output`, `prerouting`, `postrouting`).
+ Core structure: **tables** contain **chains**, chains contain **rules**. Base chains attach to Netfilter hooks (`input`,
+ `forward`, `output`, `prerouting`, `postrouting`).
Minimal host firewall:
```nft
table inet filter {
chain input {
type filter hook input priority filter; policy drop;
ct state established,related accept
ct state invalid drop
iifname "lo" accept
icmp type echo-request accept
icmpv6 type { echo-request, nd-neighbor-solicit, nd-router-advert } accept
tcp dport { ssh } accept
}
chain forward {
type filter hook forward priority filter; policy drop;
}
chain output {
type filter hook output priority filter; policy accept;
}
}
```
Key rules:
- - Place `ct state established,related accept` early in input/forward chains --
- handles bulk of traffic efficiently
+
+ - Place `ct state established,related accept` early in input/forward chains -- handles bulk of traffic efficiently
- Drop `ct state invalid` packets explicitly
- Use `policy drop` on input and forward chains (default deny)
- Use `policy accept` on output chains (restrict outbound only when needed)
- - `accept` is not final across chains -- later chains at the same hook still
- evaluate. `drop` is always final.
+ - `accept` is not final across chains -- later chains at the same hook still evaluate. `drop` is always final.
- Use `counter` on rules during development to verify traffic is hitting them
- - Persist rules: `nft list ruleset > /etc/nftables.conf`, enable
- `nftables.service`
+ - Persist rules: `nft list ruleset > /etc/nftables.conf`, enable `nftables.service`
### OPNsense / pfSense
- GUI-managed firewalls. Rules evaluate top-to-bottom, first match wins.
- Place more specific rules (e.g., block-LAN) above general rules (e.g.,
- allow-internet) -- rule ordering mistakes are the most common cause of
- VLAN isolation failures.
+ GUI-managed firewalls. Rules evaluate top-to-bottom, first match wins. Place more specific rules (e.g., block-LAN) above
+ general rules (e.g., allow-internet) -- rule ordering mistakes are the most common cause of VLAN isolation failures.
Post-install hardening (first 30 minutes):
+
1. Change default admin password
2. Enable 2FA (OPNsense: built-in; pfSense: package)
3. Disable web UI access from WAN
4. Configure DNS over TLS upstream
5. Enable automatic config backups
6. Restrict RFC1918 on WAN interface
- 7. Restrict DNS resolver to internal interfaces only (default allows
- queries from all interfaces -- open resolvers get abuse complaints)
+ 7. Restrict DNS resolver to internal interfaces only (default allows queries from all interfaces -- open resolvers get
+ abuse complaints)
- OPNsense has faster security patches and built-in 2FA. pfSense has a larger
- community knowledge base. Security posture depends more on configuration than
- platform choice.
+ OPNsense has faster security patches and built-in 2FA. pfSense has a larger community knowledge base. Security posture
+ depends more on configuration than platform choice.
- Throughput problems after install: disable hardware offloading (CRC, TSO,
- LRO) first -- this is the most common culprit in virtualized environments.
- If still slow, check IDS rulesets -- too many active rules kill performance.
- Start with 2-3 rulesets, add more only as needed.
+ Throughput problems after install: disable hardware offloading (CRC, TSO, LRO) first -- this is the most common culprit
+ in virtualized environments. If still slow, check IDS rulesets -- too many active rules kill performance. Start with 2-3
+ rulesets, add more only as needed.
## IPv6
### Dual-Stack Configuration
- Run IPv4 and IPv6 concurrently. Dual-stack doubles the attack surface -- maintain
- identical security policies for both protocols. Use `inet` family in nftables for
- rules that apply to both stacks; use `ip6` only for IPv6-specific rules (ICMPv6,
- neighbor discovery).
+ Run IPv4 and IPv6 concurrently. Dual-stack doubles the attack surface -- maintain identical security policies for both
+ protocols. Use `inet` family in nftables for rules that apply to both stacks; use `ip6` only for IPv6-specific rules
+ (ICMPv6, neighbor discovery).
### ICMPv6 Firewall Policy
- ICMPv6 is essential for IPv6 operation -- blocking all ICMPv6 breaks the network.
- Apply granular filtering:
+ ICMPv6 is essential for IPv6 operation -- blocking all ICMPv6 breaks the network. Apply granular filtering:
- - **Must allow transit**: Destination Unreachable (Type 1), Packet Too Big (Type 2),
- Time Exceeded (Type 3) -- required for PMTU discovery and communication
- - **Link-local only**: Router/Neighbor Solicitation and Advertisement (Types 133-136)
- -- critical for local discovery, must never cross network boundaries
+ - **Must allow transit**: Destination Unreachable (Type 1), Packet Too Big (Type 2), Time Exceeded (Type 3) -- required
+ for PMTU discovery and communication
+ - **Link-local only**: Router/Neighbor Solicitation and Advertisement (Types 133-136) -- critical for local discovery,
+ must never cross network boundaries
- **Drop invalid**: Drop ICMPv6 from unexpected sources or with malformed headers
### Address Assignment
- - **SLAAC**: Stateless, no server needed. Devices auto-configure from router
- advertisements. Simple but less control.
- - **DHCPv6**: Stateful, centralized address management. Provides DNS server
- addresses. Use for servers requiring fixed addresses.
- - **Privacy extensions**: Randomize interface identifiers to prevent tracking. Enable
- for external communications, disable internally (rotating addresses break logging
- and service correlation).
+ - **SLAAC**: Stateless, no server needed. Devices auto-configure from router advertisements. Simple but less control.
+ - **DHCPv6**: Stateful, centralized address management. Provides DNS server addresses. Use for servers requiring fixed
+ addresses.
+ - **Privacy extensions**: Randomize interface identifiers to prevent tracking. Enable for external communications,
+ disable internally (rotating addresses break logging and service correlation).
### DNS and IPv6
- Add AAAA records only after IPv6 connectivity is verified and working. Premature
- AAAA records cause timeouts when IPv6 is not properly configured. In dual-stack
- environments, test both A and AAAA resolution paths.
+ Add AAAA records only after IPv6 connectivity is verified and working. Premature AAAA records cause timeouts when IPv6
+ is not properly configured. In dual-stack environments, test both A and AAAA resolution paths.
## IDS/IPS
### Suricata
- Network threat detection engine. Performs deep packet inspection and generates
- alerts based on rulesets. OPNsense includes Suricata built-in; pfSense requires
- a package.
+ Network threat detection engine. Performs deep packet inspection and generates alerts based on rulesets. OPNsense
+ includes Suricata built-in; pfSense requires a package.
- Performance impact: enabling 3 rulesets causes ~27% throughput drop. Start with
- 2-3 essential rulesets, add more only as needed. Disable hardware offloading
- (CRC, TSO, LRO) first if throughput is poor -- offloading conflicts with
- packet inspection.
+ Performance impact: enabling 3 rulesets causes ~27% throughput drop. Start with 2-3 essential rulesets, add more only as
+ needed. Disable hardware offloading (CRC, TSO, LRO) first if throughput is poor -- offloading conflicts with packet
+ inspection.
### CrowdSec
- Collaborative security engine that replaces or augments fail2ban. Key
- differences from fail2ban:
+ Collaborative security engine that replaces or augments fail2ban. Key differences from fail2ban:
- | Aspect | fail2ban | CrowdSec |
- |--------|----------|----------|
- | Detection | Regex on local logs | YAML scenarios with leakspeed/capacity |
- | Intelligence | Local only | Community-shared threat data |
- | Remediation | iptables/nftables ban | Bouncers (firewall, Nginx, Traefik) |
- | Configuration | jail.conf | acquis.yaml + Hub collections |
+ | Aspect | fail2ban | CrowdSec |
+ | ------------- | --------------------- | -------------------------------------- |
+ | Detection | Regex on local logs | YAML scenarios with leakspeed/capacity |
+ | Intelligence | Local only | Community-shared threat data |
+ | Remediation | iptables/nftables ban | Bouncers (firewall, Nginx, Traefik) |
+ | Configuration | jail.conf | acquis.yaml + Hub collections |
- Install CrowdSec collections from the Hub for specific services (SSH, Nginx,
- Suricata). Configure whitelists immediately to prevent banning your own IPs.
+ Install CrowdSec collections from the Hub for specific services (SSH, Nginx, Suricata). Configure whitelists immediately
+ to prevent banning your own IPs.
### Suricata + CrowdSec Integration
- Suricata detects threats via packet inspection and logs to `fast.log`. CrowdSec
- parses these logs via `acquis.yaml` and makes blocking decisions. This separates
- detection (Suricata) from remediation (CrowdSec bouncers) -- each tool does what
- it does best.
+ Suricata detects threats via packet inspection and logs to `fast.log`. CrowdSec parses these logs via `acquis.yaml` and
+ makes blocking decisions. This separates detection (Suricata) from remediation (CrowdSec bouncers) -- each tool does
+ what it does best.
## DNS
### DNS Filtering
- Pi-hole and AdGuard Home are DNS sinkholes that block unwanted domains at the
- network level. Point DHCP-advertised DNS at the sinkhole.
+ Pi-hole and AdGuard Home are DNS sinkholes that block unwanted domains at the network level. Point DHCP-advertised DNS
+ at the sinkhole.
- **Pi-hole**: Lighter resource usage, larger community/blocklist ecosystem
- - **AdGuard Home**: Built-in encrypted DNS (DoH/DoT/DoQ), per-client rules, YAML
- config
+ - **AdGuard Home**: Built-in encrypted DNS (DoH/DoT/DoQ), per-client rules, YAML config
- Deploy redundant pairs on separate hosts for resilience. Sync blocklists between
- instances. Avoid using firewall-integrated DNS blocking plugins (e.g.,
- pfBlockerNG) -- a core firewall update can silently break the plugin and
+ Deploy redundant pairs on separate hosts for resilience. Sync blocklists between instances. Avoid using
+ firewall-integrated DNS blocking plugins (e.g., pfBlockerNG) -- a core firewall update can silently break the plugin and
kill all DNS resolution. Run DNS filtering as a separate service.
### Split-Horizon DNS
- Return different DNS answers based on client network. Internal clients resolve
- to private IPs; external clients resolve to public IPs. Implementation:
+ Return different DNS answers based on client network. Internal clients resolve to private IPs; external clients resolve
+ to public IPs. Implementation:
- - Wildcard DNS rewrite in Pi-hole/AdGuard (`*.example.com -> 192.168.1.100`)
- for internal resolution to reverse proxy
- - Separate DNS instances for internal vs external (cleanest separation --
- avoids AdGuard Home's global rewrite problem where a self-hosted DoH
- instance rewrites external queries with internal IPs)
+ - Wildcard DNS rewrite in Pi-hole/AdGuard (`*.example.com -> 192.168.1.100`) for internal resolution to reverse proxy
+ - Separate DNS instances for internal vs external (cleanest separation -- avoids AdGuard Home's global rewrite problem
+ where a self-hosted DoH instance rewrites external queries with internal IPs)
- Conditional forwarding for local domains to internal authoritative server
### mDNS Across VLANs
- mDNS (`.local`) is link-local and does not cross routed boundaries. Use Avahi
- with `enable-reflector=yes` to bridge mDNS between specific VLANs (e.g., trusted
- LAN discovering IoT devices). Restrict interfaces -- never reflect to guest or
+ mDNS (`.local`) is link-local and does not cross routed boundaries. Use Avahi with `enable-reflector=yes` to bridge mDNS
+ between specific VLANs (e.g., trusted LAN discovering IoT devices). Restrict interfaces -- never reflect to guest or
WAN.
### Upstream Encryption
- Always encrypt DNS queries upstream (DNS over TLS or HTTPS) to prevent ISP
- snooping. Configure the recursive resolver to use encrypted upstream; serve
- plain DNS internally.
+ Always encrypt DNS queries upstream (DNS over TLS or HTTPS) to prevent ISP snooping. Configure the recursive resolver to
+ use encrypted upstream; serve plain DNS internally.
## Reverse Proxy
- Single entry point for all HTTP/HTTPS services. Terminates TLS, routes by
- hostname, eliminates per-service port exposure.
+ Single entry point for all HTTP/HTTPS services. Terminates TLS, routes by hostname, eliminates per-service port
+ exposure.
### Tool Selection
- | Factor | Caddy | Traefik | Nginx Proxy Manager |
- |--------|-------|---------|---------------------|
- | Config style | Caddyfile | YAML + Docker labels | Web UI |
- | Auto HTTPS | Default behavior | Via cert resolvers | One-click |
- | Docker-aware | Plugin | Native | No |
- | Learning curve | Low | Medium | Lowest |
- | Best for | Simple setups | Docker/K8s stacks | GUI preference |
+ | Factor | Caddy | Traefik | Nginx Proxy Manager |
+ | -------------- | ---------------- | -------------------- | ------------------- |
+ | Config style | Caddyfile | YAML + Docker labels | Web UI |
+ | Auto HTTPS | Default behavior | Via cert resolvers | One-click |
+ | Docker-aware | Plugin | Native | No |
+ | Learning curve | Low | Medium | Lowest |
+ | Best for | Simple setups | Docker/K8s stacks | GUI preference |
- **Docker-heavy**: Traefik -- discovers containers automatically
- **Simplicity-first**: Caddy -- automatic HTTPS, minimal config
- **GUI management**: Nginx Proxy Manager -- point-and-click
### Architecture Pattern
```
Client --[HTTPS]--> Reverse Proxy --[HTTP]--> Backend Services
```
- Only the reverse proxy needs TLS certificates. Backend services run plain HTTP
- on internal networks. One wildcard certificate covers all services.
+ Only the reverse proxy needs TLS certificates. Backend services run plain HTTP on internal networks. One wildcard
+ certificate covers all services.
### Wildcard Certificates
- Use DNS-01 ACME challenge for wildcard certs (`*.example.com`). Required for
- internal services not reachable from the internet. Caddy and Traefik handle
- this natively with DNS provider plugins.
+ Use DNS-01 ACME challenge for wildcard certs (`*.example.com`). Required for internal services not reachable from the
+ internet. Caddy and Traefik handle this natively with DNS provider plugins.
## Authentication Proxies
### Authelia vs Authentik
- Both provide SSO and MFA for self-hosted services. Choose based on resource
- constraints and protocol needs:
+ Both provide SSO and MFA for self-hosted services. Choose based on resource constraints and protocol needs:
- - **Authelia**: Lightweight (~20 MB image, ~30 MB RAM). YAML-configured, no GUI.
- Supports OIDC, TOTP, WebAuthn, Passkeys. Best for homelabs with limited
- resources needing web SSO.
- - **Authentik**: Full identity provider (~690 MB, requires PostgreSQL). Web GUI
- with user dashboard. Supports OIDC, SAML2, LDAP, RADIUS, SCIM. Best when
- SAML support or a user portal is needed.
+ - **Authelia**: Lightweight (~20 MB image, ~30 MB RAM). YAML-configured, no GUI. Supports OIDC, TOTP, WebAuthn,
+ Passkeys. Best for homelabs with limited resources needing web SSO.
+ - **Authentik**: Full identity provider (~690 MB, requires PostgreSQL). Web GUI with user dashboard. Supports OIDC,
+ SAML2, LDAP, RADIUS, SCIM. Best when SAML support or a user portal is needed.
### Forward Auth Pattern
- Reverse proxies intercept requests and forward headers to the auth server before
- reaching the backend. Traefik uses `ForwardAuth` middleware; Caddy uses similar
- mechanisms. The auth server validates the session and returns 200 (allow) or 401
- (redirect to login).
+ Reverse proxies intercept requests and forward headers to the auth server before reaching the backend. Traefik uses
+ `ForwardAuth` middleware; Caddy uses similar mechanisms. The auth server validates the session and returns 200 (allow)
+ or 401 (redirect to login).
### Deployment
- Gate user-facing services behind auth proxies. Keep admin panels (router, Proxmox,
- NAS) on VPN or management VLAN only -- do not expose through public auth proxies.
- Prefer phishing-resistant MFA (FIDO2/WebAuthn) over TOTP where possible.
+ Gate user-facing services behind auth proxies. Keep admin panels (router, Proxmox, NAS) on VPN or management VLAN only
+ -- do not expose through public auth proxies. Prefer phishing-resistant MFA (FIDO2/WebAuthn) over TOTP where possible.
## Cloudflare Tunnels
### When to Use
- Cloudflare Tunnels expose internal services without opening inbound ports. Useful
- behind CGNAT or when port forwarding is impossible. The `cloudflared` daemon
- initiates outbound connections to Cloudflare's edge.
+ Cloudflare Tunnels expose internal services without opening inbound ports. Useful behind CGNAT or when port forwarding
+ is impossible. The `cloudflared` daemon initiates outbound connections to Cloudflare's edge.
### Architecture Pattern
```
Internet -> Cloudflare Edge -> cloudflared -> Reverse Proxy -> Backend
```
- Route tunnels into a local reverse proxy (Traefik/Caddy) for SSL termination
- and routing. Layer Authelia/Authentik or Cloudflare Access for identity gating.
+ Route tunnels into a local reverse proxy (Traefik/Caddy) for SSL termination and routing. Layer Authelia/Authentik or
+ Cloudflare Access for identity gating.
### When NOT to Use
- **Admin panels**: Router, hypervisor, NAS UIs -- keep on VPN/LAN only
- **Sensitive data services**: Password managers, private document portals
- **LAN-only tools**: Printer dashboards, IoT hubs with weak/no auth
- - **High-bandwidth media**: Jellyfin/Plex through CDN may violate ToS -- disable
- caching for media subdomains if used
+ - **High-bandwidth media**: Jellyfin/Plex through CDN may violate ToS -- disable caching for media subdomains if used
- A tunnel makes services accessible, not secure. Weak credentials, missing MFA,
- or unpatched software remain exploitable regardless of the tunnel.
+ A tunnel makes services accessible, not secure. Weak credentials, missing MFA, or unpatched software remain exploitable
+ regardless of the tunnel.
## VPN
### WireGuard
- Kernel-level VPN protocol. ~4,000 lines of code. Fast, simple, no cipher
- negotiation.
+ Kernel-level VPN protocol. ~4,000 lines of code. Fast, simple, no cipher negotiation.
- Hub-and-spoke topology for remote access VPN
- Site-to-site between fixed endpoints with static IPs
- Requires manual port forwarding (UDP 51820) and key management
- ~5 MB RAM (kernel module)
- - Use when: zero external dependencies required, resource-constrained devices,
- traditional VPN gateway needed
+ - Use when: zero external dependencies required, resource-constrained devices, traditional VPN gateway needed
### Tailscale
Mesh VPN built on WireGuard. Automatic key management, NAT traversal, DNS.
- Full mesh topology -- devices connect directly peer-to-peer
- Zero-config: SSO login, no port forwarding, no config files
- MagicDNS for automatic device name resolution
- Subnet routers expose local networks without per-device installation
- ~30-50 MB RAM (userspace daemon)
- - Use when: multiple devices across networks, NAT traversal needed, want
- managed ACLs and DNS
+ - Use when: multiple devices across networks, NAT traversal needed, want managed ACLs and DNS
### Topology Resilience
- Hub-and-spoke has a single point of failure: if the hub goes down, the
- entire VPN is unreachable. Mesh (Tailscale) is resilient -- nodes remain
- connected to each other even if one fails. Choose topology based on
- failure tolerance, not just convenience.
+ Hub-and-spoke has a single point of failure: if the hub goes down, the entire VPN is unreachable. Mesh (Tailscale) is
+ resilient -- nodes remain connected to each other even if one fails. Choose topology based on failure tolerance, not
+ just convenience.
### Hybrid Pattern
- Run both: Tailscale for day-to-day remote access (mesh, zero-config), WireGuard
- as backup VPN gateway for full-tunnel routing or when Tailscale's coordination
- server is unreachable.
+ Run both: Tailscale for day-to-day remote access (mesh, zero-config), WireGuard as backup VPN gateway for full-tunnel
+ routing or when Tailscale's coordination server is unreachable.
### OpenVPN
- Legacy. Slower, larger attack surface. Choose only when TCP-based tunneling is
- required to bypass UDP-blocking firewalls. For all new deployments, use WireGuard
- or Tailscale.
+ Legacy. Slower, larger attack surface. Choose only when TCP-based tunneling is required to bypass UDP-blocking
+ firewalls. For all new deployments, use WireGuard or Tailscale.
## TLS/SSL Certificates
### ACME and Let's Encrypt
Free, automated certificate issuance. Certificates valid 90 days, renew at 60.
Challenge types:
+
- **HTTP-01**: CA fetches token from port 80. For public-facing servers.
- - **DNS-01**: Client creates TXT record. Required for wildcards and internal
- services.
+ - **DNS-01**: Client creates TXT record. Required for wildcards and internal services.
- **TLS-ALPN-01**: CA connects to port 443. When only 443 is available.
### Recommended Approach
- Let the reverse proxy handle all certificate management. Caddy and Traefik do
- this automatically. For standalone cert management, use acme.sh (shell-only, no
- dependencies, many DNS providers).
+ Let the reverse proxy handle all certificate management. Caddy and Traefik do this automatically. For standalone cert
+ management, use acme.sh (shell-only, no dependencies, many DNS providers).
### TLS Configuration
- Minimum TLS 1.2, prefer TLS 1.3
- Enable HSTS: `Strict-Transport-Security: max-age=31536000; includeSubDomains`
- Enable OCSP stapling when supported
- - Don't manually configure cipher suites unless you have a specific reason --
- modern defaults are optimal
+ - Don't manually configure cipher suites unless you have a specific reason -- modern defaults are optimal
- Monitor certificate expiry (Prometheus blackbox_exporter, Uptime Kuma)
## Security Hardening
### SSH
- Disable password authentication -- key-based only (Ed25519)
- Disable root login -- authenticate as user, then `sudo`
- Restrict agent/X11 forwarding
- - Use CrowdSec or fail2ban as a mitigation layer (not a substitute for
- key-based auth)
- - For fleet management: use SSH Certificate Authority (step-ca) instead of
- distributing authorized_keys. SSH CA issues short-lived certificates (~16h),
- eliminating stale key accumulation. Configure `TrustUserCAKeys` in sshd_config
- to point at the CA public key.
+ - Use CrowdSec or fail2ban as a mitigation layer (not a substitute for key-based auth)
+ - For fleet management: use SSH Certificate Authority (step-ca) instead of distributing authorized_keys. SSH CA issues
+ short-lived certificates (~16h), eliminating stale key accumulation. Configure `TrustUserCAKeys` in sshd_config to
+ point at the CA public key.
### Network Hardening Checklist
- Default deny inbound on all firewall interfaces
- - Filter outbound traffic -- a compromised service with unrestricted
- outbound can exfiltrate data or contact C2 servers. At minimum: allow
- DNS only to designated DNS servers, allow HTTP/HTTPS for updates, block
- all other outbound from IoT and untrusted VLANs
+ - Filter outbound traffic -- a compromised service with unrestricted outbound can exfiltrate data or contact C2 servers.
+ At minimum: allow DNS only to designated DNS servers, allow HTTP/HTTPS for updates, block all other outbound from IoT
+ and untrusted VLANs
- Restrict management interfaces to management VLAN only
- Enable DHCP snooping on managed switches -- prevents rogue DHCP servers
- - Enable Dynamic ARP Inspection (DAI) -- prevents ARP poisoning (requires
- DHCP snooping binding table)
- - Enable port security -- limits MAC addresses per port, prevents CAM
- table overflow attacks
+ - Enable Dynamic ARP Inspection (DAI) -- prevents ARP poisoning (requires DHCP snooping binding table)
+ - Enable port security -- limits MAC addresses per port, prevents CAM table overflow attacks
- Disable DTP on all user-facing ports -- prevents VLAN hopping
- Enable BPDU Guard on access ports -- prevents STP manipulation
- Prefer DHCP reservations over static IPs for centralized management
- Change all default credentials (every device, no exceptions)
- Update firmware on all network devices regularly
- Backup configurations before any change, store off-device
- Disable unused services (UPnP, WPS, SNMP v1/v2 on WAN)
- - For IPv6: maintain identical firewall policies for both stacks, allow
- required ICMPv6 types, disable IPv6 if not actively used
+ - For IPv6: maintain identical firewall policies for both stacks, allow required ICMPv6 types, disable IPv6 if not
+ actively used
- Document network topology and keep diagrams current
### Monitoring
Deploy Prometheus + Grafana for network observability:
+
- **snmp_exporter**: Switch/router metrics via SNMP
- **blackbox_exporter**: Endpoint probing, certificate monitoring
- **node_exporter**: Host-level metrics
- Centralize logs with syslog or Loki+Promtail
- - Use Monit or systemd watchdog to auto-restart critical services (DNS
- resolvers, reverse proxies) -- silent failures cause household-wide outages
+ - Use Monit or systemd watchdog to auto-restart critical services (DNS resolvers, reverse proxies) -- silent failures
+ cause household-wide outages
- Review firewall deny logs weekly during initial setup
## Application
- When **designing** network architecture: propose segmented designs with explicit
- trust boundaries. Default to security-first configurations. Present trade-offs
- between complexity and security.
+ When **designing** network architecture: propose segmented designs with explicit trust boundaries. Default to
+ security-first configurations. Present trade-offs between complexity and security.
- When **implementing** configurations: produce production-ready config files, not
- toy examples. Include comments explaining non-obvious choices. Test connectivity
- after changes.
+ When **implementing** configurations: produce production-ready config files, not toy examples. Include comments
+ explaining non-obvious choices. Test connectivity after changes.
- When **debugging** network issues: start at layer 2 (link/VLAN), work up through
- layer 3 (routing/firewall), then layer 7 (application/proxy). Check firewall deny
- logs first -- they reveal 80% of connectivity issues. Key tools:
+ When **debugging** network issues: start at layer 2 (link/VLAN), work up through layer 3 (routing/firewall), then layer
+ 7 (application/proxy). Check firewall deny logs first -- they reveal 80% of connectivity issues. Key tools:
+
- `ping` / `traceroute` -- reachability and path verification
- `dig` / `nslookup` -- DNS resolution from specific resolvers
- `ss -tlnp` / `netstat` -- listening ports and socket state
- `tcpdump` / `tshark` -- packet captures for traffic flow analysis
- `nft list ruleset` -- verify active firewall rules match intent
- `avahi-browse -a` -- verify mDNS discovery across VLANs
- `curl -v` -- HTTP/HTTPS connectivity with TLS details
- When **reviewing** network configurations: flag missing inter-VLAN firewall rules,
- default credentials, disabled encryption, overly permissive access, and missing
- monitoring. State what's wrong and how to fix it.
+ When **reviewing** network configurations: flag missing inter-VLAN firewall rules, default credentials, disabled
+ encryption, overly permissive access, and missing monitoring. State what's wrong and how to fix it.
## Integration
- The **containers** skill covers Docker/Podman networking (bridge, host, macvlan).
- This skill covers the network infrastructure those containers sit on. When a task
- involves both container networking and VLAN/firewall design, both skills apply.
+ The **containers** skill covers Docker/Podman networking (bridge, host, macvlan). This skill covers the network
+ infrastructure those containers sit on. When a task involves both container networking and VLAN/firewall design, both
+ skills apply.
- The **ansible** skill handles automation of network configuration deployment. Use
- this skill for what to configure, ansible for how to deploy it.
+ The **ansible** skill handles automation of network configuration deployment. Use this skill for what to configure,
+ ansible for how to deploy it.
**Security is not optional. Every default must be secure. Convenience follows.**