# 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
- dirty-bounds presentation and event-driven redraws so idle screens do not repaint constantly
Set `KWALL_FRAME_METRICS=1` to display per-frame timing and byte stats in the status bar.
The TUI renders on input, active overlays, and the finite startup banner instead of repainting on a fixed idle loop.
### 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
- Keyboard selection on Rules, Ports, Plan, and Advisor views with stronger active-row highlighting
- 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.