From b1bca613de50bb505f2eda7241074e241d75e386 Mon Sep 17 00:00:00 2001
From: Nuno Duque Nunes <nunoduquenunes@gmail.com>
Date: Wed, 13 May 2026 00:41:16 +0000
Subject: [PATCH] feat: fw --rule filter, fw help, updated wgctl help, shell
 banner

---
 commands/fw.command.sh | 61 +++++++++++++++++++++++++++++++++++++++++-
 wgctl                  | 61 +++++++++++++++++++++++++++++-------------
 2 files changed, 103 insertions(+), 19 deletions(-)

diff --git a/commands/fw.command.sh b/commands/fw.command.sh
index 04ea354..8912a8f 100644
--- a/commands/fw.command.sh
+++ b/commands/fw.command.sh
@@ -7,11 +7,50 @@
 function cmd::fw::on_load() {
   flag::register --peer
   flag::register --type
+  flag::register --rule
   flag::register --no-nflog
   flag::register --no-accept
   flag::register --no-drop
 }
 
+# ============================================
+# Help
+# ============================================
+
+function cmd::fw::help() {
+  cat <<EOF
+Usage: wgctl fw [subcommand] [options]
+
+Inspect and manage firewall rules.
+
+Subcommands:
+  list                        Show FORWARD chain rules (default)
+  nat                         Show NAT/PREROUTING rules
+  flush-nat                   Flush NAT rules for a subnet
+  count                       Show rule counts by type
+
+Options for list:
+  --peer <name>               Filter by peer name
+  --rule <rule>               Filter by rule name (shows all peers with that rule)
+  --no-nflog                  Hide NFLOG rules
+  --no-accept                 Hide ACCEPT rules
+  --no-drop                   Hide DROP rules
+
+Examples:
+  wgctl fw list
+  wgctl fw list --peer phone-nuno
+  wgctl fw list --rule guest
+  wgctl fw list --no-nflog
+  wgctl fw nat
+  wgctl fw count
+  wgctl fw flush-nat --subnet 10.1.103.0/24
+EOF
+}
+
+# ============================================
+# Run
+# ============================================
+
 function cmd::fw::run() {
   local subcmd="${1:-list}"
 
@@ -34,12 +73,13 @@ function cmd::fw::run() {
 }
 
 function cmd::fw::list() {
-  local peer="" type=""
+  local peer="" type="" rule=""
   local show_nflog=true show_accept=true show_drop=true
 
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --peer)         peer="$2";          shift 2 ;;
+      --rule)         rule="$2";          shift 2 ;;
       --type)         type="$2";          shift 2 ;;
       --no-nflog)     show_nflog=false;   shift   ;;
       --no-accept)    show_accept=false;  shift   ;;
@@ -48,6 +88,25 @@ function cmd::fw::list() {
     esac
   done
 
+  # Rule filter — collect all IPs for peers with this rule
+  if [[ -n "$rule" ]]; then
+    log::section "Firewall Rules (FORWARD) — rule: ${rule}"
+    printf "\n"
+    local found=false
+    while IFS= read -r peer_name; do
+      local ip
+      ip=$(peers::get_ip "$peer_name")
+      [[ -z "$ip" ]] && continue
+      printf "  \033[0;37m── %s (%s)\033[0m\n" "$peer_name" "$ip"
+      iptables -L FORWARD -n -v | grep -F "$ip" \
+        | cmd::fw::_print_filtered "$show_nflog" "$show_accept" "$show_drop" || true
+      found=true
+    done < <(peers::with_rule "$rule")
+    $found || log::wg_warning "No peers found with rule: ${rule}"
+    printf "\n"
+    return 0
+  fi
+
   log::section "Firewall Rules (FORWARD)"
   printf "\n"
 
diff --git a/wgctl b/wgctl
index 19559c7..cfc2a6d 100755
--- a/wgctl
+++ b/wgctl
@@ -97,28 +97,53 @@ function wgctl::dispatch() {
 # ============================================
 
 function wgctl::help() {
-  cat <<EOF
-
-$(log::section "wgctl — WireGuard Management")
+cat <<EOF
+$(log::section "wgctl — WireGuard Management" 2>/dev/null || printf "\n  wgctl — WireGuard Management\n")
 
 Usage: wgctl <command> [options]
 
-Client Commands:
-  add, new, create      Add a new client
-  remove, rm, del       Remove a client
-  list, ls, show        List all clients
-  qr                    Show QR code for a client
-  block, ban            Block a client or add restrictions
-  unblock, unban        Restore client access
+  Client Commands:
+    add, new          Add a new client
+    remove, rm        Remove a client
+    rename, mv        Rename a client
+    list, ls          List all clients
+    inspect           Show detailed client info
+    config            Show client config
+    qr                Show QR code for a client
 
-Service Commands:
-  start, up             Start WireGuard
-  stop, down            Stop WireGuard
-  restart, reload       Restart WireGuard
-  status, stat          Show WireGuard status
-  logs, log             Show WireGuard logs
-  enable                Enable WireGuard on boot
-  disable               Disable WireGuard on boot
+  Access Control:
+    block, ban        Block a client entirely
+    unblock, unban    Restore client access
+    rule              Manage firewall rules (list, show, add, assign...)
+
+  Organization:
+    group             Manage peer groups (list, show, block, watch...)
+
+  Monitoring:
+    watch             Live monitor of WireGuard activity
+    logs              Show activity and firewall logs
+    audit             Verify firewall rules are correctly applied
+    fw                Inspect firewall rules
+
+  Service:
+    service           Manage WireGuard service (start/stop/restart/status)
+    restart           Restart WireGuard
+    shell             Start interactive wgctl shell
+
+  Development:
+    test              Run the wgctl test suite
+
+  Common examples:
+    wgctl add --name nuno --type phone
+    wgctl add --name visitor --type guest --subtype phone --group family
+    wgctl list --blocked
+    wgctl list --group family
+    wgctl block --name phone-nuno
+    wgctl inspect --name phone-nuno
+    wgctl rule assign --name admin --peer laptop-nuno
+    wgctl group block --name family
+    wgctl logs --follow
+    wgctl audit
 
 Run 'wgctl <command> --help' for command-specific help.
 EOF