tweek 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

tweek/cli_proxy.py

@@ -0,0 +1,405 @@
+"""CLI commands for the Tweek LLM security proxy.
+
+Provides the ``proxy`` Click group and its subcommands:
+start, stop, trust, config, wrap, setup.
+
+These were extracted from the monolithic cli.py to improve
+maintainability.  The group is registered on the main CLI
+entry-point via ``main.add_command(proxy)``.
+"""
+
+import os
+from pathlib import Path
+
+import click
+
+from tweek.cli_helpers import console, print_error, print_success, print_warning, spinner
+
+
+# ------------------------------------------------------------------
+# Proxy command group
+# ------------------------------------------------------------------
+
+@click.group()
+def proxy():
+    """LLM API security proxy for universal protection.
+
+    The proxy intercepts LLM API traffic and screens for dangerous tool calls.
+    Works with any application that calls Anthropic, OpenAI, or other LLM APIs.
+
+    \b
+    Install dependencies: pip install tweek[proxy]
+    Quick start:
+        tweek proxy start       # Start the proxy
+        tweek proxy trust       # Install CA certificate
+        tweek proxy wrap openclaw "npm start"  # Wrap an app
+    """
+    pass
+
+
+# ------------------------------------------------------------------
+# tweek proxy start
+# ------------------------------------------------------------------
+
+@proxy.command(
+    "start",
+    epilog="""\b
+Examples:
+  tweek proxy start                      Start proxy on default port (9877)
+  tweek proxy start --port 8080          Start proxy on custom port
+  tweek proxy start --foreground         Run in foreground for debugging
+  tweek proxy start --log-only           Log traffic without blocking
+""",
+)
+@click.option("--port", "-p", default=9877, help="Port for proxy to listen on")
+@click.option("--web-port", type=int, help="Port for web interface (disabled by default)")
+@click.option("--foreground", "-f", is_flag=True, help="Run in foreground (for debugging)")
+@click.option("--log-only", is_flag=True, help="Log only, don't block dangerous requests")
+def proxy_start(port: int, web_port: int, foreground: bool, log_only: bool):
+    """Start the Tweek LLM security proxy."""
+    from tweek.proxy import PROXY_AVAILABLE, PROXY_MISSING_DEPS
+
+    if not PROXY_AVAILABLE:
+        console.print("[red]\u2717[/red] Proxy dependencies not installed.")
+        console.print("  [white]Hint: Install with: pip install tweek[proxy][/white]")
+        console.print("  [white]This adds mitmproxy for HTTP(S) interception.[/white]")
+        return
+
+    from tweek.proxy.server import start_proxy
+
+    console.print(f"[cyan]Starting Tweek proxy on port {port}...[/cyan]")
+
+    success, message = start_proxy(
+        port=port,
+        web_port=web_port,
+        log_only=log_only,
+        foreground=foreground,
+    )
+
+    if success:
+        console.print(f"[green]\u2713[/green] {message}")
+        console.print()
+        console.print("[bold]To use the proxy:[/bold]")
+        console.print(f"  export HTTPS_PROXY=http://127.0.0.1:{port}")
+        console.print(f"  export HTTP_PROXY=http://127.0.0.1:{port}")
+        console.print()
+        console.print("[white]Or use 'tweek proxy wrap' to create a wrapper script[/white]")
+    else:
+        console.print(f"[red]\u2717[/red] {message}")
+
+
+# ------------------------------------------------------------------
+# tweek proxy stop
+# ------------------------------------------------------------------
+
+@proxy.command(
+    "stop",
+    epilog="""\b
+Examples:
+  tweek proxy stop                       Stop the running proxy server
+""",
+)
+def proxy_stop():
+    """Stop the Tweek LLM security proxy."""
+    from tweek.proxy import PROXY_AVAILABLE
+
+    if not PROXY_AVAILABLE:
+        console.print("[red]\u2717[/red] Proxy dependencies not installed.")
+        return
+
+    from tweek.proxy.server import stop_proxy
+
+    success, message = stop_proxy()
+
+    if success:
+        console.print(f"[green]\u2713[/green] {message}")
+    else:
+        console.print(f"[yellow]![/yellow] {message}")
+
+
+# ------------------------------------------------------------------
+# tweek proxy trust
+# ------------------------------------------------------------------
+
+@proxy.command(
+    "trust",
+    epilog="""\b
+Examples:
+  tweek proxy trust                      Install CA certificate for HTTPS interception
+""",
+)
+def proxy_trust():
+    """Install the proxy CA certificate in system trust store.
+
+    This is required for HTTPS interception to work. The certificate
+    is generated locally and only used for local proxy traffic.
+    """
+    from tweek.proxy import PROXY_AVAILABLE
+
+    if not PROXY_AVAILABLE:
+        console.print("[red]\u2717[/red] Proxy dependencies not installed.")
+        console.print("[white]Run: pip install tweek\\[proxy][/white]")
+        return
+
+    from tweek.proxy.server import get_proxy_info, install_ca_certificate
+
+    info = get_proxy_info()
+
+    console.print("[bold]Tweek Proxy Certificate Installation[/bold]")
+    console.print()
+    console.print("This will install a local CA certificate to enable HTTPS interception.")
+    console.print("The certificate is generated on YOUR machine and never transmitted.")
+    console.print()
+    console.print(f"[white]Certificate location: {info['ca_cert']}[/white]")
+    console.print()
+
+    if not click.confirm("Install certificate? (requires admin password)"):
+        console.print("[white]Cancelled[/white]")
+        return
+
+    success, message = install_ca_certificate()
+
+    if success:
+        console.print(f"[green]\u2713[/green] {message}")
+    else:
+        console.print(f"[red]\u2717[/red] {message}")
+
+
+# ------------------------------------------------------------------
+# tweek proxy config
+# ------------------------------------------------------------------
+
+@proxy.command(
+    "config",
+    epilog="""\b
+Examples:
+  tweek proxy config --enabled           Enable proxy in configuration
+  tweek proxy config --disabled          Disable proxy in configuration
+  tweek proxy config --enabled --port 8080   Enable proxy on custom port
+""",
+)
+@click.option("--enabled", "set_enabled", is_flag=True, help="Enable proxy in configuration")
+@click.option("--disabled", "set_disabled", is_flag=True, help="Disable proxy in configuration")
+@click.option("--port", "-p", default=9877, help="Port for proxy")
+def proxy_config(set_enabled, set_disabled, port):
+    """Configure proxy settings."""
+    if not set_enabled and not set_disabled:
+        console.print("[red]Specify --enabled or --disabled[/red]")
+        return
+
+    import yaml
+
+    config_path = Path.home() / ".tweek" / "config.yaml"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    config = {}
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                config = yaml.safe_load(f) or {}
+        except Exception:
+            pass
+
+    if set_enabled:
+        config["proxy"] = {
+            "enabled": True,
+            "port": port,
+            "block_mode": True,
+            "log_only": False,
+        }
+
+        with open(config_path, "w") as f:
+            yaml.dump(config, f, default_flow_style=False)
+
+        console.print(f"[green]\u2713[/green] Proxy mode enabled (port {port})")
+        console.print("[white]Run 'tweek proxy start' to start the proxy[/white]")
+
+    elif set_disabled:
+        if "proxy" in config:
+            config["proxy"]["enabled"] = False
+
+            with open(config_path, "w") as f:
+                yaml.dump(config, f, default_flow_style=False)
+
+        console.print("[green]\u2713[/green] Proxy mode disabled")
+
+
+# ------------------------------------------------------------------
+# tweek proxy wrap
+# ------------------------------------------------------------------
+
+@proxy.command(
+    "wrap",
+    epilog="""\b
+Examples:
+  tweek proxy wrap openclaw "npm start"                     Wrap a Node.js app
+  tweek proxy wrap cursor "/Applications/Cursor.app/Contents/MacOS/Cursor"
+  tweek proxy wrap myapp "python serve.py" -o run.sh       Custom output path
+  tweek proxy wrap myapp "npm start" --port 8080           Use custom proxy port
+""",
+)
+@click.argument("app_name")
+@click.argument("command")
+@click.option("--output", "-o", help="Output script path (default: ./run-{app_name}-protected.sh)")
+@click.option("--port", "-p", default=9877, help="Proxy port")
+def proxy_wrap(app_name: str, command: str, output: str, port: int):
+    """Generate a wrapper script to run an app through the proxy."""
+    from tweek.proxy.server import generate_wrapper_script
+
+    if output:
+        output_path = Path(output)
+    else:
+        output_path = Path(f"./run-{app_name}-protected.sh")
+
+    script = generate_wrapper_script(command, port=port, output_path=output_path)
+
+    console.print(f"[green]\u2713[/green] Created wrapper script: {output_path}")
+    console.print()
+    console.print("[bold]Usage:[/bold]")
+    console.print(f"  chmod +x {output_path}")
+    console.print(f"  ./{output_path.name}")
+    console.print()
+    console.print("[white]The script will:[/white]")
+    console.print("[white]  1. Start Tweek proxy if not running[/white]")
+    console.print("[white]  2. Set proxy environment variables[/white]")
+    console.print(f"[white]  3. Run: {command}[/white]")
+
+
+# ------------------------------------------------------------------
+# tweek proxy setup
+# ------------------------------------------------------------------
+
+@proxy.command(
+    "setup",
+    epilog="""\b
+Examples:
+  tweek proxy setup                      Launch interactive proxy setup wizard
+""",
+)
+def proxy_setup():
+    """Interactive setup wizard for the HTTP proxy.
+
+    Walks through:
+      1. Detecting LLM tools to protect
+      2. Generating and trusting CA certificate
+      3. Configuring shell environment variables
+    """
+    console.print()
+    console.print("[bold]HTTP Proxy Setup[/bold]")
+    console.print("\u2500" * 30)
+    console.print()
+
+    # Check dependencies
+    try:
+        from tweek.proxy import PROXY_AVAILABLE, PROXY_MISSING_DEPS
+    except ImportError:
+        print_error(
+            "Proxy module not available",
+            fix_hint="Install with: pip install tweek[proxy]",
+        )
+        return
+
+    if not PROXY_AVAILABLE:
+        print_error(
+            "Proxy dependencies not installed",
+            fix_hint="Install with: pip install tweek[proxy]",
+        )
+        return
+
+    # Step 1: Detect tools
+    console.print("[bold cyan]Step 1/3: Detect LLM Tools[/bold cyan]")
+    try:
+        from tweek.proxy import detect_supported_tools
+
+        with spinner("Scanning for LLM tools"):
+            tools = detect_supported_tools()
+
+        detected = [(name, info) for name, info in tools.items() if info]
+        if detected:
+            for name, info in detected:
+                print_success(f"Found {name.capitalize()}")
+        else:
+            print_warning("No LLM tools detected. You can still set up the proxy manually.")
+    except Exception as e:
+        print_warning(f"Could not detect tools: {e}")
+    console.print()
+
+    # Step 2: CA Certificate
+    console.print("[bold cyan]Step 2/3: CA Certificate[/bold cyan]")
+    setup_cert = click.confirm("Generate and trust Tweek CA certificate?", default=True)
+    if setup_cert:
+        try:
+            from tweek.proxy.cert import generate_ca, trust_ca
+
+            with spinner("Generating CA certificate"):
+                generate_ca()
+            print_success("CA certificate generated")
+
+            with spinner("Installing to system trust store"):
+                trust_ca()
+            print_success("Certificate trusted")
+        except ImportError:
+            print_warning("Certificate module not available. Run: tweek proxy trust")
+        except Exception as e:
+            print_warning(f"Could not set up certificate: {e}")
+            console.print("  [white]You can do this later with: tweek proxy trust[/white]")
+    else:
+        console.print("  [white]Skipped. Run 'tweek proxy trust' later.[/white]")
+    console.print()
+
+    # Step 3: Shell environment
+    console.print("[bold cyan]Step 3/3: Environment Variables[/bold cyan]")
+    port = click.prompt("Proxy port", default=9877, type=int)
+
+    shell_rc = _detect_shell_rc()
+    if shell_rc:
+        console.print(f"  Detected shell config: {shell_rc}")
+        console.print(f"  Will add:")
+        console.print(f"    export HTTP_PROXY=http://127.0.0.1:{port}")
+        console.print(f"    export HTTPS_PROXY=http://127.0.0.1:{port}")
+        console.print()
+
+        apply_env = click.confirm(f"Add to {shell_rc}?", default=True)
+        if apply_env:
+            try:
+                rc_path = Path(shell_rc).expanduser()
+                with open(rc_path, "a") as f:
+                    f.write(f"\n# Tweek proxy environment\n")
+                    f.write(f"export HTTP_PROXY=http://127.0.0.1:{port}\n")
+                    f.write(f"export HTTPS_PROXY=http://127.0.0.1:{port}\n")
+                print_success(f"Added to {shell_rc}")
+                console.print(f"  [white]Restart your shell or run: source {shell_rc}[/white]")
+            except Exception as e:
+                print_warning(f"Could not write to {shell_rc}: {e}")
+        else:
+            console.print("  [white]Skipped. Set HTTP_PROXY and HTTPS_PROXY manually.[/white]")
+    else:
+        console.print("  [white]Could not detect shell config file.[/white]")
+        console.print(f"  Add these to your shell profile:")
+        console.print(f"    export HTTP_PROXY=http://127.0.0.1:{port}")
+        console.print(f"    export HTTPS_PROXY=http://127.0.0.1:{port}")
+
+    console.print()
+    console.print("[bold green]Proxy configured![/bold green]")
+    console.print("  Start with: [cyan]tweek proxy start[/cyan]")
+    console.print()
+
+
+# ------------------------------------------------------------------
+# Helper (only used by proxy_setup)
+# ------------------------------------------------------------------
+
+def _detect_shell_rc() -> str:
+    """Detect the user's shell config file."""
+    shell = os.environ.get("SHELL", "")
+    home = Path.home()
+
+    if "zsh" in shell:
+        return "~/.zshrc"
+    elif "bash" in shell:
+        if (home / ".bash_profile").exists():
+            return "~/.bash_profile"
+        return "~/.bashrc"
+    elif "fish" in shell:
+        return "~/.config/fish/config.fish"
+    return ""

