Kwall

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

This project is configured to use the local scrin crate at ../KnottTUI so it tracks your local widget/toolkit changes during development.

Current status: safe dry-run prototype. It stages firewall rules and renders command plans for ufw, iptables, and nftables, but it does not execute commands, edit /etc, or write firewall state.

Safety Model

• No live executor exists yet.
• The UI only creates an in-memory rule plan.
• Generated commands are displayed for review only.
• No tests or live firewall probes are run by default.

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
• 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 dry-run profile
• y: apply the management-preserving recommended dry-run profile when available
• w: apply the workstation dry-run profile
• e: apply the web-server dry-run profile
• D: apply the developer dry-run profile
• k: apply the lockdown dry-run profile
• r: run advisor quick fix
• u: undo the last staged dry-run change
• o: export a local dry-run report for review
• S: export a safe commented command-preview shell script
• m: export a review-only JSON dry-run 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 dry-run plan while keeping undo available
• 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 dry-run safety popup
• ?: open the help modal

Build note

• The project uses scrin = "0.1.84" in normal dependency form and overrides it to local sources through [patch.crates-io].

• If you want to use crates.io only, remove the local override from the [patch.crates-io] section in Cargo.toml.

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

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:
  • Enter confirms the action
  • y / Y confirms the action
  • n cancels the action
  • Esc dismisses the modal
• Verify overlay toggles and focus flow:
  • : or / opens the command palette
  • 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 no firewall files or system state changes occur (review-only behavior).
• 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 → hardening staged as Confirm hardening flow
• Press : and type help then Enter → help overlay opens and ?/Esc closes it
• Press s and Esc → safety popup opens then closes
• 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
• 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
• 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 dry-run profiles
• Lockout-aware strongest dry-run 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 dry-run 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 dry-run 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 a guarded live executor with confirmation, privilege checks, and rollback plans.
• Add CLI commands after the TUI workflow is stable.