# Network Diagnostics

> Agents should invoke this skill for connectivity, DNS, Pi-hole, port reachability, routing, firewall reachability, TLS/network timeouts, or service access failures. Provides structured network troubleshooting commands and interpretation.

- **Type:** Skill
- **Install:** `agentstack add skill-firstp1ck-pi-coding-agent-forge-network-diagnostics`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Firstp1ck](https://agentstack.voostack.com/s/firstp1ck)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Firstp1ck](https://github.com/Firstp1ck)
- **Source:** https://github.com/Firstp1ck/pi-coding-agent-forge/tree/main/pi-skill-network-diagnostics/skills/network-diagnostics

## Install

```sh
agentstack add skill-firstp1ck-pi-coding-agent-forge-network-diagnostics
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Network Diagnostics

Diagnose and troubleshoot network issues including connectivity, DNS, ports, and routing.

## Quick Start

### Connectivity Check

```bash
# Check internet connectivity
ping -c 3 1.1.1.1

# Check DNS resolution
dig google.com +short

# Check a local service
curl -s -o /dev/null -w "%{http_code}" http://pi.hole/admin/
```

---

## DNS Diagnostics

### Basic DNS Resolution

```bash
# Resolve via system DNS (Pi-hole)
dig example.com +short

# Resolve via specific DNS server
dig @1.1.1.1 example.com +short   # Cloudflare
dig @8.8.8.8 example.com +short   # Google
dig @pi.hole example.com +short   # Pi-hole

# Reverse DNS lookup
dig -x  +short

# Full DNS trace
dig example.com +trace
```

### Pi-hole DNS Analysis

```bash
# Check if Pi-hole is blocking correctly
# Query a known ad domain — should return 0.0.0.0 or NXDOMAIN
dig @pi.hole ads.google.com +short

# Check Pi-hole query log (recent queries via API)
curl -s "http://pi.hole/admin/api.php?getAllQueries=100" | jq '.data | length'

# Check upstream DNS health
curl -s "http://pi.hole/admin/api.php?getForwardDestinations" | jq '.'

# Check if Pi-hole is enabled
curl -s "http://pi.hole/admin/api.php?status" | jq '.status'
```

### DNS Troubleshooting Flow

```
DNS not resolving?
├── Can you ping 1.1.1.1?
│   ├── No → Network/routing issue (not DNS)
│   └── Yes → DNS issue confirmed
│       ├── Does dig @1.1.1.1 work?
│       │   ├── No → Upstream DNS blocked (firewall?)
│       │   └── Yes → Local DNS problem
│       │       ├── Does dig @pi.hole work?
│       │       │   ├── No → Pi-hole issue
│       │       │   │   ├── Is pihole-FTL running?
│       │       │   │   ├── Is port 53 listening?
│       │       │   │   └── Check Pi-hole logs
│       │       │   └── Yes → Client DNS config issue
│       │       │       └── Check /etc/resolv.conf
│       │       └── Is /etc/resolv.conf pointing to Pi-hole?
```

---

## Connectivity Testing

### Layer-by-Layer Diagnosis

```bash
# Layer 1-2: Physical/Link
ip link show              # Interface status
ethtool        # Link speed, duplex

# Layer 3: Network
ip addr show              # IP addresses
ip route show             # Routing table
ping -c 3       # Gateway reachable?
ping -c 3 1.1.1.1        # Internet reachable?

# Layer 4: Transport
ss -tlnp                  # Listening TCP ports
ss -ulnp                  # Listening UDP ports

# Layer 7: Application
curl -v http://example.com  # HTTP connectivity
```

### Traceroute

```bash
# Standard traceroute
traceroute 

# TCP traceroute (bypasses ICMP blocks)
traceroute -T -p 443 

# MTR for continuous monitoring
mtr --report 
```

---

## Port Reachability

### Check if a Port is Open

```bash
# From this machine to a target
nc -zv             # Netcat
timeout 3 bash -c "echo > /dev/tcp//" && echo "open" || echo "closed"

# Check multiple ports
for port in 22 53 80 443 3000 8080 11434; do
  nc -zv  $port 2>&1 | grep -E "succeeded|refused"
done
```

### Port Scan (Local Network)

```bash
# Quick scan of a host
nmap -F 

# Scan specific ports
nmap -p 22,53,80,443,3000,8080,11434 

# Scan entire local subnet
nmap -sn     # Ping sweep (who's online?)
```

### Known Service Ports

| Host | Port | Service | Protocol |
|---|---|---|---|
| pi.hole | 53 | DNS | UDP/TCP |
| pi.hole | 80 | Web UI | HTTP |
|  | 3000 | Gitea | HTTP |
|  |  | NAS SSH | SSH |
|  | 22 | SSH server | SSH |
|  | 11434 | Ollama | HTTP |

---

## Network Topology

### Local Network Map

```
Internet
  │
  ▼
[Router/Gateway]
  │
  ├── Pi-hole (DNS) ─── pi.hole:53, :80
  │
  ├──  ─── Gitea :3000, NAS SSH :
  │
  ├──  ─── SSH server :22
  │
  ├──  ─── Ollama :11434
  │
  └── [This machine] ── Workstation
```

### Discover Network Devices

```bash
# ARP table (devices recently seen)
ip neigh show

# Ping sweep
nmap -sn 

# Check DHCP leases (if accessible)
# Often at router admin page
```

---

## Troubleshooting Workflows

### "Service X is Unreachable"

1. **Ping the host:** `ping -c 3 ` — Is the machine up?
2. **Check the port:** `nc -zv  ` — Is the service listening?
3. **Check locally:** SSH in, run `ss -tlnp | grep ` — Is it bound?
4. **Check firewall:** Is the port allowed through?
5. **Check the service:** `systemctl status ` — Is it running?
6. **Check logs:** `journalctl -u  -n 20` — Any errors?

### "Internet is Slow"

1. **Check DNS:** `time dig google.com` — Slow DNS resolution?
2. **Check latency:** `ping -c 10 1.1.1.1` — High latency?
3. **Check bandwidth:** `curl -o /dev/null -w "%{speed_download}" https://speed.cloudflare.com/__down?bytes=10000000`
4. **Check for packet loss:** `mtr --report -c 20 1.1.1.1`
5. **Check local network:** `iperf3 -c ` — LAN speed OK?

### "Pi-hole Stopped Blocking Ads"

1. **Check status:** `curl -s "http://pi.hole/admin/api.php?status" | jq '.status'`
2. **Check if disabled:** Someone might have paused it
3. **Check blocklists:** `curl -s "http://pi.hole/admin/api.php?summary" | jq '.gravity_last_updated'`
4. **Update gravity:** `pihole -g` (requires SSH to Pi-hole host)
5. **Check client DNS:** Is the client actually using Pi-hole? `cat /etc/resolv.conf`

---

## Useful One-Liners

```bash
# What's my public IP?
curl -s ifconfig.me

# What's my local IP?
ip -4 addr show | grep -oP '(? +short  # 0.0.0.0 = blocked

# DNS response time
time dig google.com @pi.hole > /dev/null

# Check all network interfaces
ip -br link show
```

---

_Kai skill — Network diagnostics and troubleshooting_

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Firstp1ck](https://github.com/Firstp1ck)
- **Source:** [Firstp1ck/pi-coding-agent-forge](https://github.com/Firstp1ck/pi-coding-agent-forge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-firstp1ck-pi-coding-agent-forge-network-diagnostics
- Seller: https://agentstack.voostack.com/s/firstp1ck
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.