Kwall

Kwall is a Rust terminal UI for staging, reviewing, and explicitly applying Linux firewall plans built with scrin and its built-in Aisling effects.

Current status: guarded live-apply prototype. It stages firewall rules, renders command plans for ufw, iptables, and nftables, and can run the selected backend plan against the live firewall with L after confirmation.

Safety Model

• The UI stages an in-memory rule plan first.
• L requests live apply and runs the selected backend command plan only after two-step confirmation.
• Live apply blocks when review gates have blockers and requires root privileges to edit firewall state.
• Failed commands stop the apply; there is no automatic rollback yet.
• Exported reports, scripts, and manifests are inert review artifacts and do not execute commands.
• Tests use fake command runners and do not touch the host firewall.

TUI Controls

• q or Esc: quit
• Tab: switch pages
• 1 / 2 / 3 / 4 / 5: jump to Dashboard, Rules, Ports, Plan, Advisor
• : or /: open the command palette; type block <url|domain|ip>, deny <target>, or blacklist <target> to stage outbound target blocks
• f: move active panel focus on the Dashboard page
• Up / Down: move selection
• Enter or d: block/unblock the selected known service port
• N: jump to the highest-priority at-risk known port
• n: stage a block for the highest-priority at-risk known port
• M: stage blocks for the top dashboard priority queue
• X: mark or remove a reviewed exception for the selected allowed risky port
• F: cycle the known-port filter: all, named, at-risk, open, blocked, allowed
• G: cycle the known-port service-group filter
• K: cycle the known-port risk-class filter
• g: stage blocks for every known port in the selected service group
• B: stage blocks for every known port in the selected risk class
• V: stage blocks for every known port visible under the active filters
• A: stage allows for every known port visible under the active filters
• h: stage blocks for known high-risk/admin/data ports
• Y: apply the strongest currently recommended staged profile
• y: apply the management-preserving recommended staged profile when available
• w: apply the workstation staged profile
• e: apply the web-server staged profile
• D: apply the developer staged profile
• k: apply the lockdown staged profile
• r: run advisor quick fix
• u: undo the last staged change
• o: export a local dry-run report for review
• S: export a safe commented command-preview shell script
• m: export an inert JSON staged manifest
• E: export the report, safe script, and JSON manifest together
• I: toggle the planned default incoming policy
• O: toggle the planned default outgoing policy
• c: clear all staged rules while keeping undo available
• R: restore the safe starter plan while keeping undo available
• L: apply the staged plan to the live firewall after review-gate and privilege checks
• H: focus the selected service details in the inline Ports info pane
• hover or left-click a known-port row: select it and update the inline info pane
• right-click a known-port row: arm the inline action pane for block, allow, toggle, or reviewed exception
• b: stage a deny/block rule for the selected service port
• a: stage an allow rule for the selected service port
• Space: toggle the selected staged rule
• x: remove the selected staged rule
• p: cycle the preview backend
• l: toggle planned logging behavior
• s: toggle the live-apply safety popup
• ?: open the help modal

Build Note

• The project uses scrin = "0.1.84" from crates.io with no local patch override.

Scrin Feature Upgrades

This release of Kwall is aligned with scrin 0.1.84 and takes advantage of:

• diff/frame timing via Terminal::draw_timed and FrameTiming
• safer no-op path instrumentation for performance tuning
• frame diagnostics hooks and dirty-run updates via the new terminal internals
• render scheduling aligned to the latest present/FrameDiagnostic behavior
• hit-region metadata and pointer routing for hover/select/right-click port interactions

Set KWALL_FRAME_METRICS=1 to display per-frame timing and byte stats in the status bar.

Manual TUI Smoke Test

• Run with cargo run and open the command palette with :.
• Trigger a bulk action (for example, h for high-risk hardening or V to stage visible candidates).
• Verify the confirmation modal appears before staging actions:
  • first Enter or y opens the final "Are you sure?" page
  • second Enter or y confirms the action
  • n cancels the action
  • Esc dismisses the modal
• Verify overlays, panes, and focus flow:
  • : or / opens the command palette
  • typing block 203.0.113.20 then Enter stages an outbound target block without touching the live firewall
  • Esc closes the command palette
  • : + q keeps the palette open and records q in the query (quit is shielded)
  • While the palette is open, q is treated as palette input, not quit
  • Repeating Esc closes one layer at a time (palette/help/safety), then quits on the next key when clear
  • ? opens the help modal
  • ?, Enter, or Esc close the help modal
  • s toggles the safety popup
• Confirm staged actions do not edit firewall state until L is confirmed.
• Press L without root to verify the privilege guard blocks live apply.
• Toggle the palette and repeat a no-op path (already-safe candidate set) to verify it reports no changes and does not open confirmation.