tweek/cli_security.py

@@ -0,0 +1,236 @@
+"""CLI commands for break-glass overrides and false-positive feedback.
+
+Extracted from cli.py to keep the main CLI module manageable.
+Groups:
+    override_group  -- break-glass override create / list / clear
+    feedback_group  -- false-positive reporting, stats, reset
+"""
+
+import sys
+from typing import Optional
+
+import click
+from rich.table import Table
+
+from tweek.cli_helpers import console
+
+# =========================================================================
+# BREAK-GLASS OVERRIDE COMMANDS
+# =========================================================================
+
+
+@click.group("override")
+def override_group():
+    """Break-glass override for hard-blocked patterns.
+
+    When graduated enforcement blocks a pattern with "deny" (critical +
+    deterministic), use these commands to create a temporary override.
+
+    Overrides downgrade "deny" to "ask" — you still see the prompt and
+    must explicitly approve. Every use is logged for audit.
+    """
+    pass
+
+
+@override_group.command("create")
+@click.option("--pattern", required=True, help="Pattern name to override (e.g., ssh_key_read)")
+@click.option("--once", "mode", flag_value="once", default=True, help="Single-use override (consumed on first use)")
+@click.option("--duration", "duration_minutes", type=int, default=None, help="Duration in minutes (overrides --once)")
+@click.option("--reason", default="", help="Reason for the override (logged for audit)")
+def override_create(pattern: str, mode: str, duration_minutes: Optional[int], reason: str):
+    """Create a break-glass override for a hard-blocked pattern."""
+    from tweek.hooks.break_glass import create_override
+
+    if duration_minutes:
+        mode = "duration"
+
+    override = create_override(pattern, mode=mode, duration_minutes=duration_minutes, reason=reason)
+
+    # Log the creation
+    try:
+        from tweek.logging.security_log import get_logger, EventType, SecurityEvent
+        logger = get_logger()
+        logger.log(SecurityEvent(
+            event_type=EventType.BREAK_GLASS,
+            tool_name="tweek_cli",
+            decision="override_created",
+            decision_reason=f"Break-glass override created for '{pattern}'",
+            metadata={
+                "pattern": pattern,
+                "mode": mode,
+                "duration_minutes": duration_minutes,
+                "reason": reason,
+            },
+        ))
+    except Exception:
+        pass
+
+    console.print(f"[bold green]Break-glass override created[/bold green]")
+    console.print(f"  Pattern: [bold]{pattern}[/bold]")
+    console.print(f"  Mode: {mode}")
+    if duration_minutes:
+        console.print(f"  Expires: {override.get('expires_at', 'N/A')}")
+    if reason:
+        console.print(f"  Reason: {reason}")
+    console.print()
+    console.print("[white]Next time this pattern triggers, you'll see an 'ask' prompt instead of a hard block.[/white]")
+
+
+@override_group.command("list")
+def override_list():
+    """List all break-glass overrides (active and historical)."""
+    from tweek.hooks.break_glass import list_overrides, list_active_overrides
+
+    all_overrides = list_overrides()
+    active = list_active_overrides()
+    active_patterns = {o["pattern"] for o in active}
+
+    if not all_overrides:
+        console.print("[white]No break-glass overrides found.[/white]")
+        return
+
+    table = Table(title="Break-Glass Overrides")
+    table.add_column("Pattern", style="bold")
+    table.add_column("Mode")
+    table.add_column("Status")
+    table.add_column("Reason")
+    table.add_column("Created")
+
+    for o in all_overrides:
+        if o["pattern"] in active_patterns and not o.get("used"):
+            status = "[green]active[/green]"
+        elif o.get("used"):
+            status = "[white]consumed[/white]"
+        else:
+            status = "[white]expired[/white]"
+
+        table.add_row(
+            o["pattern"],
+            o["mode"],
+            status,
+            o.get("reason", ""),
+            o.get("created_at", "")[:19],
+        )
+
+    console.print(table)
+    console.print(f"\n[bold]{len(active)}[/bold] active override(s)")
+
+
+@override_group.command("clear")
+@click.option("--confirm", is_flag=True, help="Skip confirmation prompt")
+def override_clear(confirm: bool):
+    """Remove all break-glass overrides."""
+    from tweek.hooks.break_glass import clear_overrides
+
+    if not confirm:
+        if not sys.stdin.isatty():
+            console.print("[red]Use --confirm to clear overrides in non-interactive mode.[/red]")
+            return
+        if not click.confirm("Clear all break-glass overrides?"):
+            return
+
+    count = clear_overrides()
+    console.print(f"[bold]Cleared {count} override(s).[/bold]")
+
+
+# =========================================================================
+# FEEDBACK COMMANDS
+# =========================================================================
+
+
+@click.group("feedback")
+def feedback_group():
+    """False-positive feedback and pattern performance tracking.
+
+    Report false positives, view per-pattern FP rates, and manage
+    automatic severity demotions for noisy patterns.
+    """
+    pass
+
+
+@feedback_group.command("fp")
+@click.argument("pattern_name")
+@click.option("--context", default="", help="Description of the false positive context")
+def feedback_fp(pattern_name: str, context: str):
+    """Report a false positive for a pattern."""
+    from tweek.hooks.feedback import report_false_positive
+
+    result = report_false_positive(pattern_name, context=context)
+
+    # Log the report
+    try:
+        from tweek.logging.security_log import get_logger, EventType, SecurityEvent
+        logger = get_logger()
+        logger.log(SecurityEvent(
+            event_type=EventType.FALSE_POSITIVE_REPORT,
+            tool_name="tweek_cli",
+            pattern_name=pattern_name,
+            decision="fp_reported",
+            decision_reason=f"False positive reported for '{pattern_name}'",
+            metadata={
+                "context": context,
+                "fp_rate": result.get("fp_rate"),
+                "total_triggers": result.get("total_triggers"),
+                "false_positives": result.get("false_positives"),
+            },
+        ))
+    except Exception:
+        pass
+
+    console.print(f"[bold green]False positive recorded[/bold green] for [bold]{pattern_name}[/bold]")
+    console.print(f"  FP rate: {result.get('fp_rate', 0):.1%} ({result.get('false_positives', 0)}/{result.get('total_triggers', 0)})")
+
+    if result.get("auto_demoted"):
+        console.print(f"  [yellow]Auto-demoted:[/yellow] {result.get('original_severity')} -> {result.get('current_severity')}")
+
+
+@feedback_group.command("stats")
+@click.option("--above-threshold", is_flag=True, help="Show only patterns exceeding 5% FP rate")
+def feedback_stats(above_threshold: bool):
+    """Show false-positive rates per pattern."""
+    from tweek.hooks.feedback import get_stats
+
+    stats = get_stats()
+    if not stats:
+        console.print("[white]No feedback data recorded yet.[/white]")
+        return
+
+    table = Table(title="Pattern FP Statistics")
+    table.add_column("Pattern", style="bold")
+    table.add_column("Triggers", justify="right")
+    table.add_column("FPs", justify="right")
+    table.add_column("FP Rate", justify="right")
+    table.add_column("Demoted?")
+
+    for name, data in sorted(stats.items(), key=lambda x: x[1].get("fp_rate", 0), reverse=True):
+        fp_rate = data.get("fp_rate", 0)
+        if above_threshold and fp_rate < 0.05:
+            continue
+
+        rate_style = "red" if fp_rate >= 0.05 else "green"
+        demoted = "[yellow]yes[/yellow]" if data.get("auto_demoted") else "no"
+
+        table.add_row(
+            name,
+            str(data.get("total_triggers", 0)),
+            str(data.get("false_positives", 0)),
+            f"[{rate_style}]{fp_rate:.1%}[/{rate_style}]",
+            demoted,
+        )
+
+    console.print(table)
+
+
+@feedback_group.command("reset")
+@click.argument("pattern_name")
+def feedback_reset(pattern_name: str):
+    """Reset FP tracking and undo auto-demotion for a pattern."""
+    from tweek.hooks.feedback import reset_pattern
+
+    result = reset_pattern(pattern_name)
+    if result:
+        console.print(f"[bold]Reset feedback data for '{pattern_name}'[/bold]")
+        if result.get("was_demoted"):
+            console.print(f"  Restored severity: {result.get('original_severity')}")
+    else:
+        console.print(f"[white]No feedback data found for '{pattern_name}'.[/white]")