@integsec/agentic-pentest-proxy 0.3.4 → 0.3.5

package/docs/superpowers/specs/2026-03-28-tui-monitor-design.md

@@ -0,0 +1,138 @@
+# TUI Monitor — Design Spec
+
+**Date:** 2026-03-28
+**Status:** Approved
+
+## Overview
+
+A standalone terminal dashboard that monitors the IntegSec Agentic Pentest MCP Proxy's audit log in real time. Built with Ink (React for terminals). Runs as a separate command alongside the proxy — does not interfere with the proxy's stdio pipeline.
+
+## How It Runs
+
+```bash
+# Default — watches AUDIT_LOG_PATH or ./audit/
+integsec-agentic-pentest-tui
+
+# Explicit path
+integsec-agentic-pentest-tui --audit-path ./audit
+
+# Filter to one engagement
+integsec-agentic-pentest-tui --engagement ENG-2026-TEST-001
+```
+
+Registered as a separate bin entry in package.json: `"integsec-agentic-pentest-tui"`.
+Entry file: `bin/integsec-agentic-pentest-tui.tsx`.
+
+## Screen Layout
+
+```
+┌─ ENGAGEMENT ──────────────────────────────────────────────┐
+│ ENG-2026-TEST-001 | IntegSec Internal | security@integsec │
+│ Window: 2026-03-27 → 2026-04-27  |  ██████░░ 12d left    │
+└───────────────────────────────────────────────────────────┘
+┌─ STATS ───────────────────────────────────────────────────┐
+│ ✓ Allowed: 42   ✗ Blocked: 7   Total: 49                 │
+│ Top targets: integsec.com (18) turbopentest.com (14)      │
+│ Top tools: nmap_scan (12) http_request (9) nuclei (8)     │
+└───────────────────────────────────────────────────────────┘
+┌─ LIVE FEED ───────────────────────────────────────────────┐
+│ 14:32:01 ✓ ALLOWED  nmap_scan → 10.10.10.5 (2ms)         │
+│ 14:32:03 ✗ BLOCKED  curl → evil.com [NOT_IN_SCOPE] (1ms) │
+│ 14:32:05 ✓ ALLOWED  nuclei → app.integsec.com (4ms)      │
+│ 14:32:06 ✓ ALLOWED  http_request → turbopentest.com (1ms) │
+│ ...scrolls, most recent at bottom...                      │
+└───────────────────────────────────────────────────────────┘
+```
+
+### Regions
+
+1. **Engagement Header** — static info derived from the first audit entry's metadata fields (engagement_id, client, operator, engagement window). Shows a progress bar for time remaining in the window.
+
+2. **Stats Panel** — running counters derived from all entries: allowed count, blocked count, total. Top 3 targets by frequency. Top 3 tools by frequency. Updated on each new entry.
+
+3. **Live Feed** — scrolling list of decision rows. Takes up remaining terminal height. Most recent at bottom, auto-scrolls. Color-coded:
+   - Green: ALLOWED
+   - Red: BLOCKED_*
+   - Dim gray: ALLOWED_NO_TARGET
+
+### Decision Row Format
+
+```
+HH:MM:SS ✓ ALLOWED  tool_name → target (Nms)
+HH:MM:SS ✗ BLOCKED  tool_name → target [REASON] (Nms)
+```
+
+## Architecture
+
+### Ink Components
+
+| Component | Responsibility |
+|-----------|---------------|
+| `<App>` | Root. Manages entries state array, runs file watcher, derives stats. |
+| `<EngagementHeader>` | Renders engagement info and time window progress bar. |
+| `<StatsPanel>` | Derives and displays counts, top targets, top tools from entries. |
+| `<LiveFeed>` | Scrolling list of DecisionRow components, auto-scrolls to bottom. |
+| `<DecisionRow>` | Single decision line: timestamp, icon, decision, tool, target, duration. |
+
+### File Watcher
+
+- Uses `fs.watch()` on the audit directory to detect file changes.
+- Tracks byte offset per file to read only new lines (avoids re-reading).
+- Parses each new line as an `AuditEntry` JSON object.
+- Appends parsed entries to the React state array, triggering re-render.
+- On startup, reads all existing entries from `.jsonl` files to populate historical data.
+
+### Entry Point (`bin/integsec-agentic-pentest-tui.tsx`)
+
+- Parses CLI args: `--audit-path` (default: `AUDIT_LOG_PATH` env or `./audit/`), `--engagement` (optional filter).
+- Scans audit directory for existing `.jsonl` files.
+- Loads historical entries.
+- Starts file watcher.
+- Renders `<App>` via Ink's `render()`.
+
+### New Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `ink` | ^5.0.0 | React terminal renderer |
+| `react` | ^18.0.0 | Required by Ink |
+| `ink-spinner` | ^5.0.0 | Loading spinner for "waiting for data" state |
+
+### Build
+
+TSX files compiled by TypeScript. Requires updating `tsconfig.json` to set `"jsx": "react-jsx"`. Ink 5 supports this natively.
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| No audit files exist yet | Shows "Waiting for audit data..." with spinner |
+| Malformed JSONL line | Silently skipped, logged to stderr |
+| File deleted or rotated | Watcher resets byte offset, rescans directory |
+| Multiple engagement files | If no `--engagement` flag, shows all entries interleaved chronologically |
+| Terminal resize | Ink handles automatically, feed adjusts height |
+| Ctrl+C | Clean exit via Ink's signal handling |
+
+## Testing
+
+- Unit test for the JSONL tail/parse logic (read new lines from offset, parse entries, handle malformed lines).
+- No tests for Ink components — pure display layer over the already-tested audit system.
+
+## Files Created
+
+```
+bin/integsec-agentic-pentest-tui.tsx    Entry point
+src/tui/App.tsx                         Root component
+src/tui/EngagementHeader.tsx            Engagement info panel
+src/tui/StatsPanel.tsx                  Running stats panel
+src/tui/LiveFeed.tsx                    Scrolling decision feed
+src/tui/DecisionRow.tsx                 Single decision line
+src/tui/useAuditWatcher.ts              Hook: file watcher + JSONL parser
+tests/unit/audit-watcher.test.ts        Unit test for watcher/parser
+```
+
+## Out of Scope
+
+- Interactivity (selecting entries, filtering in real time) — future Phase 3 work
+- Intercept queue — future Phase 2 work
+- Mouse support — not needed for read-only monitor

