WAF Shadow Rules Monitoring TUI

Terminal UI for exploring AWS WAF shadow-rule telemetry from either local JSON snapshots or live Athena queries.

Features

• Offline mode backed by demo or exported JSON snapshots
• Live Athena-backed manifest and per-system snapshot loading
• Ink 5.x terminal UI with overview, drilldown, and sample views
• Vim-style and arrow-key navigation
• Optional interactive AWS credential prompt for Athena mode
• Bun-based development, test, and compile workflow

Installation

Install globally:

npm install -g waf-shadow-tui

Run without installing:

npx waf-shadow-tui --folder ./demo-data

Usage

Offline mode with local JSON fixtures:

npx waf-shadow-tui --folder ./demo-data

Athena mode with a named AWS profile:

waf-shadow-tui --profile myprofile --region us-east-1

Athena mode without a profile:

waf-shadow-tui --region us-east-1

If you omit --folder, the CLI uses Athena. Credentials are resolved in this order:

1. Explicit values entered in the interactive prompt
2. --profile or AWS_PROFILE
3. Standard AWS environment/default credential chain

CLI Flags

| Flag | Description | Default | |------|-------------|---------| | --folder <path> | Load manifest and snapshots from local JSON files instead of Athena | none | | --profile <name> | AWS shared config/credentials profile for Athena mode | current AWS SDK default chain | | --region <region> | AWS region for Athena queries | us-east-1 | | --help, -h | Print usage and exit | n/a |

Keyboard Shortcuts

| Shortcut | Context | Action | |----------|---------|--------| | j / Down | Overview, drilldown, samples | Move selection down | | k / Up | Overview, drilldown, samples | Move selection up | | Enter | Overview | Open selected system | | Enter | Drilldown | Open samples for selected rule when samples exist | | Tab | Drilldown | Cycle time period (24h, 7d, 30d) | | Esc | Drilldown, samples, error states | Go back / clear error | | q | Anywhere | Quit |

Demo Data Format

Offline mode expects a folder with a manifest plus per-system snapshots.

Manifest shape:

{
  "generated": "2026-05-20T15:00:00Z",
  "systems": [
    {
      "name": "payments-api",
      "environments": ["prod", "stage"],
      "totalRules": 14,
      "latestSnapshot": "2026-05-20T15:00:00Z",
      "dataPath": "systems/payments-api.json"
    }
  ]
}

Snapshot shape:

{
  "system": "payments-api",
  "generatedAt": "2026-05-20T15:00:00Z",
  "environments": [
    {
      "name": "prod",
      "ruleCount": 10,
      "totalHits": 2481
    }
  ],
  "periods": [
    {
      "name": "24h",
      "rules": [
        {
          "ruleId": "rule-1",
          "ruleName": "RateLimitRule",
          "action": "COUNT",
          "totalHits": 25,
          "environments": {
            "prod": 20,
            "stage": 5
          },
          "samples": []
        }
      ]
    }
  ]
}

Building From Source

Install dependencies:

bun install

Run the app in development:

bun run src/index.ts --folder ./demo-data

Build the standalone Bun executable:

bun run build

Useful validation commands:

bun test
bun run typecheck

Screenshots

Screenshots will be added here.

Architecture Overview

The application is layered as CLI entry -> App shell -> Ink components -> Data providers -> shared domain types. LocalLoader and AthenaDataProvider both implement the same DataProvider contract so the UI can switch between offline and live data without changing view logic.

License

MIT