Manual Smoke Transcript

• cargo run
• Press : then q → palette opens, query becomes q
• Press Esc → palette closes, app stays open
• Press Esc again → app exits
• Open palette with : and run clear-rules
• Press Esc in confirmation modal → action canceled
• Press :, h, Enter, Enter → hardening staged after the two-step confirmation flow
• Press : and type help then Enter → help overlay opens and ?/Esc closes it
• Press : and type block 203.0.113.20 then Enter → an outbound target block appears in Rules
• Press s and Esc → safety popup opens then closes
• Hover or left-click a known port → the Ports info pane updates without covering the list
• Right-click a known port → the action pane arms; b, a, d, or X routes through two-step confirmation
• Press L → live-apply confirmation appears; cancel unless intentionally testing on a disposable/root shell
• Optional quick checks: :cycle-backend, :toggle-logging, :toggle-default-incoming, :toggle-default-outgoing should update values in Plan snapshot

TUI Features

• Clean dashboard overview with one accent color
• Dashboard priority strip for the next at-risk port or review-ready state
• Dashboard priority queue for the next at-risk ports
• Risk-scored priority queue with deterministic reasons in dashboard and review exports
• Reviewed exception workflow for intentionally allowed risky ports
• Guarded live apply of the selected backend plan with review-gate and privilege checks
• Inline risk/info pane for selected or hovered known ports
• Right-click known-port action pane with confirmation-gated mutations
• Spotlight-style command palette target blocking for URLs, domains, and IP addresses
• Priority-port jump from the dashboard or command palette
• One-key priority-port block action
• One-key priority-queue block action
• Dynamic dashboard panes that expand around active focus
• Expanded known service port catalog with service groups
• Known service aliases for easier review and search matching
• Alias-aware named filter for common services like SSH, nginx, Postgres, and Docker
• Known service port list with block/open/allowed status
• Known-port coverage totals in the dashboard and review exports
• Review-readiness grade in the dashboard and review exports
• Review gates with blocker/warning/pass status, including recommended-profile safety
• Management-access guard for SSH/RDP/VNC/Kubernetes lockout review
• Service-group coverage summaries in Ports view and review exports
• Risk-class coverage summaries in Ports view and review exports
• Known-port status catalog in report and JSON review exports
• Target address fields in staged-rule reports, manifests, fingerprints, and backend command previews
• Per-port review recommendations in report and JSON review exports
• Focused at-risk open port list in report and JSON review exports
• Focused at-risk allowed port list in report and JSON review exports
• Suggested review order in report and JSON review exports
• Priority-port queue in report and JSON review exports
• Reviewed exceptions in dashboard, advisor, report, and JSON review exports
• Filtered known-port navigation by risk and staged status
• Service-group filtering for the known-port catalog
• Risk-class filtering for the known-port catalog
• Direct block/unblock workflow for common ports
• Bulk risk-class blocking from the known-port catalog
• Bulk blocking for the current known-port filter result
• Bulk allowing for the current known-port filter result
• Bulk group blocking and staged profiles
• Lockout-aware strongest staged profile recommendation with score and rationale
• Dashboard summary for strongest and management-preserving profile actions
• Management-preserving safer profile alternative in Plan, report, and manifest exports
• Strongest and management-preserving profile change previews before application
• One-key application of strongest and management-preserving recommended staged profiles
• Profile impact preview with management lockout details before staging a profile
• Advisor tab with conflict detection, risk review, and quick fixes
• Next advisor action surfaced in the dashboard and review exports
• Advisor severity totals in the dashboard and review exports
• In-memory undo checkpoints for staged changes
• Undoable default policy controls and staged-rule clearing
• Undoable reset back to the starter plan
• Local dry-run report export with staged rules, known-port status, advisor findings, and command previews
• Safe shell preview export that exits before commented firewall commands
• Machine-readable JSON manifest export with known-port status details
• One-shot review bundle export for all generated artifacts
• Stable review fingerprint shown in the Plan page and exported artifacts
• Cross-backend command count comparison for UFW, iptables, and nftables
• Table view for generated firewall command plans
• Status bar, help modal, safety popup, toasts, tabs, and command palette

Dry-Run Profiles

• Workstation: blocks legacy, file sharing, data, admin, dev, and orchestration services.
• Web server: allows HTTP/HTTPS and blocks data, dev, file, legacy, orchestration, and observability services.
• Developer: blocks legacy, file sharing, data, and orchestration services.
• Lockdown: blocks every known service port in the catalog.

Roadmap

• Add real system discovery behind explicit opt-in.
• Add rollback planning and post-apply verification for live apply.
• Add CLI commands after the TUI workflow is stable.