package/docs/superpowers/specs/2026-03-29-manifest-builder-design.md

@@ -0,0 +1,248 @@
+# Scope Manifest Builder — Design Spec
+
+**Date:** 2026-03-29
+**Status:** Approved
+
+## Overview
+
+A CLI wizard and optional web companion for building, editing, reviewing, and sharing MCP scope manifests. Targets three personas: pentest operators (primary), security team leads, and clients filling out their own scope.
+
+## Architecture
+
+Three layers, one shared validation core:
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Shared Core                       │
+│  manifest-schema.ts (Zod) ← already exists          │
+│  smart-validator.ts (Tier 1-2 validation)            │
+│  dry-run.ts (reuses ScopeValidator for previews)     │
+│  manifest-writer.ts (serialize + output)             │
+└──────────┬──────────────────────────┬───────────────┘
+           │                          │
+    ┌──────▼──────┐         ┌────────▼─────────┐
+    │  CLI Wizard  │         │   Web Server     │
+    │  (Ink TUI)   │         │  (Node http/s)   │
+    │              │         │                  │
+    │ • new        │◄───────►│ • Client intake  │
+    │ • edit       │         │ • Operator       │
+    │ • review     │         │   preview        │
+    │ • serve      │         │ • Scope dry-run  │
+    └──────────────┘         └──────────────────┘
+```
+
+The CLI is the primary interface. The web server is started on-demand via the `serve` subcommand. No external web framework — Node built-in `http`/`https` module + static HTML + small JSON API.
+
+## CLI Command
+
+New binary: `integsec-agentic-pentest-manifest`
+
+### Modes
+
+| Mode | Usage | Description |
+|------|-------|-------------|
+| `new` | `integsec-agentic-pentest-manifest new` | Full wizard, create from scratch |
+| `new --from` | `integsec-agentic-pentest-manifest new --from template.json` | Pre-fill from template |
+| `edit` | `integsec-agentic-pentest-manifest edit scope.json` | Edit existing manifest |
+| `edit --section` | `integsec-agentic-pentest-manifest edit scope.json --section targets` | Jump to specific section |
+| `review` | `integsec-agentic-pentest-manifest review submission.pending.json` | Review client submission |
+| `serve` | `integsec-agentic-pentest-manifest serve` | Start client intake web server |
+
+### Wizard Steps (for `new`)
+
+**Step 1: Engagement Info**
+- Fields: `engagement_id`, `client`, `operator`
+- Smart: auto-suggest engagement ID format (ENG-YYYY-NNNN)
+
+**Step 2: Engagement Window**
+- Fields: `start`, `end` (ISO 8601)
+- Smart: warn if window > 30 days, start in the past, or window < 1 hour
+
+**Step 3: Authorized Targets — Domains**
+- Add domains one at a time or comma-separated
+- Smart: resolve each domain live via `DnsResolver`, show mapped IPs
+- Smart: if `*.foo.com` is added, prompt about including `foo.com` (apex)
+
+**Step 4: Authorized Targets — IP Ranges**
+- Add CIDRs
+- Smart: warn if range broader than /16 ("covers X,XXX addresses")
+- Smart: flag overlap with domains already added
+
+**Step 5: Authorized Targets — URLs & Cloud Accounts**
+- URLs (optional, for reference)
+- Cloud account IDs (optional)
+
+**Step 6: Exclusions**
+- Excluded targets (IPs, domains)
+- Smart: auto-suggest cloud metadata IPs (169.254.169.254), localhost
+- Smart: warn if excluded target isn't within any authorized range (redundant)
+
+**Step 7: Techniques**
+- Multi-select from known technique categories
+- Excluded techniques pre-populated with `dos`, `destructive`, `social_engineering`
+- Smart: show which tools each category covers
+
+**Step 8: Review & Dry-Run**
+- Full manifest summary
+- Dry-run: synthetic tool calls against the validator
+- Show what would be allowed/blocked
+- Confirm → write to file
+
+### Power-User Shortcuts
+
+- `--from template.json` to pre-fill values
+- `--section targets` to jump directly when editing
+- Each wizard step shows `[s]kip` to jump ahead, `[b]ack` to go back
+
+## Web Server — Client Intake Mode
+
+### Operator Commands
+
+```bash
+# Local only (operator previewing or sharing over SSH tunnel)
+integsec-agentic-pentest-manifest serve --template scope-template.json
+
+# Exposed to network (client access) — TLS required
+integsec-agentic-pentest-manifest serve \
+  --host 0.0.0.0 \
+  --tls-cert ./certs/server.pem \
+  --tls-key ./certs/server-key.pem \
+  --template scope-template.json
+```
+
+### Network Security
+
+- **Default port: 9471** (unassigned in IANA)
+- **Binds to `127.0.0.1` by default** (localhost only)
+- **`--host 0.0.0.0` requires TLS:** `--tls-cert` and `--tls-key` are mandatory when host is not localhost
+- Server refuses to start without TLS on non-localhost and prints: `"Refusing to serve client intake form over plaintext on a non-localhost interface. Provide --tls-cert and --tls-key."`
+
+### Client Experience
+
+- Clean, technical-but-approachable form with IntegSec branding
+- Sections match manifest structure with tooltips explaining each field (e.g., "CIDR notation: 10.0.0.0/24 covers 10.0.0.0–10.0.0.255")
+- Live validation as they type — red/green indicators for CIDR format, domain resolution, date parsing
+- Pre-filled fields from template shown but locked (grayed out, not editable)
+- Submit button saves a `.pending.json` file to the operator's working directory
+
+### Operator Review Flow
+
+1. Client submits via web form → `.pending.json` saved
+2. `integsec-agentic-pentest-manifest review client-submission.pending.json`
+3. Smart validation + dry-run shown in terminal
+4. Operator can: approve (writes final `.json`), edit (opens edit mode), or reject
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/` | Serves the client intake form (single HTML file) |
+| `GET` | `/template` | Returns pre-filled template data as JSON |
+| `POST` | `/submit` | Validates submission, saves `.pending.json` |
+
+Server auto-shuts down after submission or after 60 minutes of inactivity (configurable via `--timeout <minutes>`).
+
+## Smart Validation — Three Tiers
+
+### Tier 1: Format Validation (synchronous, instant)
+
+- CIDR syntax valid (`ip-cidr` library, existing dependency)
+- ISO 8601 date parsing (Zod, existing)
+- Required fields non-empty
+- Domain format valid (no spaces, valid TLD)
+- Engagement ID matches pattern
+
+### Tier 2: Smart Validation (async, network calls)
+
+- **Live DNS resolution** — resolve each domain, show IPs. Uses existing `DnsResolver`.
+- **Overlap detection** — warn if domain resolves to IP already covered by authorized CIDR (informational)
+- **Apex/wildcard consistency** — prompt about `foo.com` when `*.foo.com` is added
+- **Broad range warning** — flag CIDRs wider than `/16`
+- **Orphaned exclusion warning** — excluded target not in any authorized range
+- **Window sanity** — start in past, > 30 days, < 1 hour
+
+### Tier 3: Dry-Run Preview (reuses existing `ScopeValidator`)
+
+Constructs a temporary `ScopeValidator` from the in-progress manifest and runs synthetic tool calls:
+
+| Test | Tool | Expected |
+|------|------|----------|
+| Each authorized domain | `nmap` | ALLOWED |
+| Sample IP from each authorized range | `nmap` | ALLOWED |
+| Each excluded target | `nmap` | BLOCKED |
+| Sensitive targets (169.254.169.254, localhost) | `curl` | BLOCKED (unless explicitly authorized) |
+| Out-of-scope target (8.8.8.8) | `nmap` | BLOCKED |
+
+Results displayed as a table with pass/fail indicators. Surprises are flagged.
+
+## File Structure
+
+```
+src/
+  builder/
+    wizard.tsx                ← Ink wizard (main flow, step management)
+    steps/
+      engagement-info.tsx     ← Step 1
+      engagement-window.tsx   ← Step 2
+      domains.tsx             ← Step 3
+      ip-ranges.tsx           ← Step 4
+      urls-and-cloud.tsx      ← Step 5
+      exclusions.tsx          ← Step 6
+      techniques.tsx          ← Step 7
+      review.tsx              ← Step 8: summary + dry-run
+    smart-validator.ts        ← Tier 1-2 validation (shared core)
+    dry-run.ts                ← Tier 3 dry-run engine (shared core)
+    manifest-writer.ts        ← Serialize + write manifest to disk
+    web/
+      server.ts               ← Node http/https server
+      client-form.html        ← Single-file client intake form (no build step)
+      api.ts                  ← Route handlers for /template and /submit
+
+bin/
+  integsec-agentic-pentest-manifest.ts  ← new CLI entry point
+```
+
+### New package.json Entry
+
+```json
+"integsec-agentic-pentest-manifest": "dist/bin/integsec-agentic-pentest-manifest.js"
+```
+
+## Reused Existing Modules
+
+| Module | Reuse |
+|--------|-------|
+| `manifest-schema.ts` | Zod schema for validation |
+| `types.ts` | `ScopeManifest` type |
+| `validator.ts` | `ScopeValidator` for dry-run |
+| `dns-resolver.ts` | Live domain resolution |
+| `ip-matcher.ts` | CIDR validation and overlap detection |
+| `domain-matcher.ts` | Wildcard consistency checks |
+| `technique-checker.ts` | Tool-to-category mappings |
+
+## README Updates
+
+Add a new "Manifest Builder" section to README.md covering:
+
+- Feature overview and motivation
+- Usage examples for all four modes (`new`, `edit`, `review`, `serve`)
+- Client intake workflow walkthrough (operator creates template → shares link → client fills out → operator reviews)
+- TLS setup instructions for network-exposed intake
+- Smart validation and dry-run explanation
+- Screenshots/examples of the wizard and web form
+
+## Dependencies
+
+No new production dependencies required. Everything builds on:
+- `ink` (existing) — for TUI wizard
+- `react` (existing) — for Ink components
+- `zod` (existing) — for schema validation
+- `ip-cidr` (existing) — for CIDR operations
+- Node built-in `http`/`https`/`tls` — for web server
+
+## Incremental Delivery
+
+1. **Phase 1:** CLI wizard (`new` mode) + shared validation core + dry-run
+2. **Phase 2:** `edit` and `review` modes
+3. **Phase 3:** Web server (`serve` mode) + client intake form
+4. **Phase 4:** README updates, polish, edge cases

