# 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.