package/docs/tui.md

@@ -0,0 +1,25 @@
+# TUI monitor
+
+The terminal monitor tails local audit JSONL files written by the proxy. Run it in a separate terminal using the path printed by `integsec-agentic-pentest-setup`:
+
+```bash
+integsec-agentic-pentest-tui --audit-path /path/to/audit
+```
+
+Use `--engagement <id>` to show one engagement. The header shows the engagement, client, and operator from the first matching entry. The stats panel shows allowed and blocked counts and frequent targets and tools. The live feed shows recent decisions, targets, reasons for blocks, and duration.
+
+The action shots below use fictional identifiers and documentation-only IP addresses. They are rendered from the actual TUI components.
+
+### In-scope scan
+
+![TUI showing six allowed tool calls for fictional in-scope targets](images/tui-in-scope.png)
+
+### Out-of-scope target blocked
+
+![TUI showing a blocked documentation IP and excluded hostname](images/tui-out-of-scope.png)
+
+### Technique and time guardrails
+
+![TUI showing technique, free-form command, and time-window blocks](images/tui-policy-blocks.png)
+
+Regenerate the images from the current TUI components with `npm run build` followed by `node scripts/render-tui-shots.mjs`. The script writes SVG sources; the checked-in PNGs are the rendered documentation previews.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integsec/agentic-pentest-proxy",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "IntegSec Agentic Pentest MCP Proxy — enforce penetration testing engagement scope for AI agents",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
     "cloudflare/src/worker.mjs",
     "cloudflare/package.json",
     "cloudflare/package-lock.json",
-    "docs/managed-gateway.md",
+    "docs/",
     "examples/",
     "scripts/postinstall.cjs",
     "README.md",
@@ -61,10 +61,12 @@
     "ink-spinner": "^5.0.0",
     "ipaddr.js": "^2.5.0",
     "jose": "^6.2.15",
+    "markdown-it": "^14.3.3",
     "react": "^18.3.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@types/markdown-it": "^14.2.0",
     "@types/node": "^22.20.5",
     "@types/react": "^18.3.28",
     "typescript": "^5.7